How do I run a Matrix Synapse server on a VPS?

What do I have to decide before installing Synapse?

The server name comes first. It is the part after the colon in every user ID and room alias, as in @alice:example.com, and Synapse's installation guide says it cannot be changed later. Pick the domain you will keep for years, not the hostname of the VPS.

The server name and the machine can differ. With delegation, example.com stays the name while Synapse runs on matrix.example.com: you serve a small JSON file at https://example.com/.well-known/matrix/server, and other homeservers follow it. Without that file, they try your server name on port 8448.

Settle two more things now. Will strangers be able to sign up, or will you create accounts by hand? Will the server federate with the rest of the Matrix network, or stay private? Both answers shape the configuration and the work that follows. Before any of it, secure the VPS: SSH keys, updates, a firewall.

{
  "m.server": "matrix.example.com:443"
}

How do I install Synapse on Debian or Ubuntu?

Use the packages the Synapse team publishes at packages.matrix.org. On 3 November 2026 the repository carried 1.164.2 for Debian 13 (trixie) and 12 (bookworm) and for Ubuntu 24.04 (noble) and 22.04 (jammy), four of the images offered with every plan: Debian 13, Debian 12, Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, AlmaLinux 10, Rocky Linux 10. The packages are built for amd64.

The package asks for the server name during installation and writes the main configuration to /etc/matrix-synapse/homeserver.yaml. Put your own settings in separate files under /etc/matrix-synapse/conf.d/: package upgrades then never ask whether to replace your configuration.

sudo apt install -y lsb-release wget apt-transport-https
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg \
  https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
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
sudo apt update
sudo apt install matrix-synapse-py3

Why PostgreSQL rather than SQLite?

Synapse's documentation says almost all installations should use PostgreSQL, and that SQLite should not be used on a production server. SQLite is fine for a test you will throw away. Moving a live server to PostgreSQL later means a migration with downtime, so start with it.

Create a database user and a database with the C locale, as the Synapse PostgreSQL guide asks, then point Synapse at it from a file in conf.d and restart the service.

sudo apt install postgresql
sudo -u postgres createuser --pwprompt synapse_user
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

database:
  name: psycopg2
  args:
    user: synapse_user
    password: "the-password-you-chose"
    dbname: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

Which ports and reverse proxy does Synapse need?

Synapse listens on localhost:8008 over plain HTTP; nginx in front of it handles TLS. Clients connect on 443. Other homeservers use 8448 by default, or 443 when your .well-known file says so. In the firewall, open 22 for SSH, 80 for the Let's Encrypt challenge, 443, and 8448 only if you skip delegation.

Two settings are easy to miss. nginx refuses request bodies over 1 MB by default, so raise client_max_body_size to match Synapse's max_upload_size, which defaults to 50M. And set x_forwarded: true on the 8008 listener in homeserver.yaml, so Synapse sees the real client address instead of 127.0.0.1.

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    # federation on 8448: drop these two lines if you delegate to 443
    listen 8448 ssl default_server;
    listen [::]:8448 ssl default_server;
    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|/_synapse/client) {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        client_max_body_size 50M;
        proxy_http_version 1.1;
    }
}

How do I create the first account and keep sign-ups closed?

Create accounts from the server itself with register_new_matrix_user. It talks to the running Synapse and authenticates with registration_shared_secret; if your configuration has none, add one in a conf.d file and restart. Synapse's guide warns that anyone who holds this secret can create accounts, admins included, even with registration closed. Keep it out of repositories, tickets and chats.

Leave enable_registration: false unless you want an open server, which brings spam sign-ups and moderation work.

Voice and video calls are the other gap on a fresh install. Synapse's documentation says reliable VoIP through your homeserver needs a TURN server, usually coturn on the same VPS or another one.

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

How does Synapse send email when port 25 is closed?

Through a mail provider on a submission port. Outbound port 25 is closed on every VPS and is not opened on request; send mail through a mail provider on port 465 or 587. Synapse uses mail for password resets, address verification and notifications, and it works with any provider that accepts authenticated mail on 587 (STARTTLS) or 465 (TLS from the first byte).

Set the port explicitly. When smtp_port is left empty, Synapse picks 25, or 465 if force_tls is true. For 465, write smtp_port: 465 and force_tls: true instead of the STARTTLS line below.

email:
  smtp_host: smtp.your-provider.example
  smtp_port: 587
  smtp_user: "[email protected]"
  smtp_pass: "app-password-from-the-provider"
  require_transport_security: true
  notif_from: "Matrix on example.com <[email protected]>"

Which plan fits a Synapse server?

Start from Synapse's own figure: at least 1 GB of free RAM to join large public rooms. PostgreSQL, nginx and the system need memory on top of that, and a server that joins big federated rooms stores their state in its database. The rows below are starting points derived from that figure, not load tests. The vCPU of every plan are shared: they are scheduled on physical cores that neighbouring VPS also use. The RAM and NVMe space of your plan are reserved for your VPS only.

What do I back up?

Three things, copied off the VPS. No plan includes backups, so keep your own copy of anything that matters.

• The database, with pg_dump: users, rooms, messages and room state.
• The media store, the directory set by media_store_path: every uploaded file and avatar.
• The signing key, the file set by signing_key_path: it identifies your server to the rest of the federation, so a restore without it looks like a different server.

Keep the configuration files in conf.d with them. A copy on the same disk does not survive the loss of the VPS; the migration guide shows how to move the same set to a new server.