From aee9a34369328636b9972bb2c2c998d951200441 Mon Sep 17 00:00:00 2001 From: Scrublord MacBad Date: Thu, 14 May 2026 22:47:38 +0200 Subject: [PATCH] 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 --- .../deployment-guides/01-turn-server-setup.md | 54 ++++++++++++ .../02-authentik-identity-provider.md | 45 ++++++++++ .../03-monitoring-integration.md | 52 ++++++++++++ .../04-element-customization.md | 57 +++++++++++++ docs/deployment-guides/05-room-policies.md | 82 +++++++++++++++++++ 5 files changed, 290 insertions(+) create mode 100644 docs/deployment-guides/01-turn-server-setup.md create mode 100644 docs/deployment-guides/02-authentik-identity-provider.md create mode 100644 docs/deployment-guides/03-monitoring-integration.md create mode 100644 docs/deployment-guides/04-element-customization.md create mode 100644 docs/deployment-guides/05-room-policies.md diff --git a/docs/deployment-guides/01-turn-server-setup.md b/docs/deployment-guides/01-turn-server-setup.md new file mode 100644 index 0000000..00533ea --- /dev/null +++ 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. diff --git a/docs/deployment-guides/02-authentik-identity-provider.md b/docs/deployment-guides/02-authentik-identity-provider.md new file mode 100644 index 0000000..98d9599 --- /dev/null +++ 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. diff --git a/docs/deployment-guides/03-monitoring-integration.md b/docs/deployment-guides/03-monitoring-integration.md new file mode 100644 index 0000000..b904036 --- /dev/null +++ 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. diff --git a/docs/deployment-guides/04-element-customization.md b/docs/deployment-guides/04-element-customization.md new file mode 100644 index 0000000..1564657 --- /dev/null +++ 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. diff --git a/docs/deployment-guides/05-room-policies.md b/docs/deployment-guides/05-room-policies.md new file mode 100644 index 0000000..c377f49 --- /dev/null +++ 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.