What are we building?

We put Element Web 1.12.33 next to Synapse 1.164.2, on the same domain; Traefik splits the requests by path. Afterwards you have a finished chat interface in the browser, an end-to-end encrypted room, a registration that only works with an invite token, and the admin moves for accounts, rooms and media.

This is part 2 of the Matrix series. Part 1 built the homeserver, the delegation and federation; this one is about everything that comes after.

Requirements

• A running Matrix server from Matrix: Your Own Chat Server with Synapse (Part 1), including a green federation test
• Debian 13 with Docker and a Traefik that fetches the certificates
• The domain from part 1; the server_name stays unchanged
• About 60 minutes, a good part of it for the first login

Step by step

Step 1: How two services share one hostname

Synapse lays claim to three path prefixes and nothing else:

/_matrix         # the client and federation API
/_synapse        # the admin API
/.well-known/matrix  # the delegation from part 1

Everything else (the start page, JavaScript, images, fonts) belongs to Element. Traefik can tell them apart if you tell it which rule is checked first. That is what priority is for: the higher the number, the earlier the rule is evaluated.

Rule                                              priority   Result
Host(`YOUR_DOMAIN`) && PathPrefix(`/_matrix`)        100      Synapse
Host(`YOUR_DOMAIN`)                                   10      Element

Without priority, Traefik sorts by rule length and the longer one wins. That happens to give the right result here, but you cannot rely on it: it can change with every rule you add. Write the numbers down.

Step 2: Configure Element

Element Web is pure JavaScript in the browser; the entire configuration sits in a single config.json. Put it next to the compose.yaml:

cd /opt/matrix
nano element-config.json

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://YOUR_DOMAIN",
      "server_name": "YOUR_DOMAIN"
    }
  },
  "brand": "Kitchen Chat",
  "disable_custom_urls": true,
  "disable_guests": true,
  "disable_3pid_login": true,
  "default_country_code": "DE",
  "show_labs_settings": false,
  "room_directory": { "servers": ["YOUR_DOMAIN"] },
  "setting_defaults": {
    "breadcrumbs": true,
    "UIFeature.feedback": false,
    "UIFeature.registration": false
  }
}

The switches that matter:

• disable_custom_urls: true: The sign-in mask shows your server fixed instead of an input field for arbitrary homeservers. Without it people accidentally sign in to matrix.org and wonder why their account does not exist.
• disable_3pid_login and disable_guests: No login via email/phone (that would need an identity server) and no guest accounts.
• UIFeature.registration: false: The “Create account” link disappears. We handle registration in step 7 via tokens, not via an open button.
• show_labs_settings: false: Element has a whole drawer of unfinished features. On a server other people share, that drawer is better left shut.

The file has to be readable for the container:

chmod 0644 element-config.json

Step 3: Extend the stack

In the compose.yaml from part 1 we change Synapse’s Traefik rule and attach a second service:

# /opt/matrix/compose.yaml (excerpt)
  synapse:
    image: ghcr.io/element-hq/synapse:v1.164.2
    # ... unchanged ...
    labels:
      - traefik.enable=true
      - traefik.http.routers.synapse.rule=Host(`YOUR_DOMAIN`) && (PathPrefix(`/_matrix`) || PathPrefix(`/_synapse`) || PathPrefix(`/.well-known/matrix`))
      - traefik.http.routers.synapse.priority=100
      - traefik.http.routers.synapse.entrypoints=websecure
      - traefik.http.routers.synapse.tls.certresolver=le
      - traefik.http.services.synapse.loadbalancer.server.port=8008

  element:
    image: vectorim/element-web:v1.12.33
    container_name: element
    restart: unless-stopped
    volumes:
      - ./element-config.json:/app/config.json:ro
    networks: [proxy]
    labels:
      - traefik.enable=true
      - traefik.http.routers.element.rule=Host(`YOUR_DOMAIN`)
      - traefik.http.routers.element.priority=10
      - traefik.http.routers.element.entrypoints=websecure
      - traefik.http.routers.element.tls.certresolver=le
      - traefik.http.services.element.loadbalancer.server.port=80

