matrix-db: PostgreSQL für Synapse
matrix-redis: Redis für Synapse und LiveKit
matrix-synapse: Matrix Homeserver
matrix-well-known: Auslieferung von .well-known/matrix/client und .well-known/matrix/server
matrix-turn: coturn für stabile WebRTC-Verbindungen
matrix-livekit: LiveKit SFU für MatrixRTC-Konferenzen
matrix-rtc-jwt: MatrixRTC Authorization Service für LiveKit-JWTs

Vorbereitung

Lege im Repo eine .env auf Basis von .env.example an und passe mindestens diese Werte an:

MATRIX_SERVER_NAME
MATRIX_HOMESERVER_HOST
MATRIX_RTC_HOST
MATRIX_TURN_HOST
MATRIX_POSTGRES_PASSWORD
MATRIX_TURN_SHARED_SECRET
LIVEKIT_KEY
LIVEKIT_SECRET

Passe außerdem die Dateien in matrix/well-known/ an, falls die Domains nicht fedeo.de, matrix.fedeo.de und call.fedeo.de heißen.

Synapse-Konfiguration erzeugen

Synapse benötigt vor dem ersten Start eine generierte homeserver.yaml. Der Befehl bleibt innerhalb derselben Compose:

docker compose --profile matrix run --rm \
  -e SYNAPSE_SERVER_NAME="${MATRIX_SERVER_NAME}" \
  -e SYNAPSE_REPORT_STATS=no \
  matrix-synapse generate

Danach matrix/synapse/homeserver.yaml prüfen und mindestens diese Punkte setzen:

public_baseurl: "https://matrix.fedeo.de/"

database:
  name: psycopg2
  args:
    user: synapse
    password: "<MATRIX_POSTGRES_PASSWORD>"
    database: synapse
    host: matrix-db
    cp_min: 5
    cp_max: 10

redis:
  enabled: true
  host: matrix-redis

turn_uris:
  - "turn:<MATRIX_TURN_HOST>:3478?transport=udp"
  - "turn:<MATRIX_TURN_HOST>:3478?transport=tcp"
turn_shared_secret: "<MATRIX_TURN_SHARED_SECRET>"
turn_user_lifetime: "1h"

experimental_features:
  msc3266_enabled: true
  msc4222_enabled: true

max_event_delay_duration: 24h
rc_message:
  per_second: 0.5
  burst_count: 30
rc_delayed_event_mgmt:
  per_second: 1
  burst_count: 20

Start

docker compose --profile matrix up -d

Ohne Profil startet weiterhin nur der bisherige FEDEO-Stack:

docker compose up -d

Hinweise

Die Matrix-Services sind bewusst im bestehenden Compose-Stack definiert, damit FEDEO nicht in mehrere Deployment-Dateien zerfällt.
Die aktuellen Ports für TURN und LiveKit müssen auf der Firewall des Servers freigegeben werden.
Federation sollte erst nach einer expliziten Entscheidung geöffnet werden. Für B2B-Kommunikation ist eine Allowlist sinnvoll.
Die Werte in .env.example sind Platzhalter und nicht produktionssicher.

Lokaler Entwicklungsstack

Für lokale Entwicklung gibt es zusätzlich das Profil matrix-dev. Es nutzt direkte Localhost-Ports und braucht keine öffentlichen Domains, kein ACME und keine Traefik-Router.

Lokale Dienste:

Synapse: http://localhost:8008
Element Web: http://localhost:8080
MatrixRTC JWT-Service: http://localhost:8081
LiveKit: ws://localhost:7880
TURN: localhost:3478

Lokale Synapse-Konfiguration erzeugen

docker compose --profile matrix-dev run --rm \
  -e SYNAPSE_SERVER_NAME=localhost \
  -e SYNAPSE_REPORT_STATS=no \
  matrix-dev-synapse generate

Danach matrix/dev/synapse/homeserver.yaml für die lokale Compose anpassen:

public_baseurl: "http://localhost:8008/"

database:
  name: psycopg2
  args:
    user: synapse
    password: "synapse-dev-password"
    database: synapse
    host: matrix-dev-db
    cp_min: 5
    cp_max: 10

redis:
  enabled: true
  host: matrix-dev-redis

enable_registration: true
enable_registration_without_verification: true

turn_uris:
  - "turn:localhost:3478?transport=udp"
  - "turn:localhost:3478?transport=tcp"
turn_shared_secret: "matrix-dev-turn-secret"
turn_user_lifetime: "1h"

experimental_features:
  msc3266_enabled: true
  msc4222_enabled: true

Lokalen Stack starten

docker compose --profile matrix-dev up -d \
  matrix-dev-db \
  matrix-dev-redis \
  matrix-dev-synapse \
  matrix-dev-turn \
  matrix-dev-livekit \
  matrix-dev-rtc-jwt \
  matrix-dev-element

Einen lokalen Admin-Nutzer kannst du danach im Synapse-Container anlegen:

docker compose --profile matrix-dev exec matrix-dev-synapse \
  register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Anschließend Element Web unter http://localhost:8080 öffnen und mit dem lokalen Matrix-Nutzer anmelden.

Wenn FEDEO selbst parallel lokal laufen soll, starte die FEDEO-Dienste separat wie gewohnt. Der lokale Matrix-Stack ist absichtlich über direkte Ports erreichbar, damit er unabhängig von DNS, TLS und Traefik getestet werden kann.

Erste FEDEO-Backend-Integration

Das Backend stellt geschützte Matrix-Endpunkte unter /api/communication/matrix/* bereit:

GET /api/communication/matrix/status: prüft Konfiguration und Erreichbarkeit des Matrix-Homeservers
GET /api/communication/matrix/me: zeigt die aus dem FEDEO-Nutzer abgeleitete Matrix-ID
POST /api/communication/matrix/me/provision: legt den Matrix-Account für den angemeldeten FEDEO-Nutzer per Synapse-Shared-Secret-Registrierung an

Für lokale Provisionierung muss MATRIX_REGISTRATION_SHARED_SECRET aus matrix/dev/synapse/homeserver.yaml in der Backend-Umgebung gesetzt werden. Die lokale Synapse-Konfiguration ist absichtlich nicht versioniert, weil sie Secrets enthält.

In der lokalen Entwicklung liest das Backend dieses Secret als Fallback direkt aus matrix/dev/synapse/homeserver.yaml, sofern NODE_ENV nicht production ist. Auf Servern muss das Secret weiterhin explizit über die Umgebung oder das Secret-Management gesetzt werden.