feat: matrix server deployment

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.

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'
+```