Element sits only in the proxy network. It never talks to the database and not directly to Synapse either: the visitor’s browser makes the API calls, not the container. The internal network from part 1 stays reserved for the database.

docker compose up -d
docker compose ps

NAME        STATUS
element     Up 20 seconds (healthy)
matrix-db   Up 20 seconds (healthy)
synapse     Up 20 seconds (healthy)

Step 4: Counter-check both routes

Before you open a browser, check from the outside that the split really works. First the root, where Element has to answer:

curl -s https://YOUR_DOMAIN/ | grep -o "<title>[^<]*</title>"

<title>Element</title>

Then the configuration Element loads at startup:

curl -s https://YOUR_DOMAIN/config.json | head -5

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://YOUR_DOMAIN",

And finally that Synapse kept its three paths:

curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_DOMAIN/_matrix/client/versions
curl -s https://YOUR_DOMAIN/.well-known/matrix/server
curl -s https://YOUR_DOMAIN/.well-known/matrix/client

200
{"m.server":"YOUR_DOMAIN:443"}
{"m.homeserver":{"base_url":"https://YOUR_DOMAIN/"}}

If one of the three returns HTML instead of JSON, Element intercepted the request. Then the priority is wrong. If the first one returns JSON instead of HTML, it is the other way round.

Step 5: The first login and device verification

Open https://YOUR_DOMAIN/ in the browser. Because disable_custom_urls is set, your server is fixed in the mask; you only enter the username and password from part 1.

On the very first device Element sets up encryption by itself, without asking: in the background it creates a cross-signing key that marks your devices as yours, and a key backup on the server. The server only stores encrypted copies of those; it cannot read them. All you see of it is a prompt in the top left:

Step 6: The first encrypted room

Via “New room” you create a room. Two settings decide things here that are fixed later on:

• “Invite only”: The visibility can be changed later.
• “Enable end-to-end encryption”: That one cannot be taken back. Element says so as well: “You can’t disable this later. Bridges & most bots won’t work yet.” An encrypted room is unusable for most bridges to other networks and for many bots. If you are planning a Telegram or IRC bridge later, create an unencrypted room for it.

After that the room is there, and the first message goes out:

Through the admin API you can counter-check that the server really records the room as encrypted:

curl -s "https://YOUR_DOMAIN/_synapse/admin/v1/rooms?limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

name: Cooking night | members: 1 | encryption: m.megolm.v1.aes-sha2

m.megolm.v1.aes-sha2 is Matrix’s group encryption scheme. If it says null there, the room is readable in the clear, for the server and for anyone who gets hold of the database.

Step 7: Let friends in without opening registration

Part 1 sets enable_registration: false. That is right as long as you are alone. Only you would have to create every further account by hand and send the password over chat. The better way are registration tokens: registration is open, but only with an invite code that you hand out.

# /opt/matrix/data/homeserver.yaml
enable_registration: true
registration_requires_token: true

docker compose restart synapse

Now you create a token, here one that may be used three times:

curl -s -X POST "https://YOUR_DOMAIN/_synapse/admin/v1/registration_tokens/new" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uses_allowed": 3, "length": 12}'

{"token":"LvM3cFXHXX7H","uses_allowed":3,"pending":0,"completed":0,"expiry_time":null}

That string is what you send your people. Element asks for it during registration. The easiest way to check that nothing works without a token is at the start of the registration flow:

curl -s -X POST "https://YOUR_DOMAIN/_matrix/client/v3/register" \
  -H "Content-Type: application/json" -d '{}'

{"session":"PklWEdRKlnhHbBVJrwJnwnBG",
 "flows":[{"stages":["m.login.registration_token","m.login.dummy"]}],"params":{}}

The server now demands two stages, and the first one is the token. Without it (or with a wrong one, in which case the server reports “Invalid registration token”) the flow ends without an account being created. After a successful registration you can see the usage:

curl -s "https://YOUR_DOMAIN/_synapse/admin/v1/registration_tokens" \
  -H "Authorization: Bearer YOUR_TOKEN"

{"registration_tokens":[{"token":"LvM3cFXHXX7H","uses_allowed":3,"pending":0,"completed":1,"expiry_time":null}]}

