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 Originalkonfiguration + `configuration.yml.original`)
  - `/mnt/user/backups/restore-lab/authelia/test-config` (Runtime-Mount mit sanitizter `configuration.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/test-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-config/configuration.yml` zwingt `storage` auf Test-Postgres)
- echter SMTP-Versand wird **nicht** ausgeloest (`test-config/configuration.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. `test-config/configuration.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 `test-config/configuration.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