Matrix Synapse install guide

Introduction

The goal of this guide is to set up a docker installation of Synapse with Delegation and SQLite.

Throughout this guide domain.tld will be used as a placeholder domain for the Matrix server.

All container-related files will be organized under /srv/containers. This directory will contain two subdirectories:

boilerplates/ — stores compose.yaml files (service definitions).
compose/ — stores persistent data and configurations of said services.

DNS Setup

You will need to configure your domain name registrar (I recommend using Porkbun) to direct requests from domain.tld to your server’s IP address. Specifically, you’ll need to create the following A records:

domain.tld pointing to your server’s external IP address.
matrix.domain.tld also pointing to your server’s external IP address.

Don’t forget to configure port forwarding for ports 80 and 443 to route to your server’s internal IP.

Synapse

Generate a configuration file

mkdir -p /srv/containers/{boilerplates,compose}/synapse
mkdir -p /srv/containers/{boilerplates,compose}/caddy

docker network create caddy
docker run -it --rm \
  -v /srv/containers/compose/synapse/data:/data \
  -e SYNAPSE_SERVER_NAME=domain.tld \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

Create the Synapse service

1
services:
2
  synapse:
3
    image: ghcr.io/element-hq/synapse:latest
4
    container_name: synapse
5
    restart: always
6
    ports:
7
      - 8008:8008
8
    volumes:
9
      - /srv/containers/compose/synapse/data:/data
10
    networks:
11
      - caddy
12
networks:
13
  caddy:
14
    external: true

Create a server admin

cd /srv/containers/boilerplates/synapse
docker compose up -d
docker exec -it synapse register_new_matrix_user -c /data/homeserver.yaml

New user localpart: your_admin_username
Password: your_admin_password
Confirm password: your_admin_password
Make admin: yes

Caddy

We will be using Caddy as our reverse proxy

Create the Caddy service

1
services:
2
  caddy:
3
    image: docker.io/caddy:alpine
4
    container_name: caddy
5
    restart: always
6
    ports:
7
      - 80:80
8
      - 443:443
9
    volumes:
10
      - /srv/containers/compose/caddy/Caddyfile:/etc/caddy/Caddyfile
11
      - /srv/containers/compose/caddy/config:/config
12
      - /srv/containers/compose/caddy/data:/data
13
    networks:
14
      - caddy
15
networks:
16
  caddy:
17
    external: true

Create the Caddyfile

1
domain.tld {
2
  header /.well-known/matrix/* Content-Type application/json
3
  header /.well-known/matrix/* Access-Control-Allow-Origin *
4
  respond /.well-known/matrix/server `{"m.server": "matrix.domain.tld:443"}`
5
  respond /.well-known/matrix/client `{"m.homeserver":{"base_url":"https://matrix.domain.tld"}}`
6

7
  encode zstd gzip
8
}
9

10
matrix.domain.tld {
11
  reverse_proxy /_matrix/* synapse:8008
12
  reverse_proxy /_synapse/client/* synapse:8008
13
  request_body {
14
    max_size 10GB
15
  }
16
  @blocked {
17
    not path /_matrix/*
18
    not path /_synapse/client/*
19
  }
20
  respond @blocked 403
21

22
  encode zstd gzip
23
}

Start Caddy

docker compose -f /srv/containers/boilerplates/caddy/compose.yml up -d

Test the installation

At this point, give the Matrix Federation Tester a whirl by entering domain.tld. This tool checks if your server is reachable on the expected ports.

If you hit any issues, it’s likely to do with the reverse proxy or delegation setup, assuming there’s nothing wrong in the Synapse logs. Make sure to double check that your ports are actually open and accessible.

You should also be able to view the following at https://matrix.domain.tld/_matrix/static

Synapse is running

Now is the time to choose a client or app to log in with.

I recommend Element Web or Desktop for desktops and Element X for mobile devices.