completed are finished registrations, pending are started ones. Once the token is used up it simply stops working; you do not have to switch anything off. With "expiry_time" (milliseconds since 1970) you can additionally give it an expiry date.

Step 8: Federation in daily use

The federation test from part 1 checks whether others can reach your server. The other direction, whether your server gets out, you check by asking about someone who only exists elsewhere:

curl -s "https://YOUR_DOMAIN/_matrix/client/v3/profile/@matthew:matrix.org" \
  -H "Authorization: Bearer YOUR_TOKEN"

{"displayname":"Matthew","avatar_url":"mxc://matrix.org/oUxxDyzQOHdVDMxgwFzyCWEe"}

Your server cannot have made that answer up: it asked matrix.org, checked the signature and passed the result on. The same works with room addresses; the directory entry additionally tells you which servers sit in the room.

What that costs shows when you join a real public room:

time curl -s -X POST "https://YOUR_DOMAIN/_matrix/client/v3/join/%23element-web:matrix.org" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{}'

{"room_id":"!xUW4PpAe1CmThA3r2wI8IrgwwsK006-zqWdJCljpd10"}
real    0m2.221s

Two seconds. In the two minutes after that, while Synapse loads the room state (a good 5,000 state events), its memory climbs from around 120 MB to around 280 MB, the database from 15 to 63 MB. For a single room. That is the most important sentence about Matrix federation: your server keeps the complete state of every room you sit in, including the part that comes from foreign servers. A homeserver with 1 GB of RAM is therefore quickly finished once somebody joins three large rooms.

Step 9: Day-to-day admin

There are three moves you need regularly. Retiring accounts. An account is never deleted but deactivated, because the user ID lives on in foreign rooms:

curl -s -X POST "https://YOUR_DOMAIN/_synapse/admin/v1/deactivate/@NAME:YOUR_DOMAIN" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"erase": true}'

{"id_server_unbind_result":"success"}

erase: true additionally removes the display name and avatar. The user ID stays blocked and cannot be handed out again. That is on purpose, otherwise someone could take over the identity.

Getting rid of rooms you no longer need. First leave and forget, then purge from the server:

ROOM='!YOUR_ROOM_ID'
curl -s -X DELETE "https://YOUR_DOMAIN/_synapse/admin/v2/rooms/$ROOM" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"purge": true, "block": false}'

{"delete_id":"qUcHmFcjfVZFfHWv"}

The call returns immediately, the cleanup runs in the background. You query the state at /_synapse/admin/v2/rooms/delete_status/DELETE_ID until it says "status":"complete". With "block": true you additionally block the room so nobody can join it again.

Cleaning up media. Every image from every federated room ends up as a copy on your disk:

BEFORE=$(( ($(date +%s) - 2592000) * 1000 ))
curl -s -X POST "https://YOUR_DOMAIN/_synapse/admin/v1/media/YOUR_DOMAIN/delete?before_ts=$BEFORE" \
  -H "Authorization: Bearer YOUR_TOKEN"

{"deleted_media":[],"total":0}

before_ts is a timestamp in milliseconds; the calculation above means “older than 30 days”. Forget the three zeros and the call deletes nothing, because the point in time lands in 1970.

When it doesn’t work

Your problem is not listed? Search all error messages →

Maintenance & backups

You update Element and Synapse separately. Element Web is a collection of static files with no state of its own; an update is low-risk and takes seconds:

cd /opt/matrix
sed -i 's/element-web:v1.12.33/element-web:vNEW_VERSION/' compose.yaml
docker compose pull element && docker compose up -d element
curl -s https://YOUR_DOMAIN/version

The last call prints the running version, for example 1.12.33. Element follows Synapse loosely; a version jump on the server does not break the interface. The reverse holds too, as long as you do not skip several years.

What has to go into the backup on top of part 1:

/opt/matrix/element-config.json   # lives in no database

It is a small file, but it holds every decision from step 2. If it is lost, Element starts with the default configuration, and your people suddenly face an input field into which they can type any homeserver at all.

Registration tokens need hygiene. A token with uses_allowed: 3 and no expiry date is an invite code that stays valid for years. Look at the list every few months and delete what you no longer need:

