Install and Configure Matrix Synapse on

Backups and Maintenance

Reliable backup and regular maintenance are key to the stability and longevity of your Matrix server.

What to Back Up

For a full recovery of Matrix Synapse, you will need:

• PostgreSQL Database: Contains all messages, metadata, users, and rooms. This is the most critical component.
• Synapse Media Store: The directory where Synapse stores all user-uploaded files (images, videos, documents). This is usually /var/lib/matrix-synapse/media_store.
• Synapse Configuration File: /etc/matrix-synapse/homeserver.yaml and other files in this directory (e.g., log.yaml).
• Caddy Configuration: /etc/caddy/Caddyfile and certificates (although Caddy will restore them itself).

Simple Auto-Backup Script

Let's create a simple script for automatic backups. We will use pg_dump for the database and tar for files.

sudo mkdir -p /opt/backups/matrix # Create directory for backups
sudo chown matrixuser:matrixuser /opt/backups/matrix # Grant permissions to our user
nano /opt/backups/matrix/backup_matrix.sh
    

Insert the following content into the backup_matrix.sh file:

#!/bin/bash

# Settings
BACKUP_DIR="/opt/backups/matrix"
DATE=$(date +%Y%m%d%H%M%S)
DB_USER="synapse_user"
DB_NAME="synapse_db"
DB_PASSWORD="YOUR_STRONG_PASSWORD" # Use the same password as when configuring PostgreSQL
SYNAPSE_CONFIG_DIR="/etc/matrix-synapse"
SYNAPSE_MEDIA_DIR="/var/lib/matrix-synapse/media_store"
CADDY_CONFIG_DIR="/etc/caddy"

# Stop Synapse for a consistent DB backup (optional, but recommended for large databases)
# sudo systemctl stop matrix-synapse

# PostgreSQL Database Backup
echo "Dumping PostgreSQL database..."
PGPASSWORD="${DB_PASSWORD}" pg_dump -U "${DB_USER}" -h localhost "${DB_NAME}" > "${BACKUP_DIR}/synapse_db_${DATE}.sql"
if [ $? -eq 0 ]; then
    echo "Database backup successful: ${BACKUP_DIR}/synapse_db_${DATE}.sql"
else
    echo "Database backup failed!"
    exit 1
fi

# Media Store and Config Backup
echo "Archiving media store and configurations..."
tar -czf "${BACKUP_DIR}/synapse_data_config_${DATE}.tar.gz" "${SYNAPSE_MEDIA_DIR}" "${SYNAPSE_CONFIG_DIR}" "${CADDY_CONFIG_DIR}"
if [ $? -eq 0 ]; then
    echo "Data and config backup successful: ${BACKUP_DIR}/synapse_data_config_${DATE}.tar.gz"
else
    echo "Data and config backup failed!"
    exit 1
fi

# Start Synapse back up
# sudo systemctl start matrix-synapse

# Delete old backups (keep for 7 days)
find "${BACKUP_DIR}" -type f -name "*.sql" -mtime +7 -delete
find "${BACKUP_DIR}" -type f -name "*.tar.gz" -mtime +7 -delete

echo "Backup process finished."
    

Make the script executable:

chmod +x /opt/backups/matrix/backup_matrix.sh
    

For automatic execution, add it to cron. Run the command as user matrixuser:

crontab -e
    

Add the following line for a daily backup at 3 AM:

0 3 * * * /opt/backups/matrix/backup_matrix.sh > /dev/null 2>&1
    

Where to Store Backups

Storing backups on the same server as the original data is highly discouraged. In case of hardware failure or server compromise, you will lose everything. It is recommended to use:

• External S3-compatible storage: For example, AWS S3, Backblaze B2, or MinIO. For this, you can use utilities like s3cmd or rclone in your script.
• Separate VPS: You can set up a second, small VPS and use rsync or scp to copy backups there.
• Local storage on your machine: If the server is not critical and you can perform manual copying.

For more advanced backup solutions, consider tools like Restic or BorgBackup, which support deduplication, encryption, and various storage backends.

Updates: rolling vs maintenance window

• Rolling updates: For Matrix Synapse, "rolling updates" are typically used – meaning you simply update packages and restart the service. Synapse is designed to be quite resilient to such updates.
• Maintenance window: For major PostgreSQL or operating system updates, as well as for Synapse database migrations (which are rare), it is recommended to plan a "maintenance window" when the server will be unavailable. Inform users in advance.

It is recommended to regularly (once a month) update the system:

sudo apt update && sudo apt upgrade -y
sudo apt autoremove -y
sudo systemctl restart matrix-synapse # Restart Synapse after updating system libraries
sudo systemctl restart caddy # Restart Caddy if there were updates
    

Also, keep an eye on Matrix Synapse project news for information on critical updates and new versions.

Troubleshooting + FAQ

In this section, we will cover common issues you might encounter when setting up Matrix Synapse and provide answers to frequently asked questions.

