Synapse on Linux: Complete guide to install and configure your own Matrix server

Introduction

Synapse is the reference implementation of the Matrix server, an open protocol for decentralized real‑time communication. Installing Synapse on a Linux system lets you create your own chat, video‑call, and collaboration environment without relying on central services. This article shows step‑by‑step how to prepare the environment, install dependencies, configure Synapse, and keep it secure.

Prerequisites

You need a recent Linux distribution (Ubuntu 22.04 LTS, Debian 12, or Fedora 38) with root or sudo access, at least 2 GB of RAM and 20 GB of disk space. It is recommended to have a domain name pointing to the server’s IP and a valid TLS certificate (e.g., from Let’s Encrypt).

System Dependencies

On Debian/Ubuntu:

sudo apt update
sudo apt install -y python3-pip python3-virtualenv libffi-dev libssl-dev build-essential
sudo apt install -y libjpeg-turbo8-dev libpng-dev libwebp-dev

On Fedora:

sudo dnf install -y python3-pip python3-virtualenv gcc libffi-devel openssl-devel make
sudo dnf install -y libjpeg-turbo-devel libpng-devel libwebp-devel

Create a Virtual Environment

To isolate the installation, create a directory and a virtual environment:

sudo mkdir -p /opt/synapse
sudo chown $USER:$USER /opt/synapse
cd /opt/synapse
python3 -m venv env
source env/bin/activate

Install Synapse

With the environment activated, install Synapse and the PostgreSQL adapter:

pip install --upgrade pip setuptools wheel
pip install synapse[postgres]

Generate the Initial Configuration

Run the configuration creation command:

python -m synapse.app.homeserver --server-name mi.dominio.com --config-path homeserver.yaml --generate-config --report-stats=no

This will produce homeserver.yaml and homeserver.signing.key. Edit the YAML to:

Define listeners (port 8008, optionally TLS).
Configure the database section with your PostgreSQL details.
Set registration_shared_secret to a random value.
Decide whether to allow open registrations (enable_registration: true) or only via invitations.

Configure PostgreSQL

If using PostgreSQL, create the database and user:

sudo -u postgres psql
Inside psql: CREATE DATABASE synapse;
CREATE USER synapse_user WITH PASSWORD 'tu_contraseña_segura';
GRANT ALL PRIVILEGES ON DATABASE synapse TO synapse_user;
\q

Then adjust the database section of homeserver.yaml with those credentials.

Run Synapse as a Service

Create a systemd unit file so Synapse starts at boot:

sudo nano /etc/systemd/system/synapse.service

Content:

[Unit]
Description=Synapse Matrix Homeserver
After=network.target

[Service]
Type=simple
User=tu_usuario
WorkingDirectory=/opt/synapse
Environment="PATH=/opt/synapse/env/bin"
ExecStart=/opt/synapse/env/bin/python -m synapse.app.homeserver --config-path /opt/synapse/homeserver.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

Replace tu_usuario with the user that owns /opt/synapse. Then:

sudo systemctl daemon-reload
sudo systemctl enable synapse.service
sudo systemctl start synapse.service
sudo systemctl status synapse.service

Security and Best Practices

Use a Let’s Encrypt TLS certificate and set tls_certificate_path and tls_private_key_path in the YAML.
Restrict access to port 8008 (or 443 if using a reverse proxy) with ufw or firewalld.
Disable open registration (enable_registration: false) and use invitations or SSO.
Configure log rotation with logrotate.
Keep the environment up‑to‑date: pip install --upgrade synapse inside the environment and restart the service.

Monitoring and Maintenance

Synapse exposes metrics at /_synapse/metrics for Prometheus. The file homeserver.log contains error and warning information. Set up logrotate:

sudo nano /etc/logrotate.d/synapse
Content:

/opt/synapse/homeserver.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}

To update, reactivate the environment, run pip install --upgrade synapse, and restart with sudo systemctl restart synapse.service.

Conclusion

Installing Synapse on Linux is an accessible process that gives you full control over your Matrix‑based communication. Following the steps above you will have a secure server ready to integrate bridges, bots, and collaboration tools. Feel free to deploy your own node and contribute to the decentralized secure messaging network.

This post is also available in ESPAÑOL.