curl -s -X DELETE "https://YOUR_DOMAIN/_synapse/admin/v1/registration_tokens/THE_TOKEN" \
  -H "Authorization: Bearer YOUR_TOKEN"

Memory use is the actual maintenance task. The jump from around 120 to 280 MB for a single federated room scales onwards. Set yourself a reminder to look at docker stats --no-stream and du -sh /opt/matrix/data/media_store every few months, and leave rooms where none of you writes any more. That is more effective than any fine-tuning.

Realistically, Element itself creates no work: two or three updates a year. The time goes into the homeserver: a Synapse update every two weeks with a look at the release notes, a media and room cleanup once a quarter. Together roughly one hour a month.

What are we building?

We run Synapse 1.164.2 with PostgreSQL 18.6 behind Traefik. At the end you have a Matrix homeserver with registration closed, one account of your own and working federation. The official federation tester confirms that it works.

This tutorial is part 1 and deliberately covers only the server. Element Web as the interface, daily life with rooms, and administration come in part 2, otherwise this would turn into a book.

Requirements

• Traefik as a reverse proxy with a working Let’s Encrypt resolver
• A domain pointing at the server (an A record and ideally an AAAA record)
• At least 2 GB of memory. Freshly started and idle, Synapse needs a good 100 MB and Postgres around 60 MB; as soon as you join rooms with many participants, the appetite grows noticeably

Step by step

Step 1: Telling server name, host and delegation apart

Matrix knows two different addresses, and that is the most common confusion at the start:

• The server_name appears in the IDs: @cook:YOUR_DOMAIN. It is pure naming.
• The host Synapse actually runs on can be an entirely different one, matrix.YOUR_DOMAIN, say.

So that foreign servers find the second when they only know the first, there is delegation: at https://YOUR_DOMAIN/.well-known/matrix/server sits a small JSON file pointing at the real host. In the same way a chat client finds out where to connect via https://YOUR_DOMAIN/.well-known/matrix/client.

In this guide server_name and host are the same domain. That is the simplest case, and Synapse can then serve both files itself, so you need no additional web server. If you later move to matrix.YOUR_DOMAIN, the server_name stays the same and only the delegation file changes.

Step 2: Let Synapse generate the configuration

Synapse writes its own base configuration, including the secrets and the signing key:

mkdir -p /opt/matrix/data && cd /opt/matrix
docker run --rm -v /opt/matrix/data:/data \
  -e SYNAPSE_SERVER_NAME=YOUR_DOMAIN \
  -e SYNAPSE_REPORT_STATS=no \
  ghcr.io/element-hq/synapse:v1.164.2 generate

Creating log config /data/YOUR_DOMAIN.log.config
Setting ownership on /data to 991:991
Generating config file /data/homeserver.yaml
Generating signing key file /data/YOUR_DOMAIN.signing.key
A config file has been generated in '/data/homeserver.yaml' for server name 'YOUR_DOMAIN'. Please review this file and customise it to your needs.

The generated file uses SQLite. For anything beyond a single-seat test that is too little; we switch homeserver.yaml to PostgreSQL and add the settings that concern this server:

# /opt/matrix/data/homeserver.yaml (excerpt – leave the secrets untouched)
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['0.0.0.0']
    resources:
      - names: [client, federation]
        compress: false

database:
  name: psycopg2
  args:
    user: synapse
    password: YOUR_DB_PASSWORD
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10

public_baseurl: https://YOUR_DOMAIN/
serve_server_wellknown: true
enable_registration: false
suppress_key_server_warning: true
max_upload_size: 50M
url_preview_enabled: false

Four lines deserve an explanation:

• x_forwarded: true: Synapse reads the real visitor IP from the X-Forwarded-For header that Traefik sets. Without it every log line shows the proxy’s address. The generated file already has the switch set; leave it in place when you rework the file.
• public_baseurl: Synapse builds the client delegation and all links in invitations from it.
• serve_server_wellknown: true: Synapse serves /.well-known/matrix/server itself. That is why we need no second web server.
• url_preview_enabled: false: Link previews make your server fetch every URL somebody pastes into a room. That is a nice feature and at the same time a way to abuse your server as a fetching tool for other people’s addresses. Leave it off to begin with.

Step 3: PostgreSQL with the right collation

Synapse requires a database with collation C. The reason is unspectacular and the consequence annoying: with a language-dependent collation such as de_DE.utf8, Postgres compares strings differently, and Synapse therefore refuses to start at all.

In the Docker image you get there via POSTGRES_INITDB_ARGS – on the very first start, because after that the collation is fixed:

    environment:
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"

You can check it any time:

docker compose exec db psql -U synapse -d synapse \
  -c "SELECT datname, pg_encoding_to_char(encoding), datcollate FROM pg_database WHERE datname='synapse';"

 datname | pg_encoding_to_char | datcollate
---------+---------------------+------------
 synapse | UTF8                | C

Step 4: The stack

# /opt/matrix/compose.yaml
services:
  db:
    image: postgres:18.6-alpine
    container_name: matrix-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [matrix-internal]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse"]
      interval: 10s
      timeout: 5s
      retries: 6

  synapse:
    image: ghcr.io/element-hq/synapse:v1.164.2
    container_name: synapse
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
      TZ: Europe/Berlin
    volumes:
      - ./data:/data
    networks: [matrix-internal, proxy]
    labels:
      - traefik.enable=true
      - traefik.http.routers.synapse.rule=Host(`YOUR_DOMAIN`)
      - traefik.http.routers.synapse.entrypoints=websecure
      - traefik.http.routers.synapse.tls.certresolver=le
      - traefik.http.services.synapse.loadbalancer.server.port=8008

volumes:
  pgdata:

networks:
  matrix-internal:
    internal: true
  proxy:
    external: true

The database sits in a network with internal: true – unreachable from outside and from the proxy network. The database password lives in a .env next to it and has to match the value in homeserver.yaml.

docker compose up -d
docker compose ps

NAME        STATUS
matrix-db   Up 55 seconds (healthy)
synapse     Up 45 seconds (healthy)

On first start Synapse creates the schema and then runs background migrations. The logs show lines such as Running background update 'threads_backfill' for minutes. That is normal and does not affect operation.

Step 5: The four endpoints that have to be right

Before you touch any chat client, check four addresses from the outside. First, whether the client API answers at all:

curl -s https://YOUR_DOMAIN/_matrix/client/versions

{"versions":["r0.0.1","r0.1.0", … ,"v1.16","v1.17"],"unstable_features":{ … }}

Then the two delegation files that Synapse serves itself thanks to serve_server_wellknown:

curl -s https://YOUR_DOMAIN/.well-known/matrix/server
curl -s https://YOUR_DOMAIN/.well-known/matrix/client

{"m.server":"YOUR_DOMAIN:443"}
{"m.homeserver":{"base_url":"https://YOUR_DOMAIN/"}}

And finally the key endpoint that foreign servers use to verify your server’s signatures:

curl -s https://YOUR_DOMAIN/_matrix/key/v2/server

{"old_verify_keys":{},"server_name":"YOUR_DOMAIN","signatures":{"YOUR_DOMAIN":{"ed25519:a_udcw":" … "}}, … }

Lastly the check that the door is shut:

curl -s -X POST https://YOUR_DOMAIN/_matrix/client/v3/register -d '{}'

{"errcode":"M_FORBIDDEN","error":"Registration has been disabled"}

Step 6: Create the first account

Because registration is closed, you use the bundled tool. It authenticates via the registration_shared_secret from the configuration, and -a makes the user an administrator:

docker compose exec synapse register_new_matrix_user \
  -u YOUR_USERNAME -p YOUR_PASSWORD -a \
  -c /data/homeserver.yaml http://localhost:8008

Sending registration request...
Success!

Step 7: Counter-test through the client API

Now the actual functional test, with no chat client and just curl. First log in:

curl -s -X POST https://YOUR_DOMAIN/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_USERNAME"},"password":"YOUR_PASSWORD"}'

The response contains user_id, device_id and an access_token. The user ID shows that the server_name is in place:

"user_id":"@YOUR_USERNAME:YOUR_DOMAIN"

With the token you create a room, send a message into it and read it back again. That proves the whole chain of client API, database and event store:

curl -s -X POST https://YOUR_DOMAIN/_matrix/client/v3/createRoom \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Cooking night","preset":"private_chat"}'

{"room_id":"!68AeABE_Q59hjgJkh8wIl3zdGbp_n7k4a9uOf4yDrF0"}

The room ID carries no server name: Synapse creates new rooms in room version 12, whose IDs are plain hashes. Part 2 explains what that means.

curl -s -X PUT "https://YOUR_DOMAIN/_matrix/client/v3/rooms/YOUR_ROOM_ID/send/m.room.message/txn1" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"msgtype":"m.text","body":"Onion tart at 19:15"}'

{"event_id":"$WHceSNXyP34qT0CoQjq0E97dm7p7ZVLArH7mZdKftyA"}

Step 8: Check federation

Everything so far concerned your server alone. Whether the rest of the Matrix world can talk to it is answered by the official federation tester. It resolves your delegation, opens a connection, checks the certificate and compares the server name against the signature:

curl -s "https://federationtester.matrix.org/api/report?server_name=YOUR_DOMAIN" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print('FederationOK:', d['FederationOK'])"

FederationOK: True

The checker lists both addresses (IPv4 and IPv6) separately; both have to show ValidCertificates: True and MatchingServerName: True. That is exactly what you want to see before you hand anyone your Matrix address. The same check exists as a web interface at federationtester.matrix.org; the API is handier for repeating it occasionally later.

Step 9: Walling off the admin API

Synapse ships its own administration API under /_synapse/admin/. With your administrator account’s token you can, for instance, list every account:

curl -s "https://YOUR_DOMAIN/_synapse/admin/v2/users?from=0&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

total: 1
   @YOUR_USERNAME:YOUR_DOMAIN | admin: True | deactivated: False

Without a token you are turned away, as expected:

{"errcode":"M_MISSING_TOKEN","error":"Missing access token"}

One endpoint, however, is different:

curl -s https://YOUR_DOMAIN/_synapse/admin/v1/server_version

{"server_version":"1.164.2"}

This endpoint answers without any authentication. Synapse does that on purpose, but it tells everyone which version you run and therefore which known issues are interesting for you. If you do not need the admin path from outside at all, the cleanest move is to block it at the reverse proxy: an IPAllowList middleware on /_synapse/admin costs two lines and settles the matter. The pattern for that is in making services reachable only over VPN.

When it doesn’t work

Your problem is not listed? Search all error messages →

Maintenance & backups

Updates come often: Synapse publishes a new version roughly every two weeks, and security fixes are among them. That makes a fixed rhythm necessary:

cd /opt/matrix
docker compose exec -T db pg_dump -U synapse synapse > before-update-$(date +%F).sql
sed -i 's/synapse:v1.164.2/synapse:vNEW_VERSION/' compose.yaml
docker compose pull && docker compose up -d
docker compose logs synapse --tail 20

Read the release notes before every jump, especially the “deprecations” section: Synapse regularly drops old configuration keys, and the server then refuses to start with a clear but unexpected message. Database migrations run automatically at startup; on large instances the first start after an update can therefore take several minutes.

Four things need backing up, and the first is the most important:

/opt/matrix/data/YOUR_DOMAIN.signing.key   # your server's identity
/opt/matrix/data/homeserver.yaml           # contains the three secrets
pg_dump output                              # rooms, messages, accounts
/opt/matrix/data/media_store/               # images and files from the rooms

Without the signing key you cannot restore the server. You could only set up a new one, and every other server would treat it as a new, unknown server. All of it belongs encrypted in your Restic backup.

The media_store grows unnoticed: every image from every federated room you join ends up as a copy on your disk. Check every few months with du -sh /opt/matrix/data/media_store; Synapse ships an admin API for cleaning up that deletes old media.

Realistically, setting it up costs an evening. After that it is two appointments a month: one update including a look at the release notes, one for disk space and the federation test. Matrix is not a service you set up and forget; the protocol moves too fast for that.