# Matrix-Stack in der FEDEO Compose

Der Matrix-Stack liegt in derselben `docker-compose.yml` wie FEDEO und ist über das Compose-Profil `matrix` aktivierbar.

## Enthaltene Dienste

- `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:

```bash
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:

```yaml
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

```bash
docker compose --profile matrix up -d
```

Ohne Profil startet weiterhin nur der bisherige FEDEO-Stack:

```bash
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

```bash
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:

```yaml
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

```bash
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:

```bash
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.