homelab-infra/ops/restore-tests/authelia-plan.md

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 in der Test-Konfiguration 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.original + erzeugte configuration.restoretest.yml)
  • /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 (configuration.restoretest.yml zwingt storage auf Test-Postgres)
• echter SMTP-Versand wird nicht ausgeloest (configuration.restoretest.yml 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. configuration.restoretest.yml aus der restaurierten configuration.yml erzeugen: produktive storage/notifier/session/JWT-Bloecke entfernen und Test-Werte anhaengen
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 gegen configuration.restoretest.yml 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
Sanitizing-Konflikt mit Originalkonfiguration	configuration.yml definiert neue produktive Sections, die ersetzt werden muessen	bei config validate-Fehler configuration.yml.original zum Vergleich pruefen; Strip-Liste oder Test-Block im Skript 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 Schema-Drift	Aelteres/neueres Authelia-Schema erwartet andere Keys	Validate-Config Output lesen, ggf. Test-Block 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