Add validated Paperless restore test pattern

2026-05-07 11:01:27 +02:00
parent d351b1cac8
commit 2cc39c73f6
8 changed files with 309 additions and 7 deletions
@@ -0,0 +1,115 @@
+# Paperless Restore Runbook
+
+## Vorbedingungen
+
+- Borg-Quelle ist verfuegbar
+- Borg-Passphrase-Datei vorhanden: `/mnt/user/appdata/secrets/borg_repo_passphrase.txt`
+- aktueller Dump vorhanden: `/mnt/user/backups/borg/dumps/latest/postgresql17-paperless.dump`
+- Testpfade unter `/mnt/user/backups/restore-lab/` und `/mnt/user/backups/restore-reports/` sind freigegeben
+
+## Bestaetigter Host-Stand
+
+- produktive Paperless-Daten liegen unter `/mnt/user/appdata/paperless-ngx/data`
+- produktive Medien liegen unter `/mnt/user/documents/paperless`
+- produktiver Exportpfad liegt unter `/mnt/user/documents/paperless/export`
+- produktiver Consume-Pfad liegt unter `/mnt/user/documents/scans_inbox`
+- aktueller Dump `postgresql17-paperless.dump` ist vorhanden
+
+## Bestaetigter Teststand
+
+- echter Mini-Restore am `2026-05-07` erfolgreich gelaufen
+- Datei-Restore und Dump kamen aus dem produktiven Borg-Archiv
+- Testcontainer:
+  - `restoretest-paperless`
+  - `restoretest-paperless-postgres`
+  - `restoretest-paperless-redis`
+- Login-Seite war lokal auf `127.0.0.1:18120` erreichbar
+- Dump-Import in Test-Postgres war erfolgreich
+- Test-Datenbank enthielt `25` Dokumente
+- Report liegt unter `/mnt/user/backups/restore-reports/paperless-2026-05-07.md`
+
+## Platzhalter
+
+- `ARCHIVE_NAME`: Borg-Archiv fuer den Restore-Test
+- `REPORT_DATE`: z. B. `2026-05-07`
+- `BORG_REPO`: Host-Borg-Repo
+- `BORG_PASSPHRASE_FILE`: `/mnt/user/appdata/secrets/borg_repo_passphrase.txt`
+
+## Ablauf
+
+1. Testpfade vorbereiten
+
+```bash
+mkdir -p /mnt/user/backups/restore-lab/paperless/{data,media,export,consume,postgres}
+mkdir -p /mnt/user/backups/restore-reports
+rm -rf /mnt/user/backups/restore-lab/paperless/data/*
+rm -rf /mnt/user/backups/restore-lab/paperless/media/*
+rm -rf /mnt/user/backups/restore-lab/paperless/export/*
+rm -rf /mnt/user/backups/restore-lab/paperless/consume/*
+rm -rf /mnt/user/backups/restore-lab/paperless/postgres/*
+```
+
+2. Paperless-Dateipfade aus Borg in das Restore-Lab extrahieren
+
+```bash
+export BORG_REPO='...'
+export BORG_PASSPHRASE="$(cat /mnt/user/appdata/secrets/borg_repo_passphrase.txt)"
+borg list "$BORG_REPO"
+cd /mnt/user/backups/restore-lab/paperless
+borg extract "$BORG_REPO" "::ARCHIVE_NAME" local/appdata/paperless-ngx/data local/paperless/media local/paperless/export local/paperless/consume
+mv /mnt/user/backups/restore-lab/paperless/local/appdata/paperless-ngx/data /mnt/user/backups/restore-lab/paperless/data
+mv /mnt/user/backups/restore-lab/paperless/local/paperless/media /mnt/user/backups/restore-lab/paperless/media
+mv /mnt/user/backups/restore-lab/paperless/local/paperless/export /mnt/user/backups/restore-lab/paperless/export
+mv /mnt/user/backups/restore-lab/paperless/local/paperless/consume /mnt/user/backups/restore-lab/paperless/consume
+```
+
+3. Test-Postgres und Test-Redis starten
+
+```bash
+docker compose -f /mnt/user/services/homelab/ops/restore-tests/paperless-compose.test.yml up -d restoretest-paperless-postgres restoretest-paperless-redis
+```
+
+4. Dump in Test-Postgres importieren
+
+```bash
+docker exec -i restoretest-paperless-postgres pg_restore -U paperless -d paperless < /mnt/user/backups/borg/dumps/latest/postgresql17-paperless.dump
+```
+
+5. Testinstanz starten
+
+```bash
+docker compose -f /mnt/user/services/homelab/ops/restore-tests/paperless-compose.test.yml up -d restoretest-paperless
+```
+
+6. Smoke-Test
+
+```bash
+curl -I http://127.0.0.1:18120
+docker logs restoretest-paperless --tail 50
+find /mnt/user/backups/restore-lab/paperless/media -type f | head -n 10
+```
+
+Minimal erfolgreich:
+
+- Dump-Import gelingt
+- HTTP-Antwort kommt
+- Dokumentenpfad ist im Restore-Lab befuellt
+
+7. Testcontainer wieder stoppen
+
+```bash
+docker compose -f /mnt/user/services/homelab/ops/restore-tests/paperless-compose.test.yml down
+```
+
+8. Testdaten nach erfolgreichem Lauf bereinigen
+
+```bash
+rm -rf /mnt/user/backups/restore-lab/paperless
+```
+
+## Festgelegte Entscheidungen
+
+- Paperless nutzt fuer Restore-Tests immer isoliertes Test-Postgres und Test-Redis.
+- Testdaten werden nach erfolgreichem Lauf geloescht.
+- `ntfy` wird nicht im ersten echten Lauf eingebunden.
+- Die Borg-Passphrase wird fuer Restore-Tests aus einer Host-Secret-Datei gelesen, nicht aus Borg-UI-Interna.