Federation is not working (cannot communicate with other servers)

What to check:

• DNS SRV records: Ensure that _matrix._tcp.yourdomain.com and _matrix-federation._tcp.yourdomain.com correctly point to your server and port 8448. Use dig SRV _matrix._tcp.yourdomain.com.
• Firewall (UFW): Ensure that port 8448 is open for incoming connections: sudo ufw status.
• Caddy/Nginx: Check web server logs. Ensure it correctly proxies requests to /_matrix/federation/ to Synapse (port 8008).
• Synapse Logs: Check Synapse logs for federation errors: sudo journalctl -u matrix-synapse -f. Look for messages related to "federation" or "remote server".
• .well-known files: Ensure that https://yourdomain.com/.well-known/matrix/server and https://yourdomain.com/.well-known/matrix/client are accessible and return correct JSON pointing to your server_name.

How to fix: Correct DNS records, open ports in the firewall, check Caddy/Nginx configuration for proxying errors. For .well-known files, if your server_name differs from the root domain, ensure your web server correctly redirects requests to these paths to the domain where Synapse is installed.

Clients cannot connect to the server

What to check:

• HTTPS: Ensure your domain is accessible via HTTPS (port 443) and the certificate is valid. Check via browser or curl -v https://matrix.yourdomain.com/.
• Caddy/Nginx: Check web server logs. Ensure that requests to /_matrix/client/ are proxied to Synapse.
• Synapse Logs: Look for errors related to "client" or "connection".
• Port 8008: Ensure that Synapse is listening on port 8008 (or another if you changed it) and is accessible to the web server (netstat -tulnp | grep 8008).

How to fix: Resolve HTTPS issues (Caddy might not have obtained a certificate), check proxying rules in Caddyfile, ensure Synapse is running and listening on the correct port. If you changed server_name in homeserver.yaml, ensure it matches the domain clients are trying to connect to.

Cannot register a new user

What to check:

• enable_registration: Check that the enable_registration parameter in /etc/matrix-synapse/homeserver.yaml is set to true. After changing, remember to restart Synapse.
• Synapse Logs: Check logs for registration errors.
• Spam protection: Synapse has built-in spam protection mechanisms that may block registration. Check the relevant settings.

How to fix: Set enable_registration: true and restart Synapse. If the problem persists, temporarily disable any spam protection in the config to check if it's the cause.

What is the minimum suitable VPS configuration?

For a small personal or family Matrix Synapse server (up to 10 active users), a minimum of 1-2 vCPU, 2 GB RAM, and a 40-60 GB NVMe SSD is required. This configuration will be sufficient for basic chat functions and a small number of media files. However, if you plan active use of voice/video calls or a large volume of message history, it is recommended to increase resources to 4 GB RAM and 80 GB SSD for more stable operation.

What to choose — VPS or dedicated for this task?

The choice between a VPS and a dedicated server depends on the scale of your project and performance requirements. For most personal, family, or small team deployments (up to several hundred users), a VPS will be an optimal and cost-effective solution. It offers sufficient flexibility and performance. A dedicated server becomes necessary if you plan to serve thousands of users, store terabytes of data, or if you have very strict requirements for resource isolation, performance, security, and regulatory compliance. Dedicated servers provide maximum control over hardware but come with higher costs and management complexity.

Server is slow or freezes

What to check:

• Resource usage: Use htop or top to monitor CPU and RAM. If Synapse or PostgreSQL consume too many resources, you might be lacking RAM or CPU.
• Synapse Logs: Check logs for warnings or errors indicating performance issues (e.g., slow DB queries).
• Disk subsystem: A slow disk (especially HDD or slow SATA SSD) can be a bottleneck. Ensure you have an NVMe SSD.
• PostgreSQL Indexes: For large databases, ensure that indexes are created and used efficiently. Synapse usually creates them itself, but manual optimization may sometimes be required.

How to fix: If you lack RAM or CPU, consider upgrading your VPS. If the problem is with the disk, ensure you are using an NVMe SSD. Check PostgreSQL and Synapse configurations for inefficient settings. It might be worthwhile to clear old media files or chat history if they are taking up too much space.

Conclusions and Next Steps

Congratulations! You have successfully installed and configured your own Matrix Synapse server on a VPS. You now have a fully controlled and private communication platform that provides secure communication for you and your users, and also allows interaction with other Matrix servers worldwide. You have gained valuable experience in deploying and managing complex network services.

Where to go next?

• Integration with other services: Explore Matrix Bridges to connect to other chat platforms such as Telegram, Discord, IRC, Slack. This will allow your users to communicate with people on these platforms directly from your Matrix server.
• Performance optimization: For large installations, consider using Prometheus and Grafana to monitor server resources and Synapse performance. Optimize PostgreSQL and Synapse settings to improve operational speed.
• Additional features: Explore the possibility of adding voice/video calls via your own STUN/TURN servers (e.g., Coturn) to improve communication quality, especially if users are behind NAT.