fix(restore): harden restore checks and add authelia smoke scaffold

2026-06-03 07:39:05 +02:00
parent e2624796f0
commit b1ae9f3c26
24 changed files with 821 additions and 81 deletions
@@ -0,0 +1,94 @@
+# Authelia Restore Test Plan
+
+## Ziel
+
+Nachweisen, dass die Authelia-Konfiguration aus dem produktiven Borg-Archiv in einer isolierten Testumgebung wieder lauffaehig ist und der HTTP-Health-Endpunkt antwortet, ohne dass dabei produktive Secrets, produktives Postgres oder produktiver SMTP-Versand beruehrt werden.
+
+Bewusst **nicht** Teil dieses Tests:
+
+- Restore mit produktiven Authelia-Secrets. Der Test nutzt ausschliesslich Wegwerf-Werte fuer `AUTHELIA_JWT_SECRET`, `AUTHELIA_SESSION_SECRET`, `AUTHELIA_STORAGE_ENCRYPTION_KEY`, `AUTHELIA_STORAGE_POSTGRES_PASSWORD`, `AUTHELIA_NOTIFIER_SMTP_PASSWORD`. Eine Echtsession auf produktiven Daten waere fachlich nicht sinnvoll.
+- SMTP-Realanruf an GMX. Notifier wird im Test-Overlay auf Filesystem umgebogen.
+- Forward-Auth gegen Traefik. Test laeuft nur auf `127.0.0.1:19091`, keine Traefik-Route.
+- WebAuthn-/Duo-/OIDC-Identity-Provider-Endpunkte. Smoke prueft `/api/health`.
+
+## Quelle
+
+- Backup-Quelle: produktives Borg-Archiv (`hetzner_borg_appdata_critical`)
+- fachlich relevante Pfade im Archiv:
+  - `local/appdata/authelia/config` (verpflichtend)
+  - `local/borg-dumps/latest/postgresql17-authelia.dump` (optional, wenn vorhanden)
+- produktive Secrets unter `/mnt/user/appdata/secrets/authelia_*.txt` werden **nicht** gemountet
+
+## Test-Ziel
+
+- Restore-Lab: `/mnt/user/backups/restore-lab/authelia`
+- Testdatenpfade:
+  - `/mnt/user/backups/restore-lab/authelia/config` (restaurierte configuration.yml + Test-Overlay)
+  - `/mnt/user/backups/restore-lab/authelia/postgres` (Test-Postgres-Datadir)
+  - `/mnt/user/backups/restore-lab/authelia/dumps/latest/postgresql17-authelia.dump` (falls extrahiert)
+  - `/mnt/user/backups/restore-lab/authelia/config/notifier/notifications.txt` (Filesystem-Notifier-Ausgabe)
+- Testcontainer:
+  - `restoretest-authelia` (Image-Pin wie Produktion)
+  - `restoretest-authelia-postgres` (postgres:18.4, gleiche Major wie shared Postgres)
+- Testport: `127.0.0.1:19091:9091`
+- Report-Ziel: `/mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md`
+
+## Schutzregeln
+
+- produktive Pfade `/mnt/user/appdata/authelia/*` werden **nicht** beschrieben
+- produktive Secret-Dateien `/mnt/user/appdata/secrets/authelia_*.txt` werden **nicht** gemountet
+- produktive shared PostgreSQL 18 wird **nicht** angesprochen (Test-Overlay zwingt `storage` auf Test-Postgres)
+- echter SMTP-Versand wird **nicht** ausgeloest (Test-Overlay zwingt `notifier` auf Filesystem)
+- produktive Domain `auth.kaleschke.info` wird **nicht** uebernommen
+- Testcontainer publishen nur auf `127.0.0.1`, keine LAN-/Tailscale-Bindung
+- Borg-Passphrase wird aus `/mnt/user/appdata/secrets/borg_repo_passphrase.txt` gelesen und nirgendwo geloggt
+
+## Geplanter Ablauf
+
+1. Restore-Lab-Pfade leer anlegen
+2. `local/appdata/authelia/config` aus dem aktuellsten Borg-Archiv extrahieren
+3. optional `local/borg-dumps/latest/postgresql17-authelia.dump` extrahieren; wenn nicht im Archiv vorhanden, weiter ohne DB-Restore
+4. Test-Overlay-Datei `configuration.test-overlay.yml` neben die restaurierte `configuration.yml` schreiben (zwingt storage/notifier/session auf Test-Werte)
+5. Test-Postgres mit `ops/restore-tests/authelia-compose.test.yml` hochfahren
+6. optional Dump per `pg_restore -Fc --clean --if-exists --no-owner --no-privileges` einspielen (mit transientem Retry wie im Immich-/Paperless-Test)
+7. `authelia config validate` mit beiden Configdateien laufen lassen
+8. `restoretest-authelia` starten und HTTP-Health `http://127.0.0.1:19091/api/health` pollen
+9. Report unter `/mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md` schreiben
+10. Testcontainer stoppen und Restore-Lab bereinigen (`--keep-data` ueberschreibt)
+
+## Smoke-Test
+
+Minimal erfolgreich:
+
+- Borg-Extract der Authelia-Config gelingt
+- Test-Postgres startet `healthy`
+- `authelia config validate` laeuft ohne Fehler durch
+- HTTP `200` auf `/api/health` innerhalb 120 s
+
+Optional spaeter:
+
+- vollstaendigen Auth-Flow gegen Test-User aus `users_database.yml` durchspielen
+- WebAuthn-Endpunkt /api/secondfactor/webauthn pruefen
+- ForwardAuth-Pfad gegen Mock-Backend testen
+
+## Bekannte Komplikationen
+
+| Risiko | Beschreibung | Mitigation |
+|---|---|---|
+| Overlay-Konflikt mit Originalkonfiguration | `configuration.yml` definiert ggf. Sections, die das Overlay nicht ueberschreibt | bei `config validate`-Fehler `configuration.yml.original` zum Vergleich pruefen; Overlay erweitern |
+| SMTP-Startup-Check blockiert Start | Wenn Authelia trotz `disable_startup_check` SMTP probiert | Container-Logs lesen, ggf. Notifier-Block weiter haerten |
+| Postgres-Schema-Drift nach Major-Update | Authelia migriert Schema beim Start; Dump aus 17er-Cluster kann unter 18er andere Indexe brauchen | Smoke ist DB-Schema-tolerant; bei Validierung Logs auf `migration` pruefen |
+| identity_validation Block fehlt im Original | Aelteres Authelia-Schema kennt den Block nicht; Overlay fuegt ihn an | Validate-Config Output lesen, ggf. Overlay anpassen |
+| users_database.yml mit produktiven Hashes | Daten werden ins Restore-Lab kopiert, aber niemals gemountet auf produktive Domain | OK; Testpfad ist isoliert, kein Browser-Zugang ueber LAN |
+
+## Noch offen vor dem ersten echten Lauf
+
+- Erstlauf `--what-if` als Plan-Check
+- Erstlauf `--keep-data` zur Beobachtung von SMTP-Startup-Verhalten
+- Validate-Config-Output zum Authelia-Schema-Stand pruefen
+- nach Erfolg: Schedule-Eintrag analog zu Vaultwarden (2. Samstag in geraden Monaten als Vorschlag, damit nicht mit Paperless kollidiert)
+
+## Status
+
+- Skript- und Compose-Scaffold abgelegt am 2026-06-02
+- **noch kein echter Mini-Restore gelaufen** - erster Lauf braucht Operator-Freigabe