How to Install and Run Matrix Synapse Chat Server on Debian VPS

This article provides a guide detailing how to install and run Matrix Synapse chat server on Debian VPS.

What is Matrix Synapse?

Matrix Synapse is the reference implementation of a homeserver for the Matrix protocol.

What Matrix Is

Matrix is an open standard and protocol for secure, decentralized real-time communication. It’s used for things like instant messaging, VoIP (voice and video calls), and bridging between different chat platforms (Slack, Discord, IRC, etc.).

What Synapse Does

• Synapse is a server software (written in Python, using Twisted) that implements the Matrix protocol.
• It allows users to register accounts, join chat rooms, send/receive messages, and federate (communicate) with other Matrix servers around the world.
• Because Matrix is decentralized (like email), Synapse can talk to other Matrix homeservers so users on different servers can message each other.

Key Features

• End-to-end encryption (via the Olm/Megolm cryptographic ratchets).
• Federation with other homeservers using HTTPS APIs.
• Bridges to external services (Slack, IRC, Telegram, Discord, etc.).
• Identity management with user IDs (e.g. @user:example.com).
• Extensible: supports bots, integrations, and custom modules.

Why Synapse Matters

• It was the first and remains the most widely deployed Matrix homeserver.
• It’s considered the “reference implementation” (used to define and test the Matrix spec).
• Other homeserver implementations exist (like Dendrite in Go, or Conduit in Rust), but Synapse is still the most feature-complete and commonly used.

👉 In practice: If you want to host your own Matrix server (like hosting your own email server), you’d typically install Synapse.

This guide walks you through a complete installation and configuration of Matrix Synapse on a Debian 12 (Bookworm) VPS.

📋 Prerequisites

Before proceeding, ensure the following:

• A Debian 12 VPS (1GB RAM minimum, 2GB+ recommended)
• A fully qualified domain name (FQDN) (e.g., matrix.example.com)
• Root (sudo) access to the server
• Ports 80, 443, and 8448 open in your firewall
• A valid SSL certificate (we’ll use Let’s Encrypt)
• Basic Linux command-line knowledge

How to Install and Run Matrix Synapse Server on Debian VPS

To install and run Matrix Synapse chat server on Debian VPS, follow the steps below:

1. 📦 Update and Prepare the System

   sudo apt update && sudo apt upgrade -y sudo apt install -y lsb-release wget gnupg2 curl apt-transport-https ca-certificates

   Ensure your system is up-to-date with all security patches and has the required packages.

2. 🧱 Add Matrix Synapse Repository

   Matrix provides an official APT repository.

   1. Add the GPG key:

      curl -fsSL https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg | sudo tee /usr/share/keyrings/matrix-org-archive-keyring.gpg > /dev/null

   2. Add the repository:

      echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list

   3. Update package index:

      sudo apt update

3. 🏗️ Install Synapse

   sudo apt install matrix-synapse-py3 -y
   

   You will be prompted to:

   • Enter your FQDN (e.g., matrix.example.com)
   • Decide whether to send anonymous usage stats (optional)

   This generates a config file at /etc/matrix-synapse/homeserver.yaml and a secret signing key.

4. 🔐 Secure with TLS (Let’s Encrypt + NGINX)

   1. Install NGINX and Certbot:

      sudo apt install nginx certbot python3-certbot-nginx -y

   2. Configure NGINX reverse proxy:

      sudo nano /etc/nginx/sites-available/matrix

      Paste this configuration (replace matrix.example.com with your domain):

      server { listen 80; server_name matrix.example.com; location /.well-known/acme-challenge/ { root /var/www/html; } location / { return 301 https://$host$request_uri; } } server { listen 443 ssl; server_name matrix.example.com; ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem; location /_matrix { proxy_pass http://localhost:8008; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header Host $host; } }

   3. Enable and test NGINX:

      sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix sudo nginx -t sudo systemctl reload nginx

   4. Obtain SSL certificate:

      sudo certbot --nginx -d matrix.example.com

5. 🌐 Add Well-Known Delegation

   To help Matrix federation find your server, you should host a .well-known file.

   1. Edit NGINX config (add this inside port 443 server block):

      location /.well-known/matrix/server { return 200 '{ "m.server": "matrix.example.com:443" }'; default_type application/json; } location /.well-known/matrix/client { return 200 '{ "m.homeserver": { "base_url": "https://matrix.example.com" } }'; default_type application/json; }

   2. Reload NGINX:

      sudo systemctl reload nginx

6. 👤 Create an Admin User

   1. Register your first user:

      sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008

      Enter a username and password, then answer yes when asked to make the user admin.

7. 🧪 Test the Server

   You can use a Matrix web client such as Element or host your own instance to connect.

   Login using:

   • Homeserver URL: https://matrix.example.com
   • Username: @youruser:matrix.example.com
   • Password: the one you set earlier

8. 🔁 Enable Federation (Optional but Recommended)

   To allow your server to communicate with other Matrix homeservers:

   1. Ensure port 8448/tcp is open in your firewall and router.
   2. Add DNS SRV record or host matrix.example.com to point to the same IP as your homeserver.
   3. Validate federation at:
      • https://federationtester.matrix.org

9. 🛡️ Secure and Harden

   • Change the default password regularly.
   • Monitor logs:

      sudo journalctl -u matrix-synapse -f

   • Backup your configuration and keys in /etc/matrix-synapse/.

🧰 Optional Enhancements

1. Install Element Web (Matrix client) on your domain

   You can self-host Element using:

   sudo apt install nginx unzip wget https://github.com/element-hq/element-web/releases/latest/download/element-web.zip unzip element-web.zip -d /var/www/element

   Configure NGINX and map it to a subdomain (e.g., chat.example.com).

2. Enable TURN Server for Media Calls

   Install and configure Coturn to support voice/video calls.

   sudo apt install coturn -y

   Configure it to run on ports 3478 and 5349, and link it in your Synapse config under turn_uris.

📚 Logs & Maintenance

• Synapse logs:

  /var/log/matrix-synapse/homeserver.log

• Restart Synapse:

  sudo systemctl restart matrix-synapse

• Upgrade Synapse:

  sudo apt update && sudo apt upgrade matrix-synapse-py3

✅ Final Checklist

🔗 Useful Links

• Matrix Synapse GitHub: https://github.com/matrix-org/synapse
• Official Docs: https://matrix-org.github.io/synapse
• Element Web Client: https://element.io

Conclusion

You now know how to install and run Matrix Synapse chatserver on Debian VPS.