Matrix Homeserver Setup - mischlabs.de

Dieses Projekt stellt einen eigenen, föderierbaren Matrix Homeserver auf Basis von Synapse bereit, inklusive einer PostgreSQL-Datenbank und dem Web-Client Element Web.

🛠 Architektur & Dienste

Das Setup besteht aus drei Docker-Containern:

matrix_synapse: Der eigentliche Matrix Homeserver (Synapse), vorkonfiguriert für das Domain-Routing unter mischlabs.de und erreichbar über matrix.mischlabs.de.
matrix_synapse_db: Eine dedizierte PostgreSQL 16 Datenbank für maximale Performance und Zuverlässigkeit.
matrix_element: Der Web-Client Element, erreichbar unter chat.mischlabs.de.

Da du Cloudflare (Cloudflare Tunnels) nutzt, entfällt jegliche komplexe Nginx-Netzwerkkonfiguration. Die Container laufen im standardmäßigen Bridge-Netzwerk und werden über ihre Ports direkt auf der NAS-IP bereitgestellt, wo Cloudflare sie sicher abgreift.

🚀 Deployment auf der NAS

Da du Docker auf deiner UGREEN NAS betreibst, sind dies die Schritte zur Bereitstellung:

1. Dateien vorbereiten

Kopiere den gesamten Ordner D:\Vibecoding\Website\Matrix auf dein NAS in das entsprechende Docker-Verzeichnis (z. B. /volume2/docker/matrix/).

2. Keycloak Client einrichten

Melde dich in deiner Keycloak Admin-Konsole (https://auth.mischlabs.de) an:

Wähle den Realm mischlabs.
Gehe auf Clients -> Create client.
Einstellungen:
- Client type: OpenID Connect
- Client ID: matrix
- Name: Matrix Synapse
Klicke auf Next und aktiviere:
- Client authentication: ON (Confidential Client, erfordert ein Secret)
- Authorization: OFF
- Authentication flow: Standard Flow aktiviert (Authorization Code Flow)
Klicke auf Save.
Unter Settings -> Capability config folgende URIs einpflegen:
- Valid Redirect URIs: https://matrix.mischlabs.de/_synapse/client/oidc/callback
- Web Origins: https://matrix.mischlabs.de
Gehe auf den Reiter Credentials und kopiere das Client Secret.

3. Konfiguration anpassen

Öffne die .env-Datei auf der NAS und trage dein Keycloak-Secret bei KEYCLOAK_CLIENT_SECRET ein.
Öffne /data/homeserver.yaml und ersetze DEIN_KEYCLOAK_CLIENT_SECRET durch dein Keycloak Client Secret.

4. Cloudflare Tunnel einrichten

Erstelle in deinem Cloudflare One Dashboard (Zero Trust) unter Tunnels zwei neue Public Hostnames für deinen Tunnel:

Route 1: Matrix Server (`matrix.mischlabs.de`)

Public Hostname: matrix.mischlabs.de
Service Type: HTTP
URL: http://<NAS-IP>:8008 (z. B. http://192.168.178.88:8008)

Route 2: Element Web Client (`chat.mischlabs.de`)

Public Hostname: chat.mischlabs.de
Service Type: HTTP
URL: http://<NAS-IP>:8088 (z. B. http://192.168.178.88:8088)

🏁 Container starten

Verbinde dich per SSH mit deinem NAS, navigiere in das Matrix-Verzeichnis und starte die Container:

docker compose up -d

Logs prüfen

Stelle sicher, dass Synapse und die Datenbank sauber starten:

docker compose logs -f synapse
docker compose logs -f synapse_db

Hinweis: Beim ersten Start generiert Synapse automatisch den Signierungsschlüssel /data/mischlabs.de.signing.key im Datenordner.

🌐 .well-known Domain-Delegierung aktivieren

Damit dein Server über @username:mischlabs.de föderieren kann und Clients die richtige Homeserver-URL finden, haben wir die .well-known Delegierung direkt in das Node.js-Backend (server.js) deiner Landingpage eingebaut.

Nginx-Reste wurden komplett entfernt. Wenn du das nächste Mal die Landingpage deployst (per Gitea Actions/Watchtower), werden die Pfade https://mischlabs.de/.well-known/matrix/server und https://mischlabs.de/.well-known/matrix/client automatisch als korrekte JSON-Antworten über Cloudflare ausgeliefert.

🔒 Administration & Wartung

Synapse-Admin (CLI)

Da die Standardregistrierung deaktiviert ist, werden neue Accounts ausschließlich über Keycloak erstellt. Solltest du jemals einen lokalen Admin-Account (ohne Keycloak) erstellen müssen, kannst du das über das Synapse CLI im Container tun:

docker exec -it matrix_synapse register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Folge den Eingabeaufforderungen (Admin-Rechte mit yes bestätigen).

4.4 KiB Raw Blame History