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:

1. matrix_synapse: Der eigentliche Matrix Homeserver (Synapse), vorkonfiguriert für das Domain-Routing unter mischlabs.de und erreichbar über matrix.mischlabs.de.
2. matrix_synapse_db: Eine dedizierte PostgreSQL 16 Datenbank für maximale Performance und Zuverlässigkeit.
3. 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:

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

3. Konfiguration anpassen

1. Öffne die .env-Datei auf der NAS und trage dein Keycloak-Secret bei KEYCLOAK_CLIENT_SECRET ein.
2. Ö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>:38008 (z. B. http://192.168.178.88:38008 - bzw. der in deiner .env definierte SYNAPSE_PORT)

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

• Public Hostname: chat.mischlabs.de
• Service Type: HTTP
• URL: http://<NAS-IP>:38088 (z. B. http://192.168.178.88:38088 - bzw. der in deiner .env definierte ELEMENT_PORT)

---

🏁 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).