From 678a5694f42a736d369f7d06b3451cad66102435 Mon Sep 17 00:00:00 2001 From: theo Date: Thu, 5 Mar 2026 12:49:03 +0000 Subject: [PATCH] feat: matrix server deployment --- matrix/.env.example | 3 + matrix/README.md | 18 +++++ matrix/docker-compose.yml | 70 ++++++++++++++++++ matrix/docs/setup.md | 79 ++++++++++++++++++++ matrix/docs/user-management.md | 127 +++++++++++++++++++++++++++++++++ 5 files changed, 297 insertions(+) create mode 100644 matrix/.env.example create mode 100644 matrix/README.md create mode 100644 matrix/docker-compose.yml create mode 100644 matrix/docs/setup.md create mode 100644 matrix/docs/user-management.md diff --git a/matrix/.env.example b/matrix/.env.example new file mode 100644 index 0000000..c35041a --- /dev/null +++ b/matrix/.env.example @@ -0,0 +1,3 @@ +# Zufälligen Wert generieren mit: openssl rand -hex 32 +# Dann diese Datei als .env kopieren und den Wert eintragen +REGISTRATION_SHARED_SECRET=hier_langen_zufaelligen_wert_eintragen diff --git a/matrix/README.md b/matrix/README.md new file mode 100644 index 0000000..9def8b5 --- /dev/null +++ b/matrix/README.md @@ -0,0 +1,18 @@ +# Matrix Server (Synapse) – Homelab Dokumentation + +Selbst gehosteter Matrix/Synapse-Server auf `matrix.theocloud.dev`. +Registrierung ist deaktiviert – neue User werden nur per Einladungstoken angelegt. + +## Dateien + +| Datei | Beschreibung | +|---|---| +| `docker-compose-without-registration.yml` | Produktiv-Setup: Registrierung nur per Token | +| `docker-compose-with-registration.yml` | Offene Registrierung (nur lokal/Dev verwenden) | +| `.env` | Secrets (nicht committen!) | +| `.env.example` | Vorlage für `.env` | + +## Dokumentation + +- [Setup & Installation](./setup.md) +- [User & Token Verwaltung](./user-management.md) diff --git a/matrix/docker-compose.yml b/matrix/docker-compose.yml new file mode 100644 index 0000000..45c628c --- /dev/null +++ b/matrix/docker-compose.yml @@ -0,0 +1,70 @@ +###################################################### +##### MATRIX WITH TOKEN-BASED REGISTRATION ONLY ##### +###################################################### +# +# User anlegen: +# 1. Admin-Token holen (nach erstem Login): +# docker exec -it synapse register_new_matrix_user -u admin -p PASSWORT --admin http://localhost:8008 +# +# 2. Einladungstoken erstellen: +# curl -X POST 'http://localhost:8008/_synapse/admin/v1/registration_tokens/new' \ +# -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \ +# -H 'Content-Type: application/json' \ +# -d '{"uses_allowed": 1}' +# +# 3. Link an Freund schicken: +# https://matrix.theocloud.dev/#/register?token=TOKEN_AUS_SCHRITT_2 +# +###################################################### + +services: + synapse: + image: matrixdotorg/synapse:latest + container_name: synapse + restart: unless-stopped + ports: + - 8008:8008 + environment: + - SYNAPSE_SERVER_NAME=matrix.theocloud.dev + - SYNAPSE_REPORT_STATS=no + - REGISTRATION_SHARED_SECRET=${REGISTRATION_SHARED_SECRET:?Bitte REGISTRATION_SHARED_SECRET in .env setzen} + entrypoint: + - /bin/sh + - -c + - | + if [ ! -f /data/homeserver.yaml ]; then + echo "Generating initial configuration..." + /start.py generate + fi + echo "Configuring token-based registration..." + # Sicherstellen dass enable_registration vorhanden und auf true gesetzt ist + if grep -q "^enable_registration:" /data/homeserver.yaml; then + sed -i 's/^enable_registration:.*/enable_registration: true/' /data/homeserver.yaml + else + echo "enable_registration: true" >> /data/homeserver.yaml + fi + # Nur per Token registrieren erlauben + if grep -q "^registration_requires_token:" /data/homeserver.yaml; then + sed -i 's/^registration_requires_token:.*/registration_requires_token: true/' /data/homeserver.yaml + else + echo "registration_requires_token: true" >> /data/homeserver.yaml + fi + # Shared Secret für register_new_matrix_user CLI + if grep -q "^registration_shared_secret:" /data/homeserver.yaml; then + sed -i "s/^registration_shared_secret:.*/registration_shared_secret: ${REGISTRATION_SHARED_SECRET}/" /data/homeserver.yaml + else + echo "registration_shared_secret: ${REGISTRATION_SHARED_SECRET}" >> /data/homeserver.yaml + fi + # Email-Verifizierung deaktiviert (kein SMTP nötig) + if grep -q "^enable_registration_without_verification:" /data/homeserver.yaml; then + sed -i 's/^enable_registration_without_verification:.*/enable_registration_without_verification: true/' /data/homeserver.yaml + else + echo "enable_registration_without_verification: true" >> /data/homeserver.yaml + fi + echo "Starting Synapse..." + exec /start.py + volumes: + - synapse_data:/data + +volumes: + synapse_data: diff --git a/matrix/docs/setup.md b/matrix/docs/setup.md new file mode 100644 index 0000000..c152db4 --- /dev/null +++ b/matrix/docs/setup.md @@ -0,0 +1,79 @@ +# Setup & Installation + +## Voraussetzungen + +- Docker & Docker Compose +- Domain mit DNS-Eintrag auf deinen Homelab-Server (hier: `matrix.theocloud.dev`) +- Reverse Proxy (z.B. Traefik, Nginx Proxy Manager) der Port 443 → 8008 weiterleitet + +## Erstes Setup + +### 1. Repository klonen / Dateien kopieren + +```bash +cd /pfad/zum/projekt +cp .env.example .env +``` + +### 2. `.env` befüllen + +```bash +# Zufälligen Secret generieren +openssl rand -hex 32 +``` + +Dann in `.env` eintragen: + +```env +REGISTRATION_SHARED_SECRET=hier_den_generierten_wert_eintragen +``` + +### 3. Container starten + +```bash +docker compose -f docker-compose-without-registration.yml up -d +``` + +Beim ersten Start wird automatisch eine `homeserver.yaml` generiert und konfiguriert: +- `enable_registration: true` +- `registration_requires_token: true` (nur per Einladungstoken) +- `registration_shared_secret` (aus `.env`) +- `enable_registration_without_verification: true` (kein SMTP nötig) + +### 4. Ersten Admin-User anlegen + +Einmalig nach dem ersten Start: + +```bash +docker exec -it synapse register_new_matrix_user \ + -u admin \ + -p SICHERESPASSWORT \ + --admin \ + http://localhost:8008 +``` + +> Danach kann dieser Admin-Account über die Admin-API weitere User und Tokens verwalten. + +## Container verwalten + +```bash +# Logs ansehen +docker compose -f docker-compose-without-registration.yml logs -f + +# Neustart +docker compose -f docker-compose-without-registration.yml restart + +# Stoppen +docker compose -f docker-compose-without-registration.yml down +``` + +## Konfiguration anpassen + +Die generierte Synapse-Konfiguration liegt im Docker Volume `synapse_data`. +Direkter Zugriff auf die Datei: + +```bash +docker exec -it synapse cat /data/homeserver.yaml +``` + +Änderungen erfordern einen Neustart des Containers. diff --git a/matrix/docs/user-management.md b/matrix/docs/user-management.md new file mode 100644 index 0000000..bede483 --- /dev/null +++ b/matrix/docs/user-management.md @@ -0,0 +1,127 @@ +# User & Token Verwaltung + +Registrierung ist nicht offen – neue User können nur über Einladungstokens beitreten. + +## Access Token holen + +Für alle Admin-API-Aufrufe wird ein Access Token benötigt. +Nach dem Login mit dem Admin-Account: + +```bash +curl -X POST 'http://localhost:8008/_matrix/client/v3/login' \ + -H 'Content-Type: application/json' \ + -d '{ + "type": "m.login.password", + "user": "admin", + "password": "DEINPASSWORT" + }' +``` + +Den `access_token` aus der Antwort für alle weiteren Befehle verwenden. + +--- + +## Einladungstokens + +### Token erstellen (Einmalnutzung) + +```bash +curl -X POST 'http://localhost:8008/_synapse/admin/v1/registration_tokens/new' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \ + -H 'Content-Type: application/json' \ + -d '{"uses_allowed": 1}' +``` + +### Token mit Ablaufdatum erstellen + +```bash +curl -X POST 'http://localhost:8008/_synapse/admin/v1/registration_tokens/new' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \ + -H 'Content-Type: application/json' \ + -d '{ + "uses_allowed": 1, + "expiry_time": 1800000 + }' +``` + +> `expiry_time` ist ein Unix-Timestamp in Millisekunden. + +### Alle aktiven Tokens anzeigen + +```bash +curl 'http://localhost:8008/_synapse/admin/v1/registration_tokens' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' +``` + +### Token löschen + +```bash +curl -X DELETE \ + 'http://localhost:8008/_synapse/admin/v1/registration_tokens/TOKEN_HIER' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' +``` + +### Einladungslink an Freund schicken + +``` +https://matrix.theocloud.dev/#/register?token=TOKEN_AUS_DEM_ERSTELL-BEFEHL +``` + +Der Freund öffnet den Link in einem Matrix-Client (z.B. Element Web) und kann sich damit registrieren. + +--- + +## User direkt per CLI anlegen + +Ohne Einladungstoken – direkt über den Container (braucht `registration_shared_secret` in `.env`): + +```bash +docker exec -it synapse register_new_matrix_user \ + -u BENUTZERNAME \ + -p INITIALPASSWORT \ + http://localhost:8008 +``` + +Mit Admin-Rechten: + +```bash +docker exec -it synapse register_new_matrix_user \ + -u BENUTZERNAME \ + -p INITIALPASSWORT \ + --admin \ + http://localhost:8008 +``` + +--- + +## User über Admin-API verwalten + +### User anlegen oder Passwort setzen + +```bash +curl -X PUT \ + 'http://localhost:8008/_synapse/admin/v2/users/@BENUTZERNAME:matrix.theocloud.dev' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \ + -H 'Content-Type: application/json' \ + -d '{ + "password": "NEUESPASSWORT", + "admin": false + }' +``` + +### User deaktivieren + +```bash +curl -X POST \ + 'http://localhost:8008/_synapse/admin/v1/deactivate/@BENUTZERNAME:matrix.theocloud.dev' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \ + -H 'Content-Type: application/json' \ + -d '{"erase": false}' +``` + +### Alle User auflisten + +```bash +curl 'http://localhost:8008/_synapse/admin/v2/users?from=0&limit=100' \ + -H 'Authorization: Bearer DEIN_ACCESS_TOKEN' +```