How to Self-Host a Matrix/Synapse Chat Server

Matrix is an open, federated protocol for secure, real-time chat — like running your own Slack or Discord that can also talk to the wider Matrix network. Synapse is the reference homeserver. This guide installs it with Docker, gets HTTPS and federation working, and connects the Element client. It's a more involved setup than most self-hosted apps, so follow each step.

How Matrix works

Your homeserver hosts your users (@you:example.com) and their rooms. Because Matrix federates, your users can chat with people on any other Matrix server, much like email between providers. That federation is what makes the DNS and TLS steps below important. If federation between servers reminds you of email, the parallels with how DNS works are real.

Prerequisites

• A VPS with 2 GB+ RAM and Docker installed — run Docker on a VPS.
• A domain you control, e.g. example.com, with an A record for matrix.example.com.

Generate the config

Use the official Synapse image to generate an initial config, setting your server name (this becomes part of every user ID, so choose carefully — it's hard to change later):

mkdir -p ~/synapse/data && cd ~/synapse
docker run -it --rm \
  -v $(pwd)/data:/data \
  -e SYNAPSE_SERVER_NAME=example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

Run Synapse with Compose

services:
  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    volumes:
      - ./data:/data
    ports:
      - "8008:8008"

docker compose up -d

Reverse proxy and federation

Element and other servers connect over HTTPS on 443, and federation uses port 8448. The simplest robust setup uses a well-known delegation so everything runs on 443. Front Synapse with Caddy:

matrix.example.com {
    reverse_proxy 127.0.0.1:8008
}

Then serve two .well-known files from your main domain so clients and servers know where to find your homeserver:

# https://example.com/.well-known/matrix/server
{ "m.server": "matrix.example.com:443" }

# https://example.com/.well-known/matrix/client
{ "m.homeserver": { "base_url": "https://matrix.example.com" } }

Open the firewall for web traffic:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Create your first user

Registration is closed by default (good). Create an admin user from the container:

docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -a http://localhost:8008

Then open the Element app or app.element.io, choose "other homeserver", enter https://matrix.example.com, and log in.

Check federation

Paste your server name into the online Matrix "Federation Tester". If the well-known files and TLS are correct, it reports all green and your users can now message anyone across the network.

Bridges: connect to other chat networks

One of Matrix's superpowers is bridging — relaying messages to and from other platforms so you can talk to contacts on Telegram, WhatsApp, Signal or IRC from your Matrix client. Bridges run as extra services alongside Synapse, each registered in the homeserver config. Start with one bridge, get it working end to end, then add others — running several at once increases the moderation and maintenance load noticeably.

Moderation, backups and upkeep

As the server admin you own a few ongoing tasks:

• Registration: keep open signups off (as configured) or add email verification and a CAPTCHA before opening up, or spam accounts will find you fast.
• Media and database growth: federated media and event history accumulate. Run Synapse's media-retention and state-compression tools periodically, and watch Postgres size.
• Backups: the Postgres database plus the data directory (which holds your signing keys and media) are what you must protect. Losing the signing keys effectively ends your server's identity, so back them up securely and separately.

Keep Synapse updated by pulling the latest image, and always read the release notes before a major version jump.

Clients, spaces and encryption

Your users aren't limited to one app. Element (web, desktop and mobile) is the flagship client, but the Matrix ecosystem has several alternatives, and they all connect to your homeserver the same way — enter https://matrix.example.com as the server and log in. Encourage users to verify their sessions so end-to-end encryption works smoothly across devices.

Two features make a self-hosted server feel like a real Slack or Discord replacement:

• Spaces group related rooms into a navigable hierarchy — perfect for organising a community or team by topic.
• End-to-end encryption can be enabled per room, so private conversations stay private even from you as the server admin. Remind users to back up their encryption keys, because encrypted history is unrecoverable without them.

Create a few starter rooms, set a friendly server description, and your homeserver is ready for people to join — either your own users or, thanks to federation, anyone across the wider Matrix network.

FAQ

Is running a Matrix server hard?

It's more involved than a single-container app because of federation, TLS and the well-known delegation. Follow the steps in order and it's very doable in an evening.

How much RAM does Synapse need?

Start at 2 GB. Synapse's memory use grows with the number and size of federated rooms you join, so add RAM if you join large public rooms.

Do I have to federate?

No. You can disable federation to keep your server private, in which case you can skip the well-known server file. Most people keep it on to reach the wider network.

Can I move my server name later?

Not easily — user IDs are tied to it. Pick your SYNAPSE_SERVER_NAME carefully before creating users.

Run your own encrypted chat on a capable NVMe VPS with full root access. Compare plans on the pricing page.