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

Compare Debian VPS Plans

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 chat server on Debian VPS.