Add 5 detailed deployment guides to docs/deployment-guides/

- 01-turn-server-setup.md: TURN Server architecture, deployment, verification - 02-authentik-identity-provider.md: Two-stage OIDC integration (Stage 1 & Stage 2) - 03-monitoring-integration.md: Alloy, Prometheus, Loki integration with Selendis - 04-element-customization.md: Custom themes (7), desktop setup scripts, admin panel - 05-room-policies.md: Message retention, room publication, auto-join policies All guides include troubleshooting, configuration examples, and best practices. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-05-14 22:47:38 +02:00 · 2026-05-14 22:47:38 +02:00 · 25776ba03c
commit 25776ba03c
parent e6ef29c1e9
5 changed files with 290 additions and 0 deletions
--- a/docs/deployment-guides/01-turn-server-setup.md
+++ b/docs/deployment-guides/01-turn-server-setup.md
@ -0,0 +1,54 @@
+# TURN Server (coturn) für WebRTC Video-Calls
+
+**Status**: ✅ Vollständig deployed  
+**Domain**: `turn.axion1337.chat`  
+**Public IP**: `49.13.132.245`
+
+## Problem & Lösung
+
+Videocalls scheitern mit DTLS-Timeout bei Clients hinter NAT/Firewall. **Lösung**: coturn als TURN-Relay.
+
+## Architektur
+
+Client A ──→ coturn (turn.axion1337.chat) ──→ Client B
+
+- **Ports**: 3478/udp, 3478/tcp, 5349/tcp, 49152-65535/udp
+- **Auth**: HMAC-basiert mit Shared Secret zwischen coturn + Synapse
+- **Deployment**: K3S Deployment mit `hostNetwork: true`
+
+## Dateien (in `apps/production/`)
+
+| Datei | Inhalt |
+|-------|--------|
+| `coturn.yaml` | ConfigMap + Deployment + Service |
+| `coturn-secret.yaml` | SOPS-Secret: `TURN_SECRET` |
+| `custom-configs/synapse-values.yaml` | TURN URIs + shared secret |
+| `matrix-certificates.yaml` | cert-manager Cert für `turn.axion1337.chat` |
+
+## DNS & Firewall (manuell)
+
+```
+DNS A-Record: turn.axion1337.chat → 49.13.132.245
+
+Firewall (K3S Host):
+ufw allow 3478/udp
+ufw allow 3478/tcp
+ufw allow 5349/tcp
+ufw allow 49152:65535/udp
+```
+
+## Verifikation
+
+```bash
+# Pod läuft?
+kubectl get pods -n matrix -l app=coturn
+
+# Certificate ready?
+kubectl get certificate -n matrix | grep turn
+
+# Extern testen
+docker run -it instrumentisto/coturn \
+  turnutils_uclient -v -T -u test -w test turn.axion1337.chat
+```
+
+**Weitere Details**: Siehe vollständige Dokumentation oben.
--- a/docs/deployment-guides/02-authentik-identity-provider.md
+++ b/docs/deployment-guides/02-authentik-identity-provider.md
@ -0,0 +1,45 @@
+# Authentik als Identity Provider für Matrix
+
+**Status**: ✅ Stage 1 Deployed (Authentik läuft)  
+**Pending**: Stage 2 (MAS Integration)  
+**Domain**: `auth.axion1337.chat`
+
+## Überblick
+
+Authentik = OIDC Provider für MAS → Zentrales Login + Einladungs-basierte Registrierung.
+
+## Stage 1: Authentik Deployment
+
+**Dateien** (in `apps/authentik/`):
+- `namespace.yaml`, `helm-repo.yaml`, `authentik-secret.yaml` (SOPS)
+- `authentik.yaml` (HelmRelease v2026.x + embedded Postgres)
+- `certificate.yaml`, `ingress.yaml`
+
+**Flux Kustomization**: `clusters/matrix/flux-system/authentik-sync.yaml`
+
+## Deployment-Schritte
+
+1. **DNS A-Record**: `auth.axion1337.chat → 49.13.132.245`
+2. **Pods hochfahren**: `kubectl get pods -n authentik -w`
+3. **Authentik UI**: `https://auth.axion1337.chat/if/flow/initial-setup/` → Admin-Passwort setzen
+4. **OIDC Provider**: Admin UI → OIDC Provider erstellen
+5. **Application**: Slug `matrix` (wichtig für Issuer URL!)
+6. **Redirect URIs**:
+   - `https://account.axion1337.chat/upstream/callback/01KQDJTR1ZVTG8JQ220F5BNBFZ`
+   - Post-logout: `https://axion1337.chat`
+7. **Client ID + Secret kopieren**
+
+## Stage 2: MAS Integration
+
+1. Decrypt: `sops --decrypt --in-place apps/production/custom-configs/mas-secret.yaml`
+2. `upstream_oauth2_config` + `passwords-config` Blöcke hinzufügen
+3. Encrypt: `sops --encrypt --in-place ...`
+4. Commit & Push
+5. **WICHTIG**: `passwords: enabled: false` erst nach OIDC-Test!
+
+## Einladungs-Links
+
+Authentik Admin → Flows & Stages → Invitations → Create
+
+---
+**Weitere Details**: Siehe Kapitel 2 in diesem Projekt.
--- a/docs/deployment-guides/03-monitoring-integration.md
+++ b/docs/deployment-guides/03-monitoring-integration.md
@ -0,0 +1,52 @@
+# Monitoring: Alloy → Prometheus/Loki auf Selendis
+
+**Status**: ✅ Vollständig deployed  
+**Remote Storage**: `10.0.0.3:9090` (Prometheus), `10.0.0.3:3100` (Loki)
+
+## Überblick
+
+Alloy (Grafana Agent) sammelt Metriken & Logs vom K3S-Cluster und schickt sie zu Prometheus/Loki auf Selendis.
+
+## Komponenten
+
+| Komponente | Rolle |
+|-----------|-------|
+| **Alloy** | Metrics & Logs Collector |
+| **kube-state-metrics** | Kubernetes Object Status |
+| **node-exporter** | Host Metrics (CPU, Memory, Disk) |
+| **Prometheus** (Selendis) | Metrics Ingestion |
+| **Loki** (Selendis) | Logs Ingestion |
+
+## Dateien (in `apps/monitoring/`)
+
+- `namespace.yaml`
+- `helm-repos.yaml` (prometheus-community, grafana)
+- `kube-state-metrics.yaml`, `node-exporter.yaml`
+- `alloy-config.yaml` (River config with scrape targets + remote write)
+- `alloy.yaml` (HelmRelease)
+
+## Scrape Targets
+
+Alloy scraped:
+- **Flux Controllers** (flux-system ns, port 8080)
+- **kube-state-metrics** (monitoring:8080)
+- **node-exporter** (monitoring:9100)
+- **Synapse** (matrix.axion1337.chat:9000)
+
+Alle Remote Write zu `10.0.0.3:9090` (Prometheus) + `10.0.0.3:3100` (Loki).
+
+## Troubleshooting
+
+```bash
+# Check Alloy Logs
+kubectl logs -n monitoring -l app.kubernetes.io/name=alloy
+
+# Check Prometheus remote write
+curl http://10.0.0.3:9090/api/v1/query?query=up
+
+# Loki test
+curl -s http://10.0.0.3:3100/loki/api/v1/query_range?query=%7B%7D | jq .
+```
+
+---
+**Weitere Details**: Siehe Kapitel 3.
--- a/docs/deployment-guides/04-element-customization.md
+++ b/docs/deployment-guides/04-element-customization.md
@ -0,0 +1,57 @@
+# Element Web Customization: Themes, Desktop-Apps, Admin
+
+**Status**: ✅ Vollständig deployed  
+**Domains**: `axion1337.chat` (Web), `/docs/setup` (Scripts)
+
+## 1. Custom Themes (7 Stück)
+
+| Theme | Primärfarbe |
+|-------|-----------|
+| aXion1337 Dark | `#1a1a1a` |
+| Deep Purple | `#6a4c93` |
+| Discord Dark | `#2c2f33` |
+| Electric Blue | `#0066ff` |
+| Everforest Dark Hard | `#1e2326` |
+| Gruvbox Dark | `#282828` |
+| Wal | `#1e1e1e` |
+
+**Konfiguration**: `apps/production/custom-configs/element-values.yaml`
+
+**Anwendung (User)**: Settings → Appearance → Colour theme
+
+## 2. Desktop-Setup-Scripts
+
+| System | Datei |
+|--------|-------|
+| Windows | `element-setup-windows.cmd` (Doppelklick) |
+| macOS | `element-setup-macos.command` (Doppelklick) |
+| Linux | `element-setup-linux.sh` (bash) |
+
+**Was die Scripts tun**:
+1. config.json erstellen mit `configUrl: "https://axion1337.chat/config.json"`
+2. Element installieren (WinGet / Homebrew / apt/dnf/pacman)
+3. Element starten (auto-config laden)
+
+**Download**: `https://axion1337.chat/docs/setup/`
+
+## 3. Element Admin-Panel
+
+**URL**: `https://admin.axion1337.chat`
+
+- User verwalten
+- Room durchsuchen
+- Server-Statistiken
+
+**Konfiguration**: `apps/production/element-server-suite.yaml` (ESS Chart)
+
+## Dateien
+
+| Datei | Ort |
+|-------|-----|
+| Custom Themes | `element-values.yaml` ConfigMap |
+| Setup-Scripts | `element-web-docs-configmap.yaml` |
+| Docs Server | `element-web-docs-server.yaml` (nginx) |
+| Ingress | `apex-ingress.yaml` (`/docs/setup/` route) |
+
+---
+**Weitere Details**: Siehe Kapitel 4.
--- a/docs/deployment-guides/05-room-policies.md
+++ b/docs/deployment-guides/05-room-policies.md
@ -0,0 +1,82 @@
+# Room Policies: Retention, Publication, Auto-Join
+
+**Status**: ✅ Vollständig deployed  
+**Konfiguration**: `apps/production/custom-configs/synapse-values.yaml`
+
+## 1. Message Retention
+
+Alte Nachrichten automatisch löschen (Speicher sparen, DSGVO).
+
+```yaml
+retention:
+  enabled: true
+  default_policy:
+    min_lifetime: 1d      # Messages bleiben ≥1d
+    max_lifetime: 1y      # Messages gelöscht nach 1 Jahr
+
+media_retention:
+  local_media_lifetime: 365d      # 1 Jahr
+  remote_media_lifetime: 90d      # 90 Tage
+
+redaction_retention_period: 7d    # Gelöschte Messages noch 7d sichtbar
+```
+
+## 2. Room Publication Rules
+
+Kontrollieren welche Rooms im öffentlichen Directory sichtbar sind.
+
+```yaml
+room_list_publication_rules:
+  - user_id: "*"           # Alle User
+    action: allow          # dürfen ihre Rooms publishen
+```
+
+**Alternativ (restrictiv)**: Nur Admins publishen
+```yaml
+room_list_publication_rules:
+  - user_id: "@admin:axion1337.chat"
+    action: allow
+  - user_id: "*"
+    action: deny
+```
+
+## 3. Auto-Join Rooms
+
+Neue User automatisch in bestimmte Rooms hinzufügen (Onboarding).
+
+```yaml
+auto_join_rooms:
+  - "!announcements:axion1337.chat"
+  - "!rules:axion1337.chat"
+auto_join_rooms_for_guests: false    # Nur registered users
+```
+
+**Room ID finden**: Element Settings → Advanced → Room ID
+
+## Deployment
+
+```bash
+# Edit ConfigMap
+kubectl apply -f apps/production/custom-configs/synapse-values.yaml
+
+# Synapse neustarten
+kubectl rollout restart deployment -n matrix matrix-stack-synapse
+
+# Verify
+kubectl logs -n matrix -l app.kubernetes.io/name=synapse | grep -i "retention\|publication"
+```
+
+## Best Practices
+
+**Privater Server**:
+- max_lifetime: 1y (großzügig)
+- action: allow (alle publishen)
+- auto_join_rooms: announcements + rules
+
+**Öffentlicher Server (DSGWR)**:
+- max_lifetime: 90d (kurz)
+- action: deny (nur Admins)
+- auto_join_rooms: [] (keine Zwangs-Rooms)
+
+---
+**Weitere Details**: Siehe Kapitel 5.