Was bauen wir?

Wir stellen Element Web 1.12.33 neben Synapse 1.164.2, und zwar auf derselben Domain; Traefik teilt die Anfragen nach Pfad auf. Danach hast du eine fertige Chat-Oberfläche im Browser, einen Ende-zu-Ende-verschlüsselten Raum, eine Registrierung, die nur mit Einladungstoken funktioniert, und die Admin-Handgriffe für Konten, Räume und Medien.

Das ist Teil 2 der Matrix-Serie. Teil 1 hat den Homeserver, die Delegation und die Föderation aufgebaut; hier geht es um alles, was danach kommt.

Voraussetzungen

• Ein laufender Matrix-Server aus Matrix: der eigene Chat-Server mit Synapse (Teil 1), inklusive grünem Föderationstest
• Debian 13 mit Docker und einem Traefik, der die Zertifikate holt
• Die Domain aus Teil 1; der server_name bleibt unverändert
• Etwa 60 Minuten, davon ein guter Teil für den ersten Login

Schritt für Schritt

Schritt 1: Wie sich zwei Dienste einen Hostnamen teilen

Synapse beansprucht drei Pfadpräfixe und sonst nichts:

/_matrix         # die Client- und Föderations-API
/_synapse        # die Verwaltungs-API
/.well-known/matrix  # die Delegation aus Teil 1

Alles andere (die Startseite, JavaScript, Bilder, Schriften) gehört Element. Traefik kann das auseinanderhalten, wenn man ihm sagt, welche Regel zuerst geprüft wird. Dafür gibt es priority: Je höher die Zahl, desto früher wird die Regel ausgewertet.

Regel                                             priority   Ergebnis
Host(`DEINE_DOMAIN`) && PathPrefix(`/_matrix`)       100      Synapse
Host(`DEINE_DOMAIN`)                                  10      Element

Ohne priority sortiert Traefik nach Länge der Regel, und die längere gewinnt. Das führt hier zufällig zum richtigen Ergebnis. Verlassen kannst du dich darauf nicht, denn das kann sich mit jeder zusätzlichen Regel ändern. Schreib die Zahlen hin.

Schritt 2: Element konfigurieren

Element Web ist reines JavaScript im Browser; die gesamte Einstellung steckt in einer einzigen config.json. Leg sie neben die compose.yaml:

cd /opt/matrix
nano element-config.json

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

Die wichtigen Schalter:

• disable_custom_urls: true: Die Anmeldemaske zeigt deinen Server fest an, statt ein Eingabefeld für beliebige Homeserver. Ohne das melden sich Leute versehentlich bei matrix.org an und wundern sich, warum ihr Konto nicht existiert.
• disable_3pid_login und disable_guests: Kein Login über E-Mail/Telefon (dafür bräuchte es einen Identitätsserver) und keine Gastkonten.
• UIFeature.registration: false: Der Link „Konto erstellen" verschwindet. Die Registrierung regeln wir in Schritt 7 über Tokens, nicht über einen offenen Knopf.
• show_labs_settings: false: Element hat eine ganze Schublade unfertiger Funktionen. Auf einem Server, den andere mitbenutzen, bleibt die besser zu.

Die Datei muss für den Container lesbar sein:

chmod 0644 element-config.json

Schritt 3: Den Stack erweitern

In der compose.yaml aus Teil 1 ändern wir die Traefik-Regel von Synapse und hängen einen zweiten Dienst an:

# /opt/matrix/compose.yaml (Auszug)
  synapse:
    image: ghcr.io/element-hq/synapse:v1.164.2
    # ... unverändert ...
    labels:
      - traefik.enable=true
      - traefik.http.routers.synapse.rule=Host(`DEINE_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(`DEINE_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 hängt nur im proxy-Netz. Es spricht nie mit der Datenbank und auch nicht direkt mit Synapse: Die API-Aufrufe macht der Browser des Besuchers, nicht der Container. Das interne Netz aus Teil 1 bleibt der Datenbank vorbehalten.

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)

Schritt 4: Beide Wege gegenprüfen

Bevor du den Browser aufmachst, prüf von außen, dass die Aufteilung wirklich greift. Erst die Wurzel, hier muss Element antworten:

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

<title>Element</title>

Dann die Konfiguration, die Element beim Start lädt:

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

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

Und schließlich, dass Synapse seine drei Pfade behalten hat:

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

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

Kommt bei einem der drei Aufrufe HTML statt JSON zurück, hat Element die Anfrage abgefangen. Dann stimmt die priority nicht. Kommt beim ersten Aufruf JSON statt HTML, ist es umgekehrt.

Schritt 5: Der erste Login und die Geräteverifizierung

Ruf https://DEINE_DOMAIN/ im Browser auf. Weil disable_custom_urls gesetzt ist, steht dein Server fest in der Maske; du gibst nur Benutzernamen und Passwort aus Teil 1 ein.

Beim allerersten Gerät richtet Element die Verschlüsselung selbst ein, ohne Rückfrage: Es erzeugt im Hintergrund einen Cross-Signing-Schlüssel, der deine Geräte als deine ausweist, und eine Schlüsselsicherung auf dem Server. Der Server speichert davon nur verschlüsselte Kopien; lesen kann er sie nicht. Zu sehen ist davon nur ein Hinweis oben links:

Schritt 6: Der erste verschlüsselte Raum

Über „New room" legst du einen Raum an. Zwei Einstellungen entscheiden hier über Dinge, die später feststehen:

• „Invite only": Die Sichtbarkeit lässt sich später ändern.
• „Enable end-to-end encryption": Das lässt sich nicht zurücknehmen. Element sagt es auch dazu: „You can’t disable this later. Bridges & most bots won’t work yet." Ein verschlüsselter Raum ist für die meisten Brücken zu anderen Netzen und für viele Bots nicht nutzbar. Wenn du später ein Telegram- oder IRC-Bridging planst, leg dafür einen unverschlüsselten Raum an.

Danach steht der Raum, und die erste Nachricht geht raus:

Über die Admin-API kannst du gegenprüfen, dass der Server den Raum tatsächlich als verschlüsselt führt:

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

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

m.megolm.v1.aes-sha2 ist das Gruppenverschlüsselungsverfahren von Matrix. Steht dort null, ist der Raum offen lesbar, für den Server und für jeden, der die Datenbank in die Finger bekommt.

Schritt 7: Freunde einlassen, ohne die Registrierung zu öffnen

In Teil 1 steht enable_registration: false. Das ist richtig, solange du allein bist. Nur müsstest du jedes weitere Konto von Hand anlegen und das Passwort per Chat verschicken. Der bessere Weg sind Registrierungstokens: Die Registrierung ist offen, aber nur mit einem Einladungscode, den du ausgibst.

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

docker compose restart synapse

Jetzt legst du einen Token an, hier einen, der dreimal benutzt werden darf:

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

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

Diese Zeichenfolge schickst du deinen Leuten. Element fragt sie während der Registrierung ab. Dass ohne Token nichts geht, prüfst du am einfachsten am Anfang des Registrierungsvorgangs:

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

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

Der Server verlangt jetzt zwei Stufen, und die erste ist der Token. Ohne ihn (oder mit einem falschen, dann meldet der Server „Invalid registration token") endet der Vorgang, ohne dass ein Konto entsteht. Nach einer erfolgreichen Registrierung siehst du den Verbrauch:

curl -s "https://DEINE_DOMAIN/_synapse/admin/v1/registration_tokens" \
  -H "Authorization: Bearer DEIN_TOKEN"

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

completed sind fertige Registrierungen, pending angefangene. Ist der Token aufgebraucht, läuft er ins Leere; du musst nichts abschalten. Mit "expiry_time" (Millisekunden seit 1970) kannst du ihm zusätzlich ein Ablaufdatum geben.

Schritt 8: Föderation im Alltag

Der Föderationstest aus Teil 1 prüft, ob andere deinen Server erreichen. Die andere Richtung, ob dein Server rauskommt, prüfst du, indem du nach jemandem fragst, den es nur woanders gibt:

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

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

Diese Antwort kann dein Server nicht selbst erfunden haben: Er hat matrix.org gefragt, die Signatur geprüft und das Ergebnis weitergereicht. Dasselbe funktioniert mit Raumadressen; der Verzeichniseintrag verrät zusätzlich, welche Server im Raum sitzen.

Was das kostet, zeigt der Beitritt zu einem echten öffentlichen Raum:

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

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

Zwei Sekunden. In den zwei Minuten danach, während Synapse den Raumzustand nachlädt (gut 5.000 Zustandsereignisse), steigt sein Arbeitsspeicher von rund 120 MB auf rund 280 MB, die Datenbank von 15 auf 63 MB. Für einen einzigen Raum. Das ist der wichtigste Satz über Matrix-Föderation: Dein Server verwaltet für jeden Raum, in dem du sitzt, dessen gesamten Zustand mit, auch den Teil, der von fremden Servern kommt. Ein Homeserver mit 1 GB RAM ist deshalb schnell am Ende, sobald jemand drei große Räume betritt.

Schritt 9: Der Admin-Alltag

Drei Handgriffe brauchst du regelmäßig. Konten stilllegen. Ein Konto wird nie gelöscht, sondern deaktiviert, weil die Benutzer-ID in fremden Räumen weiterlebt:

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

{"id_server_unbind_result":"success"}

erase: true löscht zusätzlich Anzeigename und Profilbild. Die Benutzer-ID bleibt gesperrt und kann nicht neu vergeben werden. Das ist Absicht, sonst könnte jemand die Identität übernehmen.

Räume loswerden, die du nicht mehr brauchst. Erst austreten und vergessen, dann vom Server räumen:

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

{"delete_id":"qUcHmFcjfVZFfHWv"}

Der Aufruf kommt sofort zurück, das Aufräumen läuft im Hintergrund. Den Stand fragst du unter /_synapse/admin/v2/rooms/delete_status/DELETE_ID ab, bis dort "status":"complete" steht. Mit "block": true sperrst du den Raum zusätzlich, sodass niemand ihn erneut betreten kann.

Medien aufräumen. Jedes Bild aus jedem föderierten Raum landet als Kopie bei dir:

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

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

before_ts ist ein Zeitstempel in Millisekunden; die Rechnung oben ergibt „älter als 30 Tage". Vergisst man die drei Nullen, löscht der Aufruf nichts, weil der Zeitpunkt 1970 liegt.

Wenn es nicht funktioniert

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

Element und Synapse aktualisierst du getrennt. Element Web ist eine Sammlung statischer Dateien ohne eigenen Zustand; ein Update ist risikoarm und kostet Sekunden:

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

Der letzte Aufruf gibt die laufende Version aus, etwa 1.12.33. Element folgt Synapse locker; ein Versionssprung des Servers macht die Oberfläche nicht kaputt. Umgekehrt gilt das ebenfalls, solange du nicht mehrere Jahre überspringst.

Was zusätzlich ins Backup muss, über Teil 1 hinaus:

/opt/matrix/element-config.json   # steckt in keiner Datenbank

Das ist eine kleine Datei, aber sie enthält jede Entscheidung aus Schritt 2. Geht sie verloren, startet Element mit der Standardkonfiguration, und deine Leute stehen plötzlich vor einem Eingabefeld, in das sie irgendeinen Homeserver tippen können.

Registrierungstokens brauchen Hygiene. Ein Token mit uses_allowed: 3 ohne Ablaufdatum ist ein Einladungscode, der jahrelang gültig bleibt. Schau alle paar Monate in die Liste und lösch, was du nicht mehr brauchst:

curl -s -X DELETE "https://DEINE_DOMAIN/_synapse/admin/v1/registration_tokens/DER_TOKEN" \
  -H "Authorization: Bearer DEIN_TOKEN"

Der Speicherbedarf ist die eigentliche Wartungsaufgabe. Der Sprung von rund 120 auf 280 MB für einen einzigen föderierten Raum skaliert weiter. Setz dir eine Erinnerung, alle paar Monate docker stats --no-stream und du -sh /opt/matrix/data/media_store anzuschauen, und tritt aus Räumen aus, in denen niemand von euch mehr schreibt. Das ist wirksamer als jede Feineinstellung.

Realistisch gerechnet macht Element selbst keine Arbeit: zwei, drei Updates im Jahr. Die Zeit geht in den Homeserver: alle zwei Wochen ein Synapse-Update mit Blick in die Release Notes, einmal im Quartal Medien und Räume aufräumen. Zusammen etwa eine Stunde im Monat.

Was bauen wir?

Wir betreiben Synapse 1.164.2 mit PostgreSQL 18.6 hinter Traefik. Am Ende hast du einen Matrix-Homeserver mit geschlossener Registrierung, einem eigenen Benutzerkonto und einer funktionierenden Föderation. Dass sie funktioniert, belegt der offizielle Föderationstester.

Dieses Tutorial ist Teil 1 und behandelt bewusst nur den Server. Element Web als Oberfläche, der Alltag mit Räumen und die Administration kommen in Teil 2, sonst würde daraus ein Buch.

Voraussetzungen

• Traefik als Reverse Proxy mit funktionierendem Let’s-Encrypt-Resolver
• Eine Domain, die auf den Server zeigt (A- und idealerweise AAAA-Record)
• Mindestens 2 GB Arbeitsspeicher. Frisch gestartet und ohne Last braucht Synapse gut 100 MB und Postgres rund 60 MB; sobald du Räumen mit vielen Teilnehmern beitrittst, wächst der Bedarf deutlich

Schritt für Schritt

Schritt 1: Server-Name, Host und Delegation auseinanderhalten

Matrix kennt zwei verschiedene Adressen, und das ist die häufigste Verwirrung am Anfang:

• Der server_name steht in den IDs: @koch:DEINE_DOMAIN. Er ist reine Namensgebung.
• Der Host, auf dem Synapse tatsächlich läuft, kann ein ganz anderer sein, etwa matrix.DEINE_DOMAIN.

Damit fremde Server den zweiten finden, wenn sie nur den ersten kennen, gibt es Delegation: Unter https://DEINE_DOMAIN/.well-known/matrix/server liegt eine kleine JSON-Datei, die auf den echten Host zeigt. Genauso findet ein Chat-Programm über https://DEINE_DOMAIN/.well-known/matrix/client, wohin es sich verbinden soll.

In dieser Anleitung laufen server_name und Host auf derselben Domain. Das ist der einfachste Fall, und Synapse kann die beiden Dateien dann selbst ausliefern. Einen zusätzlichen Webserver brauchst du nicht. Willst du später auf matrix.DEINE_DOMAIN umziehen, bleibt der server_name gleich und nur die Delegationsdatei ändert sich.

Schritt 2: Die Konfiguration erzeugen lassen

Synapse schreibt sich seine Grundkonfiguration selbst, inklusive der Geheimnisse und des Signaturschlüssels:

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

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

Die erzeugte Datei benutzt SQLite. Für alles außer einem Einzelplatz-Test ist das zu wenig; wir stellen in der homeserver.yaml auf PostgreSQL um und ergänzen die Einstellungen, die diesen Server betreffen:

# /opt/matrix/data/homeserver.yaml (Auszug – Geheimnisse bleiben unangetastet)
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: DEIN_DB_PASSWORT
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10

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

Vier Zeilen verdienen eine Erklärung:

• x_forwarded: true: Synapse liest die echte Besucher-IP aus dem X-Forwarded-For-Header, den Traefik setzt. Ohne das steht in jedem Protokoll die Adresse des Proxys. Die erzeugte Datei hat den Schalter schon gesetzt; lass ihn beim Umbau stehen.
• public_baseurl: Daraus baut Synapse die Client-Delegation und alle Links in Einladungen.
• serve_server_wellknown: true: Synapse liefert /.well-known/matrix/server selbst aus. Das ist der Grund, warum wir keinen zweiten Webserver brauchen.
• url_preview_enabled: false: Die Vorschau von Links lässt deinen Server jede URL abrufen, die jemand in einen Raum schreibt. Das ist eine hübsche Funktion und gleichzeitig eine Möglichkeit, deinen Server als Abrufwerkzeug für fremde Adressen zu missbrauchen. Lass sie zunächst aus.

Schritt 3: PostgreSQL mit der richtigen Sortierung

Synapse verlangt eine Datenbank mit der Sortierreihenfolge C. Der Grund ist unspektakulär und die Folge unangenehm: Mit einer sprachabhängigen Sortierung wie de_DE.utf8 vergleicht Postgres Zeichenketten anders, und Synapse verweigert deshalb von vornherein den Start.

Im Docker-Image erreichst du das über POSTGRES_INITDB_ARGS – beim allerersten Start, denn danach steht die Sortierreihenfolge fest:

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

Nachsehen kannst du das jederzeit:

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

Schritt 4: Der 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-intern]
    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-intern, proxy]
    labels:
      - traefik.enable=true
      - traefik.http.routers.synapse.rule=Host(`DEINE_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-intern:
    internal: true
  proxy:
    external: true

Die Datenbank liegt in einem Netz mit internal: true – von außen und aus dem proxy-Netz nicht erreichbar. Das Datenbankpasswort steht in einer .env daneben und muss mit dem Wert in der homeserver.yaml übereinstimmen.

docker compose up -d
docker compose ps

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

Beim ersten Start legt Synapse das Schema an und fährt anschließend Hintergrund-Migrationen. In den Logs stehen dann minutenlang Zeilen wie Running background update 'threads_backfill'. Das ist normal und stört den Betrieb nicht.

Schritt 5: Die vier Endpunkte, die stimmen müssen

Bevor du irgendein Chat-Programm anfasst, prüfst du von außen vier Adressen. Zuerst, ob die Client-API überhaupt antwortet:

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

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

Dann die beiden Delegationsdateien, die Synapse dank serve_server_wellknown selbst ausliefert:

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

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

Und schließlich der Schlüsselendpunkt, über den fremde Server die Signaturen deines Servers prüfen:

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

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

Zum Schluss die Kontrolle, dass die Tür zu ist:

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

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

Schritt 6: Das erste Konto anlegen

Weil die Registrierung zu ist, benutzt du das mitgelieferte Werkzeug. Es authentifiziert sich über das registration_shared_secret aus der Konfiguration, -a macht den Benutzer zum Administrator:

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

Sending registration request...
Success!

Schritt 7: Gegenprobe über die Client-API

Jetzt der eigentliche Funktionstest, ohne Chat-Programm und nur mit curl. Erst anmelden:

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

Die Antwort enthält user_id, device_id und einen access_token. Die Benutzer-ID zeigt, dass der server_name sitzt:

"user_id":"@DEIN_BENUTZERNAME:DEINE_DOMAIN"

Mit dem Token legst du einen Raum an, schickst eine Nachricht hinein und liest sie wieder aus. Damit ist die komplette Kette aus Client-API, Datenbank und Ereignisspeicher belegt:

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

{"room_id":"!68AeABE_Q59hjgJkh8wIl3zdGbp_n7k4a9uOf4yDrF0"}

Die Raum-ID trägt keinen Servernamen: Synapse legt neue Räume in Raumversion 12 an, und deren IDs sind reine Prüfsummen. Was es damit auf sich hat, steht in Teil 2.

curl -s -X PUT "https://DEINE_DOMAIN/_matrix/client/v3/rooms/DEINE_RAUM_ID/send/m.room.message/txn1" \
  -H "Authorization: Bearer DEIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"msgtype":"m.text","body":"Zwiebelkuchen um 19:15 Uhr"}'

{"event_id":"$WHceSNXyP34qT0CoQjq0E97dm7p7ZVLArH7mZdKftyA"}

Schritt 8: Föderation prüfen

Alles bisher ging um deinen Server allein. Ob der Rest der Matrix-Welt mit ihm reden kann, beantwortet der offizielle Föderationstester. Er löst deine Delegation auf, baut eine Verbindung auf, prüft das Zertifikat und vergleicht den Servernamen mit der Signatur:

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

FederationOK: True

Der Prüfer führt beide Adressen (IPv4 und IPv6) einzeln auf; bei beiden muss ValidCertificates: True und MatchingServerName: True stehen. Genau das willst du sehen, bevor du jemandem deine Matrix-Adresse gibst. Dieselbe Prüfung gibt es auch als Weboberfläche unter federationtester.matrix.org; die API eignet sich besser, um sie später gelegentlich zu wiederholen.

Schritt 9: Die Admin-API abschotten

Synapse bringt eine eigene Verwaltungs-API mit, die unter /_synapse/admin/ liegt. Mit dem Token deines Administratorkontos siehst du damit zum Beispiel alle Konten:

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

total: 1
   @DEIN_BENUTZERNAME:DEINE_DOMAIN | admin: True | deactivated: False

Ohne Token bekommst du erwartungsgemäß eine Abfuhr:

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

Ein Endpunkt fällt allerdings aus der Reihe:

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

{"server_version":"1.164.2"}

Dieser Endpunkt antwortet ohne jede Authentifizierung. Synapse macht das absichtlich, verrät damit aber jedem, welche Version du fährst und welche bekannten Lücken für dich interessant sind. Wenn du den Verwaltungspfad von außen gar nicht brauchst, sperrst du ihn am besten im Reverse Proxy: Eine IPAllowList-Middleware auf /_synapse/admin kostet zwei Zeilen und nimmt das Thema vom Tisch. Das Muster dafür steht in Dienste nur im VPN erreichbar machen.

Wenn es nicht funktioniert

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

Updates kommen häufig: Synapse veröffentlicht etwa alle zwei Wochen eine neue Version, und Sicherheitskorrekturen sind darunter. Das macht einen festen Rhythmus nötig:

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

Lies vor jedem Sprung die Release Notes, insbesondere den Abschnitt zu „deprecations“: Synapse wirft regelmäßig alte Konfigurationsschlüssel raus, und der Server startet dann mit einer klaren, aber unerwarteten Meldung nicht mehr. Datenbankmigrationen laufen beim Start automatisch; bei großen Instanzen kann der erste Start nach einem Update deshalb mehrere Minuten dauern.

Sichern musst du vier Dinge, und das erste ist das wichtigste:

/opt/matrix/data/DEINE_DOMAIN.signing.key   # die Identität deines Servers
/opt/matrix/data/homeserver.yaml            # enthält die drei Geheimnisse
pg_dump-Ausgabe                             # Räume, Nachrichten, Konten
/opt/matrix/data/media_store/               # Bilder und Dateien aus den Räumen

Ohne den Signaturschlüssel kannst du den Server nicht wiederherstellen. Du könntest ihn nur neu aufsetzen, und alle anderen Server würden ihn als neuen, unbekannten Server behandeln. Alles zusammen gehört verschlüsselt ins Restic-Backup.

Der media_store wächst unbemerkt: Jedes Bild aus jedem föderierten Raum, den du betrittst, landet als Kopie auf deiner Platte. Schau alle paar Monate mit du -sh /opt/matrix/data/media_store nach; Synapse bringt für das Aufräumen eine Admin-API mit, die alte Medien löscht.

Realistisch gerechnet kostet das Aufsetzen einen Abend. Danach sind es zwei Termine pro Monat: einmal Update samt Blick in die Release Notes, einmal Plattenplatz und Föderationstest. Matrix ist kein Dienst, den man aufsetzt und vergisst; dafür entwickelt sich das Protokoll zu schnell.