homelab-infra/ops/restore-tests/paperless-runbook.md

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

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

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

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

docker exec -i restoretest-paperless-postgres pg_restore -U paperless -d paperless < /mnt/user/backups/borg/dumps/latest/postgresql17-paperless.dump

5. Testinstanz starten

docker compose -f /mnt/user/services/homelab/ops/restore-tests/paperless-compose.test.yml up -d restoretest-paperless

6. Smoke-Test

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

docker compose -f /mnt/user/services/homelab/ops/restore-tests/paperless-compose.test.yml down

8. Testdaten nach erfolgreichem Lauf bereinigen

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.