Self-host a Matrix server (Synapse) on a VPS

To self-host a Matrix server, install Synapse from matrix.org's Debian packages, give it a PostgreSQL database, and put it behind a reverse proxy that serves the Matrix APIs and the .well-known files over HTTPS on port 443. On VPSNine the Matrix Synapse one-click app does the setup, and one command names the server, starts it and creates your admin account.

Decide on the server's name before anything else. It's part of every user ID (@you:matrix.example.com), and it can never change once Synapse has started.

What you need#

• The Standard plan (2 vCPU, 4 GB) or bigger. Synapse's install guide asks for at least 1 GB of free memory to join large rooms, and PostgreSQL runs alongside it. Joining big public rooms is what makes Synapse heavy; a private server for a family or team stays light.
• Ubuntu or Debian. matrix.org publishes Synapse packages for those only, so the one-click app isn't offered on AlmaLinux, Rocky Linux or Fedora.
• A domain or subdomain for the homeserver, like matrix.example.com.

Install it with the one-click app#

Order a server with the Matrix Synapse app. On its first boot we add matrix.org's package repository, download matrix-synapse-py3 and create a PostgreSQL database with the C collation Synapse requires. The database password is in /root/synapse-db.txt. Synapse isn't installed or running yet, because it needs its name first. One-click apps shows how to follow the install.

Then:

1. Choose the server's name. Point that domain's A record at the server, for example 203.0.113.10, and allow ports 80 and 443 in the panel firewall.

2. Log in over SSH and name the homeserver:

   bash

   vps9-https matrix.example.com

   Synapse starts, Caddy gets a certificate, and your admin login (@admin:matrix.example.com) is written to /root/matrix-admin.txt.

3. Sign in with Element or another Matrix app, with https://matrix.example.com as the homeserver.

4. Add people from the server. Open registration stays off:

   bash

   register_new_matrix_user -c /etc/matrix-synapse/conf.d/vps9.yaml http://127.0.0.1:8008

   It asks for the new user's name and password, and whether they should be an admin.

Synapse is ready when this answers OK on the server:

curl http://127.0.0.1:8008/health

Put it on your domain with HTTPS#

For Synapse, vps9-https does more than add HTTPS. It sets the homeserver's name to the domain you give it, installs Synapse, and writes its settings to /etc/matrix-synapse/conf.d/vps9.yaml: PostgreSQL as the database, registration off, and a registration secret that only root can read. It then creates the admin account and installs Caddy, which gets and renews the certificate.

Synapse itself listens on localhost only. Caddy, on ports 80 and 443, passes the client and federation APIs through to it and answers /.well-known/matrix/client and /.well-known/matrix/server itself. The server file tells other homeservers to federate on port 443, so port 8448 stays closed.

Federation works like email: servers your users talk to see the rooms and messages shared with them.

Doing it by hand on another server#

Synapse's installation guide covers every option. On Debian or Ubuntu, the outline is:

1. Add matrix.org's repository and install the package:

   bash

   apt install -y lsb-release wget apt-transport-https
   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" > /etc/apt/sources.list.d/matrix-org.list
   apt update
   apt install matrix-synapse-py3

   The package asks for the server name. Type the one you mean to keep.

2. Use PostgreSQL, not the default SQLite, which the guide says is only for testing. Create the database with --locale=C --template=template0.

3. Put your own settings in a file under /etc/matrix-synapse/conf.d/ rather than editing homeserver.yaml, so package upgrades don't ask to replace it. Set public_baseurl to your HTTPS address.

4. Put a reverse proxy with a certificate in front of localhost:8008, and serve /.well-known/matrix/client with a CORS header so clients can find the server.

Updates and backups#

Synapse updates with the system's packages from matrix.org's repository. The automatic security updates we turn on cover the operating system only, so upgrade Synapse yourself after reading its upgrade notes:

apt update
apt upgrade

Back up three things and copy them off the server:

• The PostgreSQL database:

  bash

  runuser -u postgres -- pg_dump -Fc synapse > /root/synapse-$(date +%F).dump

• /etc/matrix-synapse, which holds the signing key. Without it, a restored server can't prove it's the same homeserver to the rest of Matrix.

• /var/lib/matrix-synapse, which holds uploaded media.

Backups you should run shows how to copy them off nightly.

When it goes wrong#

• vps9-https says the homeserver is already named something else: a Matrix server's name can't change, and the helper refuses to rename it. Run vps9-https with the name it gives you. To use a different name you'd need a new server, with new user IDs for everyone.
• Other servers can't reach yours: enter your server name in the Matrix federation tester. Check that ports 80 and 443 are open, that DNS points at the server, and that https://matrix.example.com/.well-known/matrix/server answers from outside.
• An app can't find the homeserver: open https://matrix.example.com/.well-known/matrix/client in a browser. It should show the homeserver's address. If it doesn't load, Caddy has no certificate yet; journalctl -u caddy -n 30 says why.
• You want user IDs on your main domain: vps9-https names the server after the domain it serves. For @you:example.com with Synapse on a subdomain, the server name must be example.com and that domain must serve the .well-known files, as Synapse's delegation guide describes. Decide before the first start.