
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:
-
📦 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.
-
🧱 Add Matrix Synapse Repository
Matrix provides an official APT repository.
- 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
- 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
- Update package index:
sudo apt update
- Add the GPG key:
-
🏗️ 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. - Enter your FQDN (e.g.,
-
🔐 Secure with TLS (Let’s Encrypt + NGINX)
- Install NGINX and Certbot:
sudo apt install nginx certbot python3-certbot-nginx -y
- 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; } }
- Enable and test NGINX:
sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix sudo nginx -t sudo systemctl reload nginx
- Obtain SSL certificate:
sudo certbot --nginx -d matrix.example.com
- Install NGINX and Certbot:
-
🌐 Add Well-Known Delegation
To help Matrix federation find your server, you should host a
.well-known
file.- 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; }
- Reload NGINX:
sudo systemctl reload nginx
- Edit NGINX config (add this inside port 443 server block):
-
👤 Create an Admin User
- 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.
- Register your first user:
-
🧪 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
- Homeserver URL:
-
🔁 Enable Federation (Optional but Recommended)
To allow your server to communicate with other Matrix homeservers:
- Ensure port 8448/tcp is open in your firewall and router.
- Add DNS SRV record or host
matrix.example.com
to point to the same IP as your homeserver. - Validate federation at:
-
🛡️ 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
-
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
). -
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
Task | Status |
---|---|
Debian system updated | ✅ |
Domain pointed to VPS | ✅ |
Matrix Synapse installed | ✅ |
TLS enabled via Let’s Encrypt | ✅ |
Admin user created | ✅ |
Federation enabled (port 8448 open) | ✅ |
Well-known endpoints configured | ✅ |
NGINX reverse proxy configured | ✅ |
🔗 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.