Add operations and archive documentation to wiki
- Operations-ConfigMap-Sync.md: Git pre-commit hook automation - Element-Desktop-Setup.md: Platform-specific setup scripts - Authentik-Archive.md, Invitation-Registration-Archive.md: Historical docs - Update Home.md navigation with all resources Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Scrublord MacBad
parent
425a18bfab
commit
280aa36cc3
117
Authentik-Archive.md
Normal file
117
Authentik-Archive.md
Normal file
@ -0,0 +1,117 @@
|
||||
# Authentik als Einladungs- und Self-Registration-Layer vor MAS in ESS Community
|
||||
|
||||
## Kurzurteil
|
||||
|
||||
Ja — in deinem Setup ist **Authentik** technisch sinnvoll einsetzbar, aber **nicht als Ersatz für den Matrix Authentication Service**, sondern **als Upstream-OIDC-Provider vor MAS**. Das ist der sauberste Weg, weil Synapse heute eine stabile, vereinfachte Integration mit MAS hat, ESS Community zusätzliche MAS-Konfiguration ausdrücklich über `matrixAuthenticationService.additional` vorsieht, und MAS jede OIDC-konforme Upstream-Identitätsquelle unterstützt. Für ein ESS-Deployment mit delegierter Authentifizierung ist das deutlich kohärenter als eine Direktanbindung von Synapse an Authentik vorbei. citeturn31view0turn7view2turn14view1turn23search0
|
||||
|
||||
Wichtig ist aber die Abgrenzung: Wenn dein einziges Problem wirklich nur lautet „im Admin-Frontend kann ich keine Registration Tokens mehr klicken“, dann **brauchst du Authentik nicht zwingend**. MAS hat weiterhin eine Admin-API mit Endpunkten für User-Registration-Tokens; der fehlende Komfort liegt also eher in der Oberfläche als in der Funktion selbst. Die API ist mit `urn:mas:admin` abgesichert und kann sowohl interaktiv als auch automatisiert benutzt werden. citeturn19search0turn28search0turn28search1turn28search2
|
||||
|
||||
## Warum Authentik hier die bessere Plattform sein kann
|
||||
|
||||
Der Mehrwert von Authentik entsteht dann, wenn du **mehr als nur ein Token-Feld** willst: Einladungen, Self-Service-Enrolment, E-Mail-Verifikation, Policies, Gruppen-Zuweisung, später vielleicht weitere Login-Quellen hinter derselben Oberfläche. Authentik kann selbst als OpenID Provider auftreten, aber auch als Relying Party gegenüber anderen OAuth/OIDC-Quellen arbeiten; MAS sieht dann nur noch **eine** saubere OIDC-Oberfläche, während Authentik die eigentliche Onboarding- und Policy-Logik kapselt. Das passt sehr gut zu MAS, weil MAS nach oben bewusst nur OIDC unterstützt und SAML/LDAP nicht selbst als Upstream sprechen will. citeturn21view0turn21view3turn14view1
|
||||
|
||||
Für dein Ziel „potenzielle Anwender sollen sich selbst registrieren können“ ist der entscheidende Unterschied: Bei MAS-Registration-Tokens autorisierst du eine **Matrix-Registrierung**; bei Authentik autorisierst du zunächst eine **Identität im IdP**, und MAS übernimmt diese Identität anschließend per OIDC und legt daraus den Matrix-Account an. Das ist architektonisch stärker, weil dieselbe Identität später auch für andere Dienste nutzbar wird. MAS kann beim Upstream-Login den Matrix-Localpart, Display Name und E-Mail aus Claims übernehmen; für neue Nutzer gibt es dabei sogar einen expliziten Bestätigungs- bzw. Attribut-Import-Schritt. citeturn24search0turn14view0
|
||||
|
||||
## Wann Authentik nicht nötig ist
|
||||
|
||||
Wenn du ausschließlich einen „Einladungs-Code“ für Matrix brauchst und keinerlei separates Identitätsmanagement, dann ist die schlankere Lösung wahrscheinlich: **bei MAS bleiben und die Registration-Tokens per Admin-API verwalten**. Dafür brauchst du keinen zusätzlichen Dienst, keine zweite Postgres-Anwendung und keine zweite Policy-Oberfläche. Das ist betriebsärmer und passt gut zu kleinen Community-Setups. citeturn19search0turn28search0turn28search2
|
||||
|
||||
Sobald du aber Dinge wie diese willst, kippt die Bewertung klar zugunsten von Authentik: verschiedene Onboarding-Flows, Einladungs-Links statt nackter Codes, E-Mail-Verifikation, Domain-Allow-Lists, Gruppen-Zuweisung, zentrale MFA-Politik oder später externe Identity-Sources. Authentik bringt dafür sowohl vorgefertigte Einladungs-Blueprints als auch Enrolment-Flows mit und kann bei Bedarf eigene Expression Policies für restriktivere Zulassungslogik einsetzen. citeturn21view1turn21view2turn30search3
|
||||
|
||||
## Empfohlene Zielarchitektur
|
||||
|
||||
Die von mir empfohlene Zielarchitektur ist:
|
||||
|
||||
**Element Web / Clients → MAS → Authentik → Benutzerquelle(n)**
|
||||
|
||||
Synapse bleibt dabei an MAS delegiert. Das ist genau der Pfad, den die Synapse- und MAS-Dokumentation heute unterstützen: Synapse integriert stabil mit MAS, und MAS kann wiederum Upstream-OIDC-Provider sprechen. Eine direkte Synapse-OIDC-Integration mit Authentik ist zwar technisch dokumentiert, wäre in deinem ESS/MAS-Setup aber die weniger saubere Variante, weil du damit an der in ESS bereits vorgesehenen Delegationsschicht vorbeikonfigurierst. citeturn31view0turn14view2turn14view1turn7view2
|
||||
|
||||
Für Authentik selbst ist das Standardmaterial: auf Kubernetes per Helm deployen, in Produktion ein echtes PostgreSQL verwenden statt der Demo-Datenbank, und E-Mail konfigurieren, wenn du Einladungen oder Verifikations-Mails nutzen willst. Das ist wichtig, weil Authentik-Einladungen und E-Mail-basierte Enrolment-Flows ohne Mailtransport ihren eigentlichen Nutzen verlieren. citeturn34view0turn25search1
|
||||
|
||||
Ein entscheidender UX-Punkt: Wenn in MAS genau **ein** Upstream-Provider konfiguriert ist und die lokale Passwortdatenbank deaktiviert wird, startet MAS den Upstream-Authentifizierungsfluss automatisch. Damit verhält sich das System für Endnutzer fast so, als wäre Authentik „direkt“ integriert, obwohl MAS weiterhin die Matrix-native Auth-Schicht bleibt. citeturn26view0
|
||||
|
||||
## Konkrete Integration in ESS und FluxCD
|
||||
|
||||
Der erste praktische Schritt ist, Authentik als eigene GitOps-Anwendung in Kubernetes einzuführen. Offiziell ist dafür das Helm-Chart vorgesehen; produktiv sollte die Datenbank extern bzw. operator-basiert laufen, und Mail sollte von Anfang an mitgedacht werden. Danach erzeugst du in Authentik eine **Application + OAuth2/OIDC Provider**-Kombination. Das ist der von Authentik empfohlene Weg zur Erstellung eines OIDC-Providers. citeturn34view0turn35view0
|
||||
|
||||
Für den OIDC-Provider in Authentik verwendest du als Redirect-URI **nicht** die Synapse-Callback-URL aus der direkten Synapse-Dokumentation, sondern die von MAS erwartete Upstream-Callback-URL. MAS verlangt für Upstream-Provider eine stabile ULID als Provider-ID und verwendet daraus die Callback-URL `https://<auth-service-domain>/upstream/callback/<id>`. Optional kannst du zusätzlich die Backchannel-Logout-URL `https://<auth-service-domain>/upstream/backchannel-logout/<id>` hinterlegen. Authentik unterstützt für OIDC-Anwendungen Front- und Back-Channel-Logout, sofern der Provider entsprechend konfiguriert ist. citeturn14view1turn26view3turn35view1
|
||||
|
||||
In ESS selbst musst du dafür **keinen Chart forken**. Die vorgesehene Stelle ist `matrixAuthenticationService.additional`. Dort gibst du MAS die Upstream-OIDC-Konfiguration und schaltest die lokale Passwortdatenbank ab, wenn Authentik der alleinige Eintrittspunkt werden soll. Genau dafür ist die ESS-Advanced-Dokumentation da. citeturn7view2
|
||||
|
||||
Ein praktikabler MAS-Werteblock für deine GitOps-Struktur sieht so aus:
|
||||
|
||||
```yaml
|
||||
matrixAuthenticationService:
|
||||
additional:
|
||||
10-authentik-upstream.yaml:
|
||||
config: |
|
||||
passwords:
|
||||
enabled: false
|
||||
|
||||
account:
|
||||
password_registration_enabled: false
|
||||
|
||||
upstream_oauth2:
|
||||
providers:
|
||||
- id: 01JVXXXXXXXXXXXXXXXAUTHN
|
||||
issuer: "https://auth.example.com/application/o/matrix-mas/"
|
||||
human_name: "Community Login"
|
||||
client_id: "mas-community"
|
||||
client_secret: "AUS_SOPS_SECRET"
|
||||
token_endpoint_auth_method: client_secret_post
|
||||
scope: "openid profile email"
|
||||
fetch_userinfo: true
|
||||
on_backchannel_logout: logout_browser_only
|
||||
|
||||
claims_imports:
|
||||
localpart:
|
||||
action: require
|
||||
template: "{{ user.preferred_username }}"
|
||||
# Nur für Bestandskonten und nur nach Pilotphase:
|
||||
# on_conflict: set
|
||||
|
||||
displayname:
|
||||
action: force
|
||||
template: "{{ user.name }}"
|
||||
|
||||
email:
|
||||
action: force
|
||||
template: "{{ user.email }}"
|
||||
```
|
||||
|
||||
Die inhaltliche Grundlage dafür kommt direkt aus den MAS-Upstream-OIDC-Dokumenten: Provider-`id` als ULID, `issuer`, `client_id`, `client_secret`, Scope, optionale UserInfo-Nutzung und Claim-Mapping für `localpart`, `displayname` und `email`. ESS injiziert genau solche zusätzlichen MAS-Dateien über `matrixAuthenticationService.additional`. citeturn14view1turn14view0turn13view5turn7view2
|
||||
|
||||
Für das eigentliche Onboarding in Authentik hast du zwei gute Varianten. Wenn du das MAS-Token-Modell möglichst ähnlich nachbauen willst, nimmst du **Invitations**. Authentik kann Einladungs-URLs an konkrete Empfänger senden oder generische Einladungslinks bereitstellen, bei denen Benutzer ihre Credentials selbst festlegen. Wenn du eher echte Self-Service-Registrierung willst, nimmst du einen Enrolment-Flow, optional mit E-Mail-Verifikation. Beide Muster sind offiziell dokumentiert; es gibt sogar vorgefertigte Blueprints für invitation-based enrollment und Beispiel-Flows für Enrolment mit oder ohne E-Mail-Verifikation. citeturn21view1turn21view2
|
||||
|
||||
Wenn du bei der Benutzerführung in Element noch glatter werden willst, kannst du optional in Element Web `sso_redirect_options` setzen, damit Nutzer auf der Login- oder Welcome-Seite sofort in den OIDC-/SSO-Flow gehen. Das ist kein Muss — MAS kann bei einem einzigen Upstream-Provider ohnehin automatisch weiterleiten — aber es verbessert den Eindruck eines „SSO-only“-Setups. citeturn15view4turn26view0
|
||||
|
||||
Ein optionaler Element-Web-Block dafür wäre:
|
||||
|
||||
```json
|
||||
{
|
||||
"sso_redirect_options": {
|
||||
"on_login_page": true,
|
||||
"on_welcome_page": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Risiken und Fallstricke
|
||||
|
||||
Der heikelste Punkt ist die **Abbildung auf bestehende Matrix-Konten**. MAS kann Upstream-Identitäten an vorhandene lokale Nutzer binden, wenn der gemappte `localpart` passt. Standardmäßig verweigert MAS diese Verknüpfung aber; dafür gibt es `claims_imports.localpart.on_conflict` mit Werten wie `set`, `add` oder `replace`. Die Dokumentation warnt ausdrücklich davor, dass das bei unsauberem Mapping ein Account-Takeover-Risiko werden kann. In der Praxis heißt das: `on_conflict` nur dann einschalten, wenn du sicher garantieren kannst, dass Authentik-`preferred_username` oder ein anderes Attribut **eindeutig und dauerhaft** dem gewünschten Matrix-Localpart entspricht. citeturn26view2turn14view0
|
||||
|
||||
Der zweite Betriebsfallstrick ist GitOps-spezifisch: Änderungen und Ergänzungen im `upstream_oauth2.providers`-Block synchronisiert MAS beim Start in seine Datenbank, **Entfernungen** aber nicht automatisch. Wenn du einen Provider wieder herausnimmst oder umbenennst, brauchst du zusätzlich `mas-cli config sync --prune`. Für FluxCD ist das wichtig, weil „Config aus Git gelöscht“ hier nicht automatisch „Provider aus MAS-DB gelöscht“ bedeutet. citeturn27search1turn13view5
|
||||
|
||||
Der dritte Punkt betrifft Logout-Semantik. Sowohl MAS als auch Authentik können OIDC-Logout verarbeiten, aber du solltest den Modus bewusst wählen. `logout_all` in MAS ist am konsequentesten, kann aber auch Sessions beenden, die aus derselben Upstream-Sitzung stammen und über andere Flows erzeugt wurden. `logout_browser_only` ist meist die konservativere Wahl für einen ersten Rollout. Auf Authentik-Seite kannst du zusätzlich vollständiges Single Logout aktivieren, wenn Logout aus einer Anwendung auch die Authentik-Sitzung selbst und andere verbundene Anwendungen beenden soll. citeturn26view0turn35view1
|
||||
|
||||
Falls du Authentik doch nicht einführst und stattdessen bei MAS-Registration-Tokens bleibst, solltest du den ESS-Hinweis ernst nehmen: `account.password_registration_email_required: false` darf auf einem öffentlich föderierenden System nur zusammen mit Einschränkungen wie `registration_token_required: true` benutzt werden, sonst läufst du direkt in Missbrauch und Spam. MAS selbst dokumentiert dieselben Schalter im `account`-Block: Passwort-Registrierung ist standardmäßig aus, E-Mail-Pflicht standardmäßig an, Registration-Token-Pflicht standardmäßig aus. citeturn7view2turn13view0turn13view1turn13view2
|
||||
|
||||
## Praktische Entscheidung
|
||||
|
||||
Wenn dein Zielbild lautet **„Einladungen, Self-Service, Verifikation, Gruppen, spätere Erweiterbarkeit“**, dann ist meine klare Empfehlung: **Authentik vor MAS**. Das ist in ESS Community sauber integrierbar, nutzt die offiziell vorgesehenen Konfigurationspfade und hält Synapse in der heute empfohlenen MAS-Architektur. citeturn7view2turn31view0turn14view1
|
||||
|
||||
Wenn dein Zielbild dagegen nur lautet **„ich will wieder Registration Tokens vergeben können, aber ohne zweiten IdP zu betreiben“**, dann ist die wirtschaftlichere Lösung sehr wahrscheinlich: **MAS Admin API automatisieren statt Authentik einführen**. Funktional ist das möglich; der fehlende Baustein ist nur die Bedienoberfläche, nicht die darunterliegende Token-Funktion. citeturn19search0turn28search0turn28search2
|
||||
|
||||
## Offene Punkte und Grenzen
|
||||
|
||||
Die produktseitigen Integrationsfragen sind gut durch die offiziellen Dokumentationen abgedeckt. Was ich in diesem Bericht bewusst generisch gehalten habe, sind deine **konkreten Datei- und Pfadnamen im GitOps-Repo** sowie die **genaue Secret-Aufteilung** zwischen ConfigMap und SOPS-Secret. Die technische Empfehlung steht trotzdem fest: MAS bleibt die Matrix-Schicht, Authentik wird der Upstream-IdP, und die Integration erfolgt über `matrixAuthenticationService.additional` in ESS. citeturn7view2turn14view1
|
||||
206
Element-Desktop-Setup.md
Normal file
206
Element-Desktop-Setup.md
Normal file
@ -0,0 +1,206 @@
|
||||
# Element Desktop Setup Scripts
|
||||
|
||||
Automatische Konfiguration und Installation von Element Desktop mit Custom Themes für aXion1337.Chat
|
||||
|
||||
## 📋 Systemanforderungen
|
||||
|
||||
- **Windows 10/11**
|
||||
- **macOS 10.13+**
|
||||
- **Linux** (Ubuntu, Debian, Fedora, Arch, openSUSE, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 🪟 Windows
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Lade die Datei herunter**: `element-setup-windows.cmd`
|
||||
2. **Doppelklick** auf die Datei
|
||||
3. Das Skript wird automatisch:
|
||||
- ✅ Die config.json erstellen
|
||||
- ✅ Element Desktop installieren (falls nötig)
|
||||
- ✅ Element starten
|
||||
|
||||
**Oder manuell:**
|
||||
```cmd
|
||||
element-setup-windows.cmd
|
||||
```
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
Das Skript versucht automatisch, Element zu installieren über:
|
||||
- Windows Store (Microsoft Store)
|
||||
- WinGet (Windows Package Manager)
|
||||
- Chocolatey
|
||||
|
||||
Falls nichts davon vorhanden ist, installiere Element manuell:
|
||||
https://element.io/download
|
||||
|
||||
---
|
||||
|
||||
## 🍎 macOS
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Lade die Datei herunter**: `element-setup-macos.command`
|
||||
2. **Doppelklick** im Finder
|
||||
3. Das Skript wird automatisch:
|
||||
- ✅ Die config.json erstellen
|
||||
- ✅ Element Desktop installieren (über Homebrew falls nötig)
|
||||
- ✅ Element starten
|
||||
|
||||
**Oder im Terminal:**
|
||||
```bash
|
||||
chmod +x element-setup-macos.command
|
||||
./element-setup-macos.command
|
||||
```
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
Das Skript nutzt **Homebrew** (falls vorhanden):
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
Oder installiere Element manuell:
|
||||
https://element.io/download
|
||||
|
||||
---
|
||||
|
||||
## 🐧 Linux
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Lade die Datei herunter**: `element-setup-linux.sh`
|
||||
2. **Im Terminal:**
|
||||
```bash
|
||||
chmod +x element-setup-linux.sh
|
||||
./element-setup-linux.sh
|
||||
```
|
||||
|
||||
3. Das Skript wird automatisch:
|
||||
- ✅ Die config.json erstellen
|
||||
- ✅ Element Desktop installieren (über apt/dnf/pacman/zypper)
|
||||
- ✅ Element starten
|
||||
|
||||
### Unterstützte Distributionen
|
||||
|
||||
- **Ubuntu/Debian**: `apt`
|
||||
- **Fedora/RHEL**: `dnf`
|
||||
- **Arch Linux**: `pacman`
|
||||
- **openSUSE**: `zypper`
|
||||
|
||||
---
|
||||
|
||||
## ✅ Was die Skripte machen
|
||||
|
||||
Alle Skripte führen diese Schritte aus:
|
||||
|
||||
1. **config.json erstellen** im richtigen Verzeichnis:
|
||||
- **Windows**: `%APPDATA%\Element\config.json`
|
||||
- **macOS**: `~/Library/Application Support/Element/config.json`
|
||||
- **Linux**: `~/.config/Element/config.json`
|
||||
|
||||
2. **Automatische Konfiguration**:
|
||||
```json
|
||||
{
|
||||
"configUrl": "https://axion1337.chat/config.json",
|
||||
"brand": "aXion1337.Chat",
|
||||
"default_theme": "aXion1337 Dark",
|
||||
"show_labs_settings": true,
|
||||
"features": {
|
||||
"feature_qr_code_login": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Element Desktop installieren** (falls nicht vorhanden)
|
||||
|
||||
4. **Element starten** und deine Custom Themes laden
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Themes nach Setup
|
||||
|
||||
Nach dem Setup hat dein Element Desktop:
|
||||
|
||||
1. **Automatisch geladene Themes** von: `https://axion1337.chat/config.json`
|
||||
2. **Standard Theme**: aXion1337 Dark
|
||||
3. **Verfügbare Themes**:
|
||||
- aXion1337 Dark
|
||||
- Deep Purple
|
||||
- Discord Dark
|
||||
- Electric Blue
|
||||
- Everforest dark hard
|
||||
- Gruvbox Dark
|
||||
- Wal
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Manuelle Konfiguration (falls Skript nicht funktioniert)
|
||||
|
||||
Falls die Skripte nicht funktionieren, erstelle manuell die config.json:
|
||||
|
||||
### Windows
|
||||
```
|
||||
%APPDATA%\Element\config.json
|
||||
```
|
||||
|
||||
### macOS
|
||||
```
|
||||
~/Library/Application Support/Element/config.json
|
||||
```
|
||||
|
||||
### Linux
|
||||
```
|
||||
~/.config/Element/config.json
|
||||
```
|
||||
|
||||
**Inhalt** (copy-paste):
|
||||
```json
|
||||
{
|
||||
"configUrl": "https://axion1337.chat/config.json",
|
||||
"brand": "aXion1337.Chat",
|
||||
"default_theme": "aXion1337 Dark",
|
||||
"show_labs_settings": true,
|
||||
"features": {
|
||||
"feature_qr_code_login": true
|
||||
},
|
||||
"setting_defaults": {
|
||||
"custom_themes": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### Element startet nicht
|
||||
- Stelle sicher, dass Element Desktop installiert ist
|
||||
- Überprüfe den Installationspfad
|
||||
- Starten manuell: `element` (Terminal/CMD)
|
||||
|
||||
### config.json wird nicht geladen
|
||||
- Überprüfe, dass die Datei im richtigen Verzeichnis ist
|
||||
- Beende Element vollständig (auch in der Taskbar)
|
||||
- Starte Element neu
|
||||
|
||||
### Themes nicht sichtbar
|
||||
- Überprüfe Internetverbindung
|
||||
- `https://axion1337.chat/config.json` sollte erreichbar sein
|
||||
- Öffne Settings > Appearance > Theme und wähle manuell
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
- https://element.io/help
|
||||
- https://axion1337.chat
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0
|
||||
**Letztes Update**: 2026-04-23
|
||||
**Kompatibilität**: Element Desktop 1.11+
|
||||
24
Home.md
24
Home.md
@ -6,9 +6,10 @@
|
||||
|
||||
## 📖 Dokumentation
|
||||
|
||||
### Basis-Konfiguration
|
||||
### Basis & Getting Started
|
||||
- **[Installation & Setup](01-Installation.md)** – K3S, Flux CD, ESS Deployment
|
||||
- **[Task List & Roadmap](00-TASKS.md)** – Status, Prioritäten, nächste Schritte
|
||||
- **[Element Desktop Setup](Element-Desktop-Setup.md)** – Windows, macOS, Linux Setup Scripts
|
||||
|
||||
### Deployment Guides
|
||||
|
||||
@ -20,12 +21,19 @@
|
||||
| **Element Customization** | [Element-Customization.md](Element-Customization.md) | ✅ Deployed | Themes, Desktop Setup, Admin Panel |
|
||||
| **Room Policies** | [Room-Policies.md](Room-Policies.md) | ✅ Deployed | Retention, Publication, Auto-Join |
|
||||
|
||||
### Operations & Architecture
|
||||
|
||||
- **[Operations: ConfigMap Sync](Operations-ConfigMap-Sync.md)** – Automated ConfigMap updates via Git pre-commit hooks
|
||||
- **[Authentik Integration (Archive)](Authentik-Archive.md)** – Early documentation on Authentik setup
|
||||
- **[Invitation Registration (Archive)](Invitation-Registration-Archive.md)** – Invite-based registration flow
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Navigation
|
||||
|
||||
- **Getting Started**: Start with [01-Installation.md](01-Installation.md)
|
||||
- **Current Work**: See [00-TASKS.md](00-TASKS.md) for priorities and status
|
||||
- **Desktop Setup**: [Element-Desktop-Setup.md](Element-Desktop-Setup.md)
|
||||
- **Troubleshooting**: Each guide has a troubleshooting section
|
||||
|
||||
---
|
||||
@ -52,8 +60,20 @@ PostgreSQL + TURN (turn.axion1337.chat)
|
||||
- **Monitoring**: `10.0.0.3` (Selendis)
|
||||
- **Gitea Repository**: `rohana.axion1337.de/sorb/axion1337.chat-gitops`
|
||||
- **Project Board**: See Issues #3-#10 for current tasks
|
||||
- **Issues**: Critical and High priority work tracked in Gitea
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current Status
|
||||
|
||||
| Category | Count | Status |
|
||||
|----------|-------|--------|
|
||||
| **Completed** | 6 | ✅ K3S, Flux, ESS, Themes, Desktop, Monitoring, TURN |
|
||||
| **In Progress** | 1 | 🔄 Authentik Stage 2 (awaiting manual config) |
|
||||
| **Backlog** | 15+ | 📋 Element Call Fork, DB Backups, NetworkPolicies, etc. |
|
||||
| **Security** | 10 | 🔒 Firewall, SSH, auditd, Kernel hardening, CrowdSec, Falco |
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-05-15
|
||||
**Status**: 6 features deployed, 1 in progress, 15+ pending
|
||||
**Maintained by**: Claude Code + Team
|
||||
|
||||
498
Invitation-Registration-Archive.md
Normal file
498
Invitation-Registration-Archive.md
Normal file
@ -0,0 +1,498 @@
|
||||
# Invite-basierte Selbstregistrierung mit MAS in ESS Community unter Ansible und FluxCD
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Für ein entity["company","Element","matrix software company"]-basiertes ESS-Community-Deployment mit aktivem Matrix Authentication Service ist eine invite-basierte Selbstregistrierung **ohne Authentik** sauber umsetzbar. Der belastbare Weg ist: **MAS-Registrierung aktivieren, Registrierungstoken erzwingen, Tokens über die MAS Admin API erzeugen, und Standard-Onboarding über Synapse `auto_join_rooms` abbilden**. In MAS-/MSC3861-Setups sind die alten Synapse-Mechanismen für Registration Tokens bzw. Shared-Secret-Registration nicht mehr der richtige Pfad: Die Synapse-Registration-Token-API ist in diesem Modus deaktiviert, ebenso die Shared-Secret-Registration-API; die offizielle Automationsoberfläche für externe Tools ist stattdessen die MAS Admin API. citeturn1view2turn20view1turn26search11turn26search5turn35view0
|
||||
|
||||
Für die Zuweisung zu Räumen und Spaces gilt: **MAS-Claims sind für Identitätsattribute gedacht, nicht für Raum-/Space-Mitgliedschaften**. Der robuste Standard ist daher eine Zweiteilung: **allgemeine Onboarding-Räume und Spaces über Synapse `auto_join_rooms`**, und **feingranulare, zielgruppenspezifische Mitgliedschaften über einen kleinen Post-Registration-Provisioner oder ein Synapse-Modul** über `on_user_registration` bzw. `on_user_login`. Gruppen/Communities sind heute kein sinnvolles Ziel mehr, weil Synapse diese Funktion deprecated und anschließend entfernt hat; für aktuelle Deployments solltest du konsequent mit **Spaces + Rooms** arbeiten. citeturn16view0turn16view1turn16view2turn34view0turn35view0turn17search0turn17search2
|
||||
|
||||
Für GitOps empfehle ich eine klare Trennung zwischen **statischer Konfiguration** und **operativem Invite-Zustand**. Statisch in Git/SOPS/Flux gehören: MAS-Account-Settings, SMTP-Daten, der MAS-Admin-OAuth-Client und optionale Onboarding-Policies. **Kurzlebige Einmal-Tokens** sollten dagegen in der Regel **nicht** als dauerhafter Desired State in Git geführt werden, sondern bei Bedarf über die MAS Admin API erzeugt, per E-Mail verschickt und nur optional als Audit-Record abgelegt werden. Das passt deutlich besser zu FluxCD als das “GitOpsen” flüchtiger Einladungen. Die optionale LiveKit-/Element-Call-Schicht ist für den Registrierungsfluss architektonisch unabhängig. citeturn20view1turn23view0turn23view3turn25search0turn25search13
|
||||
|
||||
## Zielbild und Architektur
|
||||
|
||||
Die offizielle ESS-Dokumentation unterstützt zusätzliche Konfiguration für Synapse, MAS, Element Web und MatrixRTC/LiveKit jeweils über `additional`-Blöcke. MAS läuft dabei neben Synapse und spricht mit Synapse über den dedizierten `matrix_authentication_service`-Mechanismus; Synapse 1.136+ führt diese Integration als stabile Konfiguration. Für dein Ziel bedeutet das: ESS/Helm liefert die Plattform, MAS erzwingt die Token-basierte Registrierung, Synapse übernimmt Mitgliedschaften, und Element Web kann optional eine eigene Landing-/Invite-Seite anzeigen. citeturn1view2turn1view5turn31view1turn35view0turn24search0
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph GitOps["GitOps-Steuerung"]
|
||||
A[Ansible]
|
||||
F[FluxCD]
|
||||
G[Git Repository]
|
||||
S[SOPS Secrets]
|
||||
A --> G
|
||||
S --> G
|
||||
F --> G
|
||||
end
|
||||
|
||||
subgraph K8s["Kubernetes / ESS Helm"]
|
||||
HR[HelmRelease matrix-stack]
|
||||
EW[Element Web]
|
||||
MAS[Matrix Authentication Service]
|
||||
SYN[Synapse]
|
||||
PG[(PostgreSQL)]
|
||||
SMTP[SMTP]
|
||||
MOD[Optional: Post-Registration Provisioner / Synapse-Modul]
|
||||
LK[Optional: LiveKit / Element Call]
|
||||
end
|
||||
|
||||
G --> HR
|
||||
HR --> EW
|
||||
HR --> MAS
|
||||
HR --> SYN
|
||||
HR --> PG
|
||||
HR --> LK
|
||||
|
||||
MAS --> PG
|
||||
SYN --> PG
|
||||
MAS --> SMTP
|
||||
MAS <--> SYN
|
||||
EW --> MAS
|
||||
EW --> SYN
|
||||
|
||||
A -->|MAS Admin API| MAS
|
||||
A -->|E-Mail Einladung| User[Neuer Benutzer]
|
||||
User -->|Invite-Link + Registration Token| EW
|
||||
User -->|Registrierung| MAS
|
||||
MAS -->|User-Provisionierung| SYN
|
||||
SYN -->|auto_join_rooms| User
|
||||
MOD -->|join/invite per Synapse Admin API| SYN
|
||||
```
|
||||
|
||||
Die praktikabelste Zielarchitektur ist deshalb: **Invite-Mail → MAS Token-Registierung → Synapse-Provisionierung → automatisches Standard-Onboarding via `auto_join_rooms` → optionaler Fein-Provisioner für zusätzliche Spaces/Räume**. Für Spaces ist wichtig: Synapse behandelt Spaces “unter der Haube” als Räume, daher können Space-Aliasse in `auto_join_rooms` verwendet werden. **Automatisch erzeugen** kann Synapse über `autocreate_auto_join_rooms` jedoch **keine Spaces**; Spaces müssen also vorher existieren. citeturn16view0turn16view1turn16view5
|
||||
|
||||
Die Optionen lassen sich so einordnen:
|
||||
|
||||
| Option | Bewertung | Stärken | Schwächen | Geeignet für |
|
||||
|---|---|---|---|---|
|
||||
| MAS Registration Tokens | **Empfohlen** | Nativ im MAS-Stack, sauber mit ESS/MAS, externe Tooling-Anbindung über Admin API | Keine offizielle, dokumentierte “Einladungs-E-Mail-Engine” für Invite-Links; Token-Versand musst du selbst automatisieren | ESS Community mit FluxCD/Ansible citeturn20view1turn12view0turn37view1turn1view2 |
|
||||
| Authentik Invitations | Möglich, aber hier unnötig | Fertiges Invite-/Enrollment-Modell, URL-basierte Invitations | Zusätzlicher IdP-Layer, mehr bewegliche Teile, für dein Ziel kein Muss | Wenn ohnehin zentraler OIDC-IdP Standard ist citeturn36search0turn36search1 |
|
||||
| Manuelle Admin-Erstellung | Solide als Fallback | Maximal kontrolliert, kein Self-Service nötig | Kein Selbstregistrierungsfluss, hoher Betriebsaufwand | Break-glass, Admin-/Testkonten citeturn27view1turn26search5 |
|
||||
|
||||
Wichtig für die Zielmodellierung: **Groups/Communities** sind im aktuellen Synapse-Kontext kein tragfähiges Onboarding-Ziel mehr. Die offizielle Synapse-Kommunikation beschreibt Groups/Communities als deprecated und ab Synapse 1.61 entfernt; Spaces sind der vorgesehene Ersatz. Wenn du also “Spaces, Groups, Rooms” als Zielbild denkst, sollte die reale Implementierung **Spaces + Rooms** heißen. citeturn17search0turn17search2
|
||||
|
||||
## MAS-Konfiguration und GitOps-Manifeste
|
||||
|
||||
ESS stellt laut offizieller Doku genau den von dir benötigten Mechanismus bereit: Zusätzliche MAS-Konfiguration wird unter `matrixAuthenticationService.additional` in YAML-Fragmente gelegt und in die finale MAS-Konfiguration gemerged. Dasselbe gilt für Synapse unter `synapse.additional` und für Element Web unter `elementWeb.additional`. citeturn1view2turn31view1
|
||||
|
||||
Der kleinste sinnvolle MAS-Block für invite-basierte Self-Registration sieht so aus. Die Felder `password_registration_enabled`, `registration_token_required` und `password_registration_email_required` sind offiziell dokumentiert; ESS dokumentiert zusätzlich explizit, dass `password_registration_email_required: false` **nur** in Kombination mit Restriktionen wie `registration_token_required: true` auf öffentlich föderierenden Deployments verantwortbar ist, weil die Instanz sonst missbraucht werden kann. citeturn2view4turn20view0turn1view2
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: ess-mas-values-secret
|
||||
namespace: matrix
|
||||
stringData:
|
||||
values.yaml: |
|
||||
matrixAuthenticationService:
|
||||
additional:
|
||||
10-account.yaml:
|
||||
config: |
|
||||
passwords:
|
||||
enabled: true
|
||||
minimum_complexity: 3
|
||||
|
||||
account:
|
||||
password_registration_enabled: true
|
||||
registration_token_required: true
|
||||
password_registration_email_required: false
|
||||
password_change_allowed: true
|
||||
password_recovery_enabled: false
|
||||
login_with_email_allowed: false
|
||||
|
||||
# Optional, falls du Recoveries / Verifizierung brauchst
|
||||
email:
|
||||
from: '"Matrix Auth" <no-reply@__DOMAIN__>'
|
||||
reply_to: '"Support" <support@__DOMAIN__>'
|
||||
transport: smtp
|
||||
mode: starttls
|
||||
hostname: __SMTP_HOST__
|
||||
port: 587
|
||||
username: __SMTP_USERNAME__
|
||||
password: __SMTP_PASSWORD__
|
||||
|
||||
# Für halböffentliche Setups empfehlenswert
|
||||
captcha:
|
||||
service: cloudflare_turnstile
|
||||
site_key: __TURNSTILE_SITE_KEY__
|
||||
secret_key: __TURNSTILE_SECRET_KEY__
|
||||
|
||||
policy:
|
||||
data:
|
||||
registration:
|
||||
banned_usernames:
|
||||
literals: ["admin", "root", "support"]
|
||||
emails:
|
||||
allowed_addresses:
|
||||
suffixes: ["@example.org"]
|
||||
requester:
|
||||
banned_ips:
|
||||
- 10.0.0.0/8
|
||||
- 192.168.0.0/16
|
||||
|
||||
rate_limiting:
|
||||
registration:
|
||||
burst: 2
|
||||
per_second: 0.0003
|
||||
login:
|
||||
per_ip:
|
||||
burst: 5
|
||||
per_second: 0.02
|
||||
per_account:
|
||||
burst: 30
|
||||
per_second: 0.1
|
||||
```
|
||||
|
||||
Damit externe Tools Tokens anlegen können, muss die **MAS Admin API** aktiviert werden. Die offizielle MAS-Doku sagt ausdrücklich, dass `adminapi` nicht standardmäßig exponiert ist und in einen Listener aufgenommen werden muss; Zugriffe werden mit dem Scope `urn:mas:admin` geschützt. Für automatisierte Tools ist der dokumentierte Weg ein **OAuth-Client mit `client_credentials`**, dessen `client_id` in `policy.data.admin_clients` steht. citeturn20view1turn23view0turn23view3
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: ess-mas-admin-client
|
||||
namespace: matrix
|
||||
stringData:
|
||||
admin-client.yaml: |
|
||||
http:
|
||||
listeners:
|
||||
- name: web
|
||||
resources:
|
||||
- name: discovery
|
||||
- name: human
|
||||
- name: oauth
|
||||
- name: compat
|
||||
- name: graphql
|
||||
playground: false
|
||||
- name: assets
|
||||
path: ./share/assets/
|
||||
- name: adminapi
|
||||
binds:
|
||||
- address: "[::]:8080"
|
||||
|
||||
clients:
|
||||
- client_id: 01JV0000000000000000000001
|
||||
client_auth_method: client_secret_basic
|
||||
client_secret: "__MAS_ADMIN_CLIENT_SECRET__"
|
||||
|
||||
policy:
|
||||
data:
|
||||
admin_clients:
|
||||
- 01JV0000000000000000000001
|
||||
```
|
||||
|
||||
Dieses Secret bindest du wiederum als weiteren `additional`-Eintrag ein. So vermeidest du Dateipfad-Annahmen im Container und hältst den Client-Secret-Wert SOPS-fähig. citeturn31view1turn20view1turn23view0
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: ess-mas-values-secret
|
||||
namespace: matrix
|
||||
stringData:
|
||||
values.yaml: |
|
||||
matrixAuthenticationService:
|
||||
additional:
|
||||
20-admin-client.yaml:
|
||||
configSecret: ess-mas-admin-client
|
||||
configSecretKey: admin-client.yaml
|
||||
```
|
||||
|
||||
Für FluxCD genügt ein klassisches `valuesFrom`-Muster. Das bildet dein bestehendes Repo-Schema mit ConfigMaps/Secrets gut ab und bleibt mit SOPS kompatibel. citeturn31view1turn1view2
|
||||
|
||||
```yaml
|
||||
apiVersion: helm.toolkit.fluxcd.io/v2
|
||||
kind: HelmRelease
|
||||
metadata:
|
||||
name: matrix-stack
|
||||
namespace: matrix
|
||||
spec:
|
||||
interval: 1h
|
||||
chart:
|
||||
spec:
|
||||
chart: matrix-stack
|
||||
sourceRef:
|
||||
kind: HelmRepository
|
||||
name: element-ess-oci
|
||||
namespace: flux-system
|
||||
valuesFrom:
|
||||
- kind: ConfigMap
|
||||
name: ess-synapse-custom
|
||||
valuesKey: values.yaml
|
||||
- kind: ConfigMap
|
||||
name: ess-element-custom
|
||||
valuesKey: values.yaml
|
||||
- kind: Secret
|
||||
name: ess-mas-values-secret
|
||||
valuesKey: values.yaml
|
||||
values:
|
||||
serverName: "__SERVER_NAME__"
|
||||
postgres:
|
||||
enabled: true
|
||||
synapse:
|
||||
enabled: true
|
||||
ingress:
|
||||
host: "__SYNAPSE_HOST__"
|
||||
matrixAuthenticationService:
|
||||
enabled: true
|
||||
ingress:
|
||||
host: "__MAS_HOST__"
|
||||
elementWeb:
|
||||
enabled: true
|
||||
ingress:
|
||||
host: "__ELEMENT_HOST__"
|
||||
matrixRTC:
|
||||
enabled: true
|
||||
ingress:
|
||||
host: "__MRTC_HOST__"
|
||||
```
|
||||
|
||||
Für das automatische Standard-Onboarding nimmst du Synapse `auto_join_rooms`. Die offizielle Synapse-Doku bestätigt: neue Benutzer werden automatisch zu den gelisteten Räumen hinzugefügt; **Space-Aliasse sind erlaubt**, weil Spaces Räume sind; **Spaces werden aber nicht automatisch erzeugt**, und für private/invite-only Auto-Join-Setups muss `auto_join_mxid_localpart` gesetzt sein, wobei dieser Benutzer in den betreffenden Räumen Mitglied sein und Einladungsrechte haben muss. citeturn16view0turn16view1turn16view2
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: ess-synapse-custom
|
||||
namespace: matrix
|
||||
data:
|
||||
values.yaml: |
|
||||
synapse:
|
||||
additional:
|
||||
20-onboarding.yaml:
|
||||
config: |
|
||||
auto_join_rooms:
|
||||
- "#welcome:__SERVER_NAME__"
|
||||
- "#announcements:__SERVER_NAME__"
|
||||
- "#community-space:__SERVER_NAME__"
|
||||
|
||||
autocreate_auto_join_rooms: false
|
||||
auto_join_mxid_localpart: system
|
||||
auto_join_rooms_for_guests: false
|
||||
```
|
||||
|
||||
Für die User Experience kannst du Element Web mit einer eigenen Welcome-/Invite-Seite versehen. Offiziell unterstützt Element Web dafür `embedded_pages.welcome_url`, `login_for_welcome`, Branding-Parameter und – für native OIDC-Setups – OIDC-Client-Optionen. Für deinen Fall ist das vor allem nützlich, **weil die offizielle MAS-Dokumentation keinen stabil dokumentierten URL-Parameter zum Prefill eines Registration Tokens beschreibt**; die saubere Lösung ist daher oft eine eigene Landing-Page, die den Token erklärt oder temporär speichert und dann zum Registrierungsfluss führt. Diese Aussage ist eine Architektur-Inferenz aus den offiziellen Element- und MAS-Dokumenten. citeturn24search0turn20view1turn22view0
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: ess-element-custom
|
||||
namespace: matrix
|
||||
data:
|
||||
values.yaml: |
|
||||
elementWeb:
|
||||
additional:
|
||||
config.json: |
|
||||
{
|
||||
"embedded_pages": {
|
||||
"welcome_url": "https://__ELEMENT_HOST__/invite/index.html",
|
||||
"login_for_welcome": false
|
||||
},
|
||||
"branding": {
|
||||
"auth_header_logo_url": "https://__ELEMENT_HOST__/assets/logo.svg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Ein wichtiger Betriebs-Hinweis: Es gibt aktuell ein **offenes GitHub-Issue** im ESS-Helm-Repository, das meldet, dass `matrixAuthenticationService.additional.*` in bestimmten Konstellationen ignoriert werden könne. Das ist kein offizieller Release-Hinweis, aber als Failure-Mode ernst zu nehmen. Deshalb solltest du nach jeder Änderung das **gerenderte MAS-ConfigFile im Pod** prüfen, bevor du mit echten Einladungen arbeitest. citeturn38view0turn31view1
|
||||
|
||||
## Einladungsworkflow und Provisionierung
|
||||
|
||||
Der saubere GitOps-Ablauf ist in der Praxis fünfstufig. Zuerst legst du **statische Konfiguration** in Git ab: MAS-Settings, SMTP, Admin-Client, Synapse Auto-Join. Danach reconciled Flux diese Ressourcen in den Cluster. Anschließend erzeugt Ansible oder ein Shell-Skript **on demand** ein kurzlebiges Registration Token über die MAS Admin API. Dieses Token wird per E-Mail verschickt – entweder als Link zu deiner eigenen Invite-Landing-Page oder als Nachricht mit Token + Registrierungsanweisung. Beim ersten erfolgreichen Abschluss der Registrierung provisioniert MAS den Account in Synapse; Synapse zieht dann `auto_join_rooms`. Wenn du danach noch gezielt Spaces/Räume abhängig von Abteilung, Rolle oder Domäne vergeben willst, übernimmt das ein Provisioner oder ein Synapse-Modul. citeturn20view1turn12view0turn16view0turn34view0
|
||||
|
||||
Für die **MAS Admin API** ist der dokumentierte Automationspfad `client_credentials`. Die MAS-Doku nennt dafür explizit statische Clients + `policy.data.admin_clients`. Das Access-Token kannst du discovery-basiert holen, damit du keine Token-Endpoint-Pfade hart codierst. citeturn20view1turn22view0turn23view0
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
MAS_ISSUER="https://account.__DOMAIN__/"
|
||||
CLIENT_ID="01JV0000000000000000000001"
|
||||
CLIENT_SECRET="${MAS_ADMIN_CLIENT_SECRET}"
|
||||
|
||||
TOKEN_ENDPOINT="$(
|
||||
curl -fsSL "${MAS_ISSUER}.well-known/openid-configuration" \
|
||||
| jq -r '.token_endpoint'
|
||||
)"
|
||||
|
||||
ACCESS_TOKEN="$(
|
||||
curl -fsSL -u "${CLIENT_ID}:${CLIENT_SECRET}" \
|
||||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||||
-d 'grant_type=client_credentials' \
|
||||
-d 'scope=urn:mas:admin' \
|
||||
"${TOKEN_ENDPOINT}" \
|
||||
| jq -r '.access_token'
|
||||
)"
|
||||
|
||||
curl -fsSL -X POST "https://account.__DOMAIN__/api/admin/v1/user-registration-tokens" \
|
||||
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"usage_limit": 1,
|
||||
"expires_at": "2026-05-01T12:00:00Z"
|
||||
}' | jq
|
||||
```
|
||||
|
||||
Die MAS-OpenAPI-Spezifikation dokumentiert für Registration Tokens genau die Felder, die du dafür brauchst: `token` optional, `usage_limit`, `expires_at`, dazu die Verwaltungsendpunkte zum **Listen**, **Updaten**, **Revoken** und **Unrevoken** unter `/api/admin/v1/user-registration-tokens`. “Valid” bedeutet laut Spec: nicht abgelaufen, nicht widerrufen und Usage-Limit nicht ausgeschöpft. Für Invite-Flows solltest du in der Regel **`usage_limit: 1` und kurze Expiry-Zeiten** verwenden. citeturn12view0turn13view0turn37view0turn37view1turn37view2
|
||||
|
||||
Beispiel für Rotation bzw. Widerruf eines ungenutzten Tokens:
|
||||
|
||||
```bash
|
||||
TOKEN_ID="01JVABCDEF..."
|
||||
curl -fsSL -X POST "https://account.__DOMAIN__/api/admin/v1/user-registration-tokens/${TOKEN_ID}/revoke" \
|
||||
-H "Authorization: Bearer ${ACCESS_TOKEN}"
|
||||
```
|
||||
|
||||
Wenn du Token-Limits oder die Ablaufzeit nachträglich anpassen willst, ist laut MAS-Admin-Spec `PUT /api/admin/v1/user-registration-tokens/{id}` der vorgesehene Weg. citeturn13view0turn11view0
|
||||
|
||||
In Ansible lässt sich derselbe Flow sehr gut abbilden. Hier ein minimales Beispiel mit Discovery, Token-Erzeugung und Mailversand. Der SMTP-Provider ist bewusst als Platzhalter gelassen, weil du ihn nicht spezifiziert hast. Die Speicherung des erzeugten Registration-Tokens in Git ist **optional**; ich würde standardmäßig nur **Token-ID, Empfänger, Ablaufzeit und Versandzeitpunkt** als Audit speichern, nicht das Secret selbst. citeturn20view1turn12view0turn3view1turn2view5
|
||||
|
||||
```yaml
|
||||
- name: Discover MAS token endpoint
|
||||
ansible.builtin.uri:
|
||||
url: "https://account.__DOMAIN__/.well-known/openid-configuration"
|
||||
return_content: true
|
||||
register: oidc_discovery
|
||||
|
||||
- name: Get MAS admin access token
|
||||
ansible.builtin.uri:
|
||||
url: "{{ oidc_discovery.json.token_endpoint }}"
|
||||
method: POST
|
||||
user: "{{ mas_admin_client_id }}"
|
||||
password: "{{ mas_admin_client_secret }}"
|
||||
force_basic_auth: true
|
||||
body_format: form-urlencoded
|
||||
body:
|
||||
grant_type: client_credentials
|
||||
scope: urn:mas:admin
|
||||
return_content: true
|
||||
register: mas_oauth
|
||||
|
||||
- name: Create single-use registration token
|
||||
ansible.builtin.uri:
|
||||
url: "https://account.__DOMAIN__/api/admin/v1/user-registration-tokens"
|
||||
method: POST
|
||||
headers:
|
||||
Authorization: "Bearer {{ mas_oauth.json.access_token }}"
|
||||
body_format: json
|
||||
body:
|
||||
usage_limit: 1
|
||||
expires_at: "{{ invite_expires_at }}"
|
||||
return_content: true
|
||||
register: mas_invite
|
||||
|
||||
- name: Build invite URL
|
||||
ansible.builtin.set_fact:
|
||||
invite_url: "https://__ELEMENT_HOST__/invite/?token={{ mas_invite.json.data.attributes.token | urlencode }}"
|
||||
|
||||
- name: Send invitation email
|
||||
community.general.mail:
|
||||
host: "__SMTP_HOST__"
|
||||
port: 587
|
||||
secure: starttls
|
||||
username: "__SMTP_USER__"
|
||||
password: "__SMTP_PASSWORD__"
|
||||
to: "{{ invitee_email }}"
|
||||
from: "no-reply@__DOMAIN__"
|
||||
subject: "Deine Matrix-Einladung"
|
||||
body: |
|
||||
Hallo,
|
||||
|
||||
hier ist deine Einladung für Matrix.
|
||||
Einladung: {{ invite_url }}
|
||||
|
||||
Das Token ist einmalig nutzbar und gültig bis {{ invite_expires_at }}.
|
||||
```
|
||||
|
||||
Für die **automatische Zuweisung** zu Spaces/Räumen nach erster Anmeldung gibt es drei robuste Muster:
|
||||
|
||||
Erstens der Standardpfad über `auto_join_rooms`: ideal für **alle** neuen Benutzer, z. B. `#welcome`, `#announcements` und ein Haupt-Space. Das ist die einfachste und offizielle Lösung. Zweitens ein **Post-Registration-Provisioner**, der den Benutzer zusätzlich in weitere Räume einlädt oder joined. Dafür ist der offizielle Synapse-Admin-Endpunkt `POST /_synapse/admin/v1/join/<room_id_or_alias>` gedacht. Drittens ein **Synapse-Modul**, das `on_user_registration` oder `on_user_login` implementiert. Die Primärdoku beschreibt genau diese Callback-Punkte; seit Synapse 1.135 müssen Module allerdings worker-safe sein, weil `on_user_registration` auch auf Workern laufen kann. citeturn16view0turn27view0turn34view0turn35view0
|
||||
|
||||
Ein Provisioner gegen die Synapse Admin API kann so aussehen. Dabei setze ich voraus, dass du bereits einen **user-bound** Synapse-Admin-Token hast; dafür verweist die offizielle MAS-Doku auf den Device-Code-Flow mit Synapse-Admin-Scopes. Dasselbe Dokument zeigt auch, wie man kombinierte MAS-/Synapse-Admin-Tokens interaktiv anfordern kann. citeturn27view0turn32search1turn32search0
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SYNAPSE_BASE="https://matrix.__DOMAIN__"
|
||||
SYNAPSE_ADMIN_TOKEN="${SYNAPSE_ADMIN_TOKEN}"
|
||||
USER_ID="$1"
|
||||
|
||||
join_room() {
|
||||
local alias="$1"
|
||||
curl -fsSL -X POST \
|
||||
-H "Authorization: Bearer ${SYNAPSE_ADMIN_TOKEN}" \
|
||||
-H 'Content-Type: application/json' \
|
||||
"${SYNAPSE_BASE}/_synapse/admin/v1/join/${alias}" \
|
||||
-d "{\"user_id\":\"${USER_ID}\"}" >/dev/null
|
||||
}
|
||||
|
||||
join_room "#community-space:__SERVER_NAME__"
|
||||
join_room "#announcements:__SERVER_NAME__"
|
||||
join_room "#team-general:__SERVER_NAME__"
|
||||
```
|
||||
|
||||
Wichtig ist hier die Abgrenzung zu “Claim Mappings”: Die offizielle MAS-OIDC-Doku beschreibt `claims_imports` für **`localpart`**, **`displayname`**, **`email`** und **`account_name`**. Daraus folgt: Claim-Mappings sind nützlich, wenn du später doch einen Upstream-OIDC-Provider ergänzen willst, aber sie lösen **nicht** die Mitgliedschaft in Spaces/Räumen. Für deinen Authentik-freien Invite-Flow ist das korrekte Modell also **Token + Synapse-Onboarding**, nicht “Claims → Rooms”. citeturn21search1turn9search4
|
||||
|
||||
## Sicherheit und Betriebsmodell
|
||||
|
||||
Die sicherste Konfiguration für dein Szenario ist nicht “offene Registrierung mit etwas Deko”, sondern **echte Invite-only-Registrierung**. Das bedeutet konkret: `password_registration_enabled: true`, `registration_token_required: true` und nur dann `password_registration_email_required: false`, wenn du bewusst auf Token-Schutz, kurze Laufzeiten, Single-Use und gute Missbrauchsbarrieren setzt. Genau davor warnt die ESS-Doku ausdrücklich: Ein öffentlich föderierender Server ohne Mailpflicht **und** ohne starke Restriktionen wird missbraucht. citeturn2view4turn20view0turn1view2
|
||||
|
||||
Ich würde die Sicherheitsprofile so priorisieren:
|
||||
|
||||
| Profil | Empfohlene Settings | Wann sinnvoll | Kommentar |
|
||||
|---|---|---|---|
|
||||
| Striktes Invite-only | `password_registration_enabled: true`, `registration_token_required: true`, `password_registration_email_required: false`, `usage_limit: 1`, kurze Expiry | Kleine Community, kuratierte Benutzerbasis | Beste Mischung aus UX und Missbrauchsschutz citeturn2view4turn12view0turn37view2 |
|
||||
| Invite-only mit Recovery | Wie oben, aber `password_recovery_enabled: true` und SMTP voll konfiguriert | Wenn Nutzer Self-Service-Passwort-Reset brauchen | Erhöht Komfort, verlangt sauberen Mailbetrieb citeturn2view4turn2view5 |
|
||||
| Halböffentlich | Tokenpflicht + CAPTCHA + E-Mail-Allowlist + restriktivere Rate-Limits | Wenn Einladungen wiederverwendbar oder breiter verteilt werden | Mehr Schutz gegen Bot-/Spam-Missbrauch citeturn3view2turn20view0turn3view1 |
|
||||
|
||||
Zu den wichtigsten Härtungsmaßnahmen gehören: **Single-Use (`usage_limit: 1`)**, **kurze Gültigkeit**, **Rate Limits für Registrierungen**, **optional CAPTCHA**, **optional Domain-Allowlist für E-Mails**, **Banned IP/User-Agent-Regeln** und ein **interner oder streng geschützter MAS-Admin-API-Zugang**. MAS dokumentiert all diese Stellhebel explizit: `policy.data.registration.*`, `emails.allowed_addresses`, `requester.banned_ips`, CAPTCHA-Provider und `rate_limiting.registration`. citeturn20view0turn3view1turn3view2turn2view5
|
||||
|
||||
Für die Raum-/Space-Seite gilt zusätzlich: Halte sensible Onboarding-Räume **invite-only** und vermische “öffentlich sichtbare Discovery” nicht mit einem privaten Invite-Modell. Die Matrix-/Synapse-Dokumentation empfiehlt bei privaten Setups ausdrücklich, die Sichtbarkeit öffentlicher Räume restriktiv zu halten; Synapse hat die Standardregeln für Room-Directory-Publikation in neueren Versionen auch bewusst verschärft. citeturn17search6turn35view0
|
||||
|
||||
Ein subtiler, aber wichtiger Punkt ist die Trennung von **MAS Admin** und **Synapse Admin**. Offiziell ist `urn:mas:admin` für automatisierte `client_credentials`-Tools dokumentiert. Für `urn:synapse:admin:*` beschreibt die Scope-Referenz dagegen ein benutzergebundenes Modell; außerdem braucht Synapse-Admin zusätzlich die Matrix-API-Scopes. Daraus folgt als belastbare Betriebsregel: **Reine Maschinenautomation sollte primär MAS Admin API nutzen; Synapse-Admin-Aktionen entweder über Auto-Join, über ein Synapse-Modul oder über einen echten Service-User mit benutzergebundenem Admin-Token**. citeturn20view1turn32search0turn32search1
|
||||
|
||||
## Tests, Rollout und Recovery
|
||||
|
||||
Der Rollout sollte nicht mit echten Einladungen beginnen, sondern mit einem **vollständigen Dry-Run auf Staging oder einem Testkonto**. Zuerst reconcile-st du Flux, dann prüfst du das HelmRelease und die gerenderte MAS-Konfiguration. Danach testest du die MAS Admin API, erzeugst ein kurzes Einmal-Token, registrierst einen neuen Testnutzer, überprüfst `times_used`/`valid`, kontrollierst die Raum-/Space-Mitgliedschaften und widerrufst übrige Tokens. Damit deckst du sowohl die ESS-/MAS-Seite als auch die Synapse-Onboarding-Seite einmal komplett ab. citeturn20view1turn12view0turn16view0turn27view0
|
||||
|
||||
Die fachliche Checkliste dafür ist kurz, aber strikt:
|
||||
|
||||
- **Konfiguration vorhanden:** `matrixAuthenticationService.additional` und `synapse.additional` sind im gerenderten Config-Output sichtbar. Wegen des offenen ESS-Issues zu `additional.*` solltest du das aktiv prüfen. citeturn31view1turn38view0
|
||||
- **MAS Admin API erreichbar:** `/api/spec.json` bzw. das Anlegen eines Tokens funktioniert mit `urn:mas:admin`. citeturn20view1turn10view0
|
||||
- **Token-Lebenszyklus korrekt:** neues Token erscheint als `valid`, nach Nutzung steigt `times_used`, bei `usage_limit: 1` ist es anschließend nicht mehr gültig. citeturn12view0turn37view2
|
||||
- **Onboarding korrekt:** Testnutzer landet im Haupt-Space, in Welcome/Announcements und – falls aktiviert – in weiteren Zielräumen. citeturn16view0turn27view0
|
||||
- **Missbrauchsschutz greift:** Ablaufzeit, CAPTCHA, Rate-Limits und Policy-Regeln sind aktiv. citeturn3view1turn3view2turn20view0
|
||||
|
||||
Die wichtigsten Failure Modes und ihre Recovery-Schritte sind diese:
|
||||
|
||||
| Symptom | Wahrscheinliche Ursache | Recovery |
|
||||
|---|---|---|
|
||||
| Registrierung fordert trotzdem E-Mail-Verifikation | `password_registration_email_required` ist noch `true` oder falsches MAS-Configfile aktiv | Gerendertes MAS-Configfile prüfen, Werte korrigieren, neu deployen citeturn2view4turn1view2turn38view0 |
|
||||
| `403` bei Token-Erzeugung | OAuth-Client nicht in `policy.data.admin_clients` oder falscher Scope | Client-/Policy-Fragment korrigieren, neuen Access Token holen citeturn20view1turn23view3 |
|
||||
| `404` auf `/api/admin/v1/...` | `adminapi` nicht in `http.listeners.resources` aktiviert | Listener-Block korrigieren und Redeploy citeturn20view1 |
|
||||
| User landet nicht im Space | Space existiert nicht, Space wurde nicht separat angelegt, oder `auto_join_mxid_localpart`-User kann nicht einladen | Space vorab anlegen, `system`-User joinen lassen, Rechte prüfen; Spaces werden nicht automatisch erstellt citeturn16view0turn16view1turn16view2 |
|
||||
| Feingranulare Raumzuweisung klappt nicht | Du versuchst Membership über Claim-Mapping zu lösen | Membership über Auto-Join, Provisioner oder Synapse-Modul abbilden citeturn21search1turn34view0 |
|
||||
| “Groups” lassen sich nicht mehr sinnvoll zuweisen | Groups/Communities sind im aktuellen Synapse-Modell entfernt | Auf Spaces + Rooms umstellen citeturn17search0turn17search2 |
|
||||
|
||||
Wenn ein Invite-Token versehentlich verschickt wurde, ist der saubere Recovery-Schritt **nicht** das HelmRelease zu verändern, sondern das Token per MAS Admin API zu **revoken** und bei Bedarf ein neues zu erzeugen. Wenn ein Benutzer zwar registriert wurde, aber Raumzuweisungen fehlen, ist die schnellste operative Korrektur ein nachgelagerter Join über den Synapse-Admin-Endpunkt. Wenn ein Synapse-Modul dafür verantwortlich ist, beachte die Worker-Eigenschaft von `on_user_registration`. citeturn13view0turn27view0turn35view0
|
||||
|
||||
## Quellenbasis und offene Punkte
|
||||
|
||||
Die belastbarsten Primärquellen für dieses Design sind die offiziellen Dokumentationen zu ESS, MAS, Synapse, Element Web und LiveKit. Für den Vergleichspfad “Authentik Invitations” ist die offizielle Authentik-Doku hinzugezogen worden.
|
||||
|
||||
Die Priorisierung war dabei:
|
||||
|
||||
- ESS Advanced-Doku zur Einbindung zusätzlicher Konfigurationsdateien für MAS, Synapse, Element Web und MatrixRTC. citeturn1view2
|
||||
- ESS Chart-Values zur Bestätigung, dass `matrixAuthenticationService.additional`/`synapse.additional`/`elementWeb.additional` offizielle Wertepfade sind. citeturn31view1turn31view4
|
||||
- MAS-Konfigurationsreferenz für `account.*`, `captcha`, `policy`, `rate_limiting`, `email`, `clients`, `admin_clients` und HTTP-Listener. citeturn2view4turn20view0turn22view0turn23view0
|
||||
- MAS Admin API und OpenAPI-Schema für Token-Erzeugung, Update, Revoke, Validitätsbegriff und Automationsmodell. citeturn20view1turn12view0turn13view0turn37view1turn37view2
|
||||
- MAS Scope- und Access-Token-Doku für den Unterschied zwischen `urn:mas:admin` und benutzergebundenem Synapse-Admin-Zugriff. citeturn32search0turn32search1
|
||||
- Synapse-Konfigurationsmanual für `auto_join_rooms`, Space-Aliasse, `autocreate_auto_join_rooms` und `auto_join_mxid_localpart`. citeturn16view0turn16view1turn16view2
|
||||
- Synapse-Admin- und Modul-Doku für Raumzuweisung per API und Callback-Punkte `on_user_registration` / `on_user_login`. citeturn27view0turn34view0turn35view0
|
||||
- Element-Web-Konfiguration für Welcome-/Branding-/OIDC-nahe UX-Optionen. citeturn24search0
|
||||
- LiveKit-/Element-Call-Doku als optionale, vom Registrierungsfluss getrennte RTC-Schicht. citeturn25search0turn25search13
|
||||
- Authentik-Invitationsdoku nur für den Vergleich innerhalb der Optionen-Tabelle. citeturn36search0turn36search1
|
||||
|
||||
Offen beziehungsweise bewusst konservativ behandelt bleiben drei Punkte. Erstens beschreibt die offizielle MAS-Dokumentation nach dem hier ausgewerteten Stand **keinen stabil dokumentierten Invite-Link-Parameter**, mit dem ein Registration Token sicher per URL in die MAS-UI vorbefüllt wird; deshalb empfehle ich eine eigene Landing-Page oder Token-Übermittlung im Mailtext. Zweitens ist **client_credentials** sauber für die **MAS Admin API** dokumentiert, nicht aber als Standardmuster für **Synapse-Admin-Automation**; für Synapse-Onboarding ist deshalb `auto_join_rooms` oder ein user-/modulbasierter Pfad robuster. Drittens gibt es aktuell ein offenes ESS-Helm-Issue zu `matrixAuthenticationService.additional.*`; deshalb solltest du das gerenderte MAS-Configfile im Deployment immer verifizieren, bevor du produktive Einladungen versendest. citeturn20view1turn32search0turn38view0
|
||||
|
||||
12083
Old-Home.md
Normal file
12083
Old-Home.md
Normal file
File diff suppressed because it is too large
Load Diff
296
Operations-ConfigMap-Sync.md
Normal file
296
Operations-ConfigMap-Sync.md
Normal file
@ -0,0 +1,296 @@
|
||||
# 🔄 GitOps ConfigMap Auto-Sync via Checksums
|
||||
|
||||
Dieses Dokument erklärt ein Kernproblem mit **Flux CD** und **externe Konfigurationen** – und wie wir es gelöst haben.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Das Problem: Flux erkennt ConfigMap-Änderungen nicht
|
||||
|
||||
### Die Situation
|
||||
|
||||
Unsere HelmRelease (`element-server-suite.yaml`) nutzt `valuesFrom`, um Konfigurationen aus externen **ConfigMaps** zu laden:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
valuesFrom:
|
||||
- kind: ConfigMap
|
||||
name: ess-element-custom # ← Diese ConfigMap
|
||||
valuesKey: values.yaml
|
||||
- kind: ConfigMap
|
||||
name: ess-synapse-custom # ← Diese ConfigMap
|
||||
valuesKey: values.yaml
|
||||
```
|
||||
|
||||
Diese ConfigMaps entstehen aus Dateien im Git-Repo (`apps/production/custom-configs/*.yaml`) und werden von Kustomize in den Cluster deployed.
|
||||
|
||||
### Das Kernproblem
|
||||
|
||||
**Flux CD reagiert NICHT automatisch, wenn sich eine ConfigMap ändert.**
|
||||
|
||||
Warum? Flux überwacht nur das Git-Repository auf Änderungen. Wenn du `element-values.yaml` änderst:
|
||||
|
||||
1. ✅ Flux sieht die Änderung im Git-Repo
|
||||
2. ✅ Kustomize erzeugt eine neue ConfigMap mit den neuen Werten
|
||||
3. ❌ Aber Helm (der Helm-Controller in Flux) erkennt **nicht**, dass sich die externe ConfigMap geändert hat
|
||||
4. ❌ Helm deployt das Chart nicht neu → Die alten Themes/Configs bleiben aktiv
|
||||
|
||||
Das ist kein Bug, sondern by-design: Helm achtet nur auf:
|
||||
- Chart-Version (z.B. `26.4.0`)
|
||||
- Änderungen in den direkten `values:` Blöcken
|
||||
- Nicht auf externe Quellen wie ConfigMaps
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Die Lösung: Checksums als Trigger
|
||||
|
||||
Wir nutzen **Annotations mit Checksums** als Workaround:
|
||||
|
||||
```yaml
|
||||
apiVersion: helm.toolkit.fluxcd.io/v2
|
||||
kind: HelmRelease
|
||||
metadata:
|
||||
annotations:
|
||||
element-config-checksum: "401f8a87d0ef5d91d2e5032d4aede42c" # ← Hash der element-values.yaml
|
||||
synapse-config-checksum: "e98fe81141f52e7ea833596ca39853b9" # ← Hash der synapse-values.yaml
|
||||
```
|
||||
|
||||
Wenn sich der Annotation-Wert ändert, sieht Flux, dass die **HelmRelease selbst** sich geändert hat – und deployt neu.
|
||||
|
||||
### Automatisierung via Git Pre-Commit Hook
|
||||
|
||||
Das Problem: Wer aktualisiert die Checksums, wenn man `element-values.yaml` editiert?
|
||||
|
||||
**Lösung:** Ein Git **pre-commit Hook** tut das automatisch:
|
||||
|
||||
```bash
|
||||
$ vi apps/production/custom-configs/element-values.yaml
|
||||
# (Farbe ändern, Theme hinzufügen, …)
|
||||
|
||||
$ git add apps/production/custom-configs/element-values.yaml
|
||||
$ git commit -m "feat: new theme"
|
||||
# ← Der Hook läuft jetzt:
|
||||
# 1. Berechnet MD5-Hash der neuen element-values.yaml
|
||||
# 2. Aktualisiert die Annotation in kustomization.yaml
|
||||
# 3. Added kustomization.yaml zum Commit automatisch
|
||||
```
|
||||
|
||||
Der User muss **nichts Zusätzliches tun** – alles läuft automatisch.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Installation
|
||||
|
||||
Nach dem Repository **klonen**, führe dieses Skript aus:
|
||||
|
||||
```bash
|
||||
cd prod/gitops
|
||||
./scripts/install-hooks.sh
|
||||
```
|
||||
|
||||
Das Skript:
|
||||
- ✅ Erstellt einen Symlink `.git/hooks/pre-commit` → `scripts/hooks/pre-commit`
|
||||
- ✅ Macht die Hook-Datei ausführbar
|
||||
- ✅ Gibt dir eine Bestätigungsmeldung
|
||||
|
||||
**Einmalig pro lokales Repository.** Neue Klone müssen den Hook auch installieren.
|
||||
|
||||
---
|
||||
|
||||
## 📝 Workflow: ConfigMaps ändern
|
||||
|
||||
So sieht die Praxis aus:
|
||||
|
||||
### 1️⃣ Änderung machen
|
||||
|
||||
```bash
|
||||
vi apps/production/custom-configs/element-values.yaml
|
||||
# Edit: Themes, Farben, Logging-Level, etc.
|
||||
```
|
||||
|
||||
### 2️⃣ Committen (Hook läuft automatisch)
|
||||
|
||||
```bash
|
||||
git add apps/production/custom-configs/element-values.yaml
|
||||
git commit -m "feat: add Dark Purple theme variant"
|
||||
|
||||
# Pre-Commit Hook läuft automatisch:
|
||||
# → Berechnet neuen Hash
|
||||
# → Updated kustomization.yaml
|
||||
# → Added kustomization.yaml zum Commit
|
||||
```
|
||||
|
||||
### 3️⃣ Überprüfung (optional)
|
||||
|
||||
```bash
|
||||
# Schaue, was committet wird:
|
||||
git show --stat
|
||||
|
||||
# Output sollte zeigen:
|
||||
# element-values.yaml (modified)
|
||||
# kustomization.yaml (modified) ← vom Hook hinzugefügt
|
||||
```
|
||||
|
||||
### 4️⃣ Pushen & Deployen
|
||||
|
||||
```bash
|
||||
git push
|
||||
# ← Flux sieht die Änderung an kustomization.yaml
|
||||
# ← HelmRelease wird neu-synced mit den neuen Checksums
|
||||
# ← Die neue Config ist in ~5 Minuten aktiv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Technische Details
|
||||
|
||||
### Welche Dateien sind "überwacht"?
|
||||
|
||||
Der Hook beobachtet:
|
||||
|
||||
| Datei | Annotation | Ziel |
|
||||
|-------|-----------|------|
|
||||
| `apps/production/custom-configs/element-values.yaml` | `element-config-checksum` | Element Web Themes, Branding |
|
||||
| `apps/production/custom-configs/synapse-values.yaml` | `synapse-config-checksum` | Synapse Logging, Federation |
|
||||
|
||||
### Hook-Implementation
|
||||
|
||||
Der Hook (`scripts/hooks/pre-commit`) macht folgendes:
|
||||
|
||||
1. Prüft, ob eine der überwachten Dateien geändert wurde (`git diff --cached`)
|
||||
2. Berechnet den MD5-Hash der Datei (kompatibel mit macOS/Linux)
|
||||
3. Ersetzt den Hash-Wert in `apps/production/kustomization.yaml` via `sed`
|
||||
4. Added `kustomization.yaml` automatisch zum Commit mit `git add`
|
||||
|
||||
```bash
|
||||
# Beispiel: element-values.yaml ändert sich von
|
||||
value: "401f8a87d0ef5d91d2e5032d4aede42c" # element-config
|
||||
# zu
|
||||
value: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" # element-config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Häufige Fragen
|
||||
|
||||
### F: Was passiert, wenn der Hook fehlschlägt?
|
||||
|
||||
A: Der Commit wird **abgebrochen**. Du siehst eine Fehlermeldung. Typische Gründe:
|
||||
- `md5` oder `md5sum` nicht installiert (sehr unwahrscheinlich)
|
||||
- `sed` Syntax-Fehler (sehr selten)
|
||||
|
||||
Lass dich nicht entmutigen – rufe denen auf, die das Setup machen 🚀
|
||||
|
||||
### F: Kann ich den Hook deaktivieren?
|
||||
|
||||
A: Ja, aber bitte nicht! Wenn du temporär ohne Hook arbeiten möchtest:
|
||||
|
||||
```bash
|
||||
git commit --no-verify
|
||||
```
|
||||
|
||||
Das umgeht den Hook einmalig. Danach musst du die Checksums manuell aktualisieren.
|
||||
|
||||
### F: Der Hook touched `kustomization.yaml`, obwohl ich sie nicht editiert habe?
|
||||
|
||||
A: Das ist **Absicht**. Der Hook updated **nur** die Checksums, nicht den Rest der Datei. Das ist sauber und Git-freundlich.
|
||||
|
||||
### F: Was wenn ich mehrere ConfigMaps gleichzeitig ändere?
|
||||
|
||||
A: Der Hook aktualisiert **alle** deren Checksums in einem Pass. Keine Probleme.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Verifikation: Hook funktioniert?
|
||||
|
||||
Teste es selbst:
|
||||
|
||||
```bash
|
||||
# 1. Hook installieren
|
||||
./scripts/install-hooks.sh
|
||||
|
||||
# 2. Eine Teständerung machen
|
||||
echo "# Test" >> apps/production/custom-configs/element-values.yaml
|
||||
|
||||
# 3. Committen
|
||||
git add apps/production/custom-configs/element-values.yaml
|
||||
git commit -m "test: verify hook"
|
||||
|
||||
# 4. Überprüfung: Wurde kustomization.yaml auto-updated?
|
||||
git diff HEAD~1 apps/production/kustomization.yaml | grep -i checksum
|
||||
|
||||
# Output sollte zeigen, dass ein Checksum sich geändert hat
|
||||
```
|
||||
|
||||
Wenn ja → Hook funktioniert! ✅
|
||||
Wenn nein → Rufe uns an 📞
|
||||
|
||||
---
|
||||
|
||||
## 📚 Zusammenhang mit Flux CD
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Git Repository (axion1337.chat-gitops) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ apps/production/custom-configs/ │
|
||||
│ ├── element-values.yaml (du änderst das) │
|
||||
│ ├── synapse-values.yaml │
|
||||
│ └── mas-secret.yaml │
|
||||
│ │
|
||||
│ apps/production/ │
|
||||
│ └── kustomization.yaml (Hook updated die Checksums hier) │
|
||||
│ │
|
||||
│ apps/production/ │
|
||||
│ └── element-server-suite.yaml (HelmRelease mit Annotations)│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓ git push
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ FluxCD im Kubernetes-Cluster │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. GitRepository Source │
|
||||
│ └─ Fetcht dein Repo alle 10 Minuten │
|
||||
│ │
|
||||
│ 2. Kustomization production-apps │
|
||||
│ └─ Applyt die Kustomize-Overlays │
|
||||
│ └─ Erzeugt ConfigMaps mit neuen Werten │
|
||||
│ │
|
||||
│ 3. HelmRelease matrix-stack │
|
||||
│ └─ Sieht neue Annotations (Checksums) │
|
||||
│ └─ Deployt Helm-Chart mit neuen Werten │
|
||||
│ │
|
||||
│ 4. Element Web Pods │
|
||||
│ └─ Restarten automatisch │
|
||||
│ └─ Laden neue Config aus der ConfigMap │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Notfall: Manuelle Checksum-Aktualisierung
|
||||
|
||||
Falls der Hook ausfällt (z.B. weil Git Hooks in CI deaktiviert sind), kannst du Checksums manuell aktualisieren:
|
||||
|
||||
```bash
|
||||
# 1. Neuen Hash berechnen
|
||||
md5sum apps/production/custom-configs/element-values.yaml
|
||||
# Output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 apps/production/custom-configs/element-values.yaml
|
||||
|
||||
# 2. Annotation in kustomization.yaml updaten
|
||||
vi apps/production/kustomization.yaml
|
||||
# Ändere: value: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" # element-config
|
||||
|
||||
# 3. Committen
|
||||
git add apps/production/kustomization.yaml
|
||||
git commit -m "fix: manual checksum update"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0
|
||||
**Letztes Update:** 2026-05-14
|
||||
**Kompatibilität:** FluxCD 2.x, Kustomize 5.x+
|
||||
Loading…
x
Reference in New Issue
Block a user