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.