Paperless-NGX sichern — Backup und Restore Anleitung

Paperless-NGX Backup mit Docker — Dokumente sicher auf dem Raspberry Pi

Paperless-NGX läuft, hunderte Dokumente sind gescannt und getaggt — aber was passiert, wenn ein Update schiefgeht oder du auf neue Hardware umziehen willst? Ich zeige dir, wie du ein sauberes, automatisiertes Backup einrichtest und im Ernstfall alles wiederherstellst.

DarkWolfCave.de

Wer Paperless-NGX auf dem Raspberry Pi betreibt, speichert die Daten in der Regel nicht auf der SD-Karte, sondern auf einer NVMe-SSD, einer externen Festplatte oder einer NAS-Freigabe. Damit sind die Dokumente selbst schon auf einem zuverlässigeren Speichermedium — und dein NAS hat vermutlich ein eigenes Backup.

Trotzdem reicht ein reines Datei-Backup nicht aus. Die PostgreSQL-Datenbank läuft in einem Docker-Container, und ein Dateikopie bei laufender DB kann inkonsistent sein. Außerdem speichert Paperless-NGX die Zuordnungen zwischen Dokumenten, Tags und Korrespondenten in der Datenbank — ohne diese Metadaten sind deine PDFs nur eine Sammlung loser Dateien. Und spätestens beim Umzug auf neue Hardware brauchst du einen sauberen Export-Import-Pfad.

In meinem Artikel zur Paperless-NGX Installation mit Docker ging es um das Einrichten. Hier geht es um das Absichern — mit dem eingebauten Document Exporter, einem separaten Datenbank-Dump und einem Cron-Job, der beides automatisch erledigt.

Was genau muss gesichert werden?

Paperless-NGX speichert Daten an mehreren Stellen. Für ein vollständiges Backup musst du alle davon berücksichtigen:

Komponente	Inhalt	Wo gespeichert
Originaldokumente	Hochgeladene PDFs, Bilder, Scans	Volume media → Unterordner documents/originals/
Archiv-PDFs	OCR-verarbeitete Versionen	Volume media → Unterordner documents/archive/
Thumbnails	Vorschaubilder für die Web-GUI	Volume media → Unterordner documents/thumbnails/
PostgreSQL-Datenbank	Tags, Korrespondenten, Dokumenttypen, Benutzer, Zuordnungen	Volume pgdata
Konfiguration	docker-compose.yml, .env-Datei	Auf dem Host im Projektverzeichnis

Wenn du Paperless-NGX wie in meiner Installationsanleitung eingerichtet hast, liegen die Daten als Bind-Mounts auf dem Host. Die genauen Pfade findest du in deiner docker-compose.yml.

Zwei Backup-Strategien im Vergleich

Es gibt zwei Wege, Paperless-NGX zu sichern. Beide haben ihre Berechtigung:

Document Exporter (Paperless-eigenes Tool)

Der Document Exporter ist ein Management-Command von Paperless-NGX. Er exportiert alle Dokumente, Thumbnails und eine manifest.json mit sämtlichen Metadaten. Der passende Gegenpart — der Document Importer — stellt aus diesem Export eine komplette Paperless-Instanz wieder her.

Vorteile:

• Offiziell unterstützt und dokumentiert
• Plattformunabhängig — du kannst den Export auf einem anderen System importieren
• Inkrementelle Exports möglich (nur geänderte Dateien)

Nachteile:

• Bei großen Dokumentenbeständen langsamer als ein Dateibackup
• Restore nur auf einer leeren Installation

Dateibasiertes Backup (Volumes + DB-Dump)

Hier sicherst du die Docker-Volumes direkt vom Host und erstellst einen separaten PostgreSQL-Dump. Das ist schneller, aber an die gleiche Verzeichnisstruktur gebunden.

Vorteile:

• Schnell, auch bei tausenden Dokumenten
• Datenbank-Dump ist kompakt und einzeln wiederherstellbar

Nachteile:

• Nicht portabel — gleiche Verzeichnisstruktur auf dem Zielsystem nötig
• Keine offizielle Validierung durch Paperless-NGX

Meine Empfehlung: Beides kombinieren. Der Document Exporter als primäres Backup, der Datenbank-Dump als schnelle Zusatzsicherung. Das Backup-Script weiter unten macht genau das.

Voraussetzungen

Bevor du loslegst, prüfe diese Punkte:

• Paperless-NGX läuft als Docker-Container auf deinem Raspberry Pi (siehe Installationsanleitung)
• Du hast SSH-Zugriff auf den Pi
• Genügend freier Speicherplatz für den Export — rechne mit dem 1,5- bis 2-fachen deiner Paperless-Daten
• Ein separates Backup-Ziel: NAS-Freigabe, externe Festplatte oder ein zweiter Server

💡 Tipp: Auch wenn deine Paperless-Daten bereits auf einer NVMe-SSD oder einem NAS liegen — der Export und der Datenbank-Dump sollten auf ein anderes Gerät. Dein NAS-Backup sichert zwar die Dateien, aber nicht unbedingt die PostgreSQL-Datenbank in einem konsistenten Zustand.

Backup-Verzeichnis einrichten

Erstelle ein Verzeichnis für deine Backups. In diesem Beispiel nutze ich einen Ordner auf dem Host:

# Backup-Verzeichnis anlegen
mkdir -p ~/paperless-backup/export
mkdir -p ~/paperless-backup/database

Falls du eine externe Festplatte nutzt, mounte sie zuerst und passe den Pfad entsprechend an — z.B. /mnt/backup/paperless/.

Backup mit dem Document Exporter

Der Document Exporter ist das offizielle Backup-Tool von Paperless-NGX. Er erstellt eine vollständige Kopie aller Dokumente und Metadaten.

Manueller Export

Wechsle in dein Paperless-NGX Projektverzeichnis und führe den Exporter aus:

# In das Paperless-Verzeichnis wechseln
cd ~/paperless-ngx

# Document Exporter ausführen
docker compose exec -T webserver document_exporter ../export

Das -T Flag verhindert TTY-Fehler, die bei automatisierter Ausführung (Cron) auftreten würden. Der Exporter schreibt die Daten in das export-Volume, das in deiner docker-compose.yml definiert sein muss. Falls du das Volume noch nicht gemappt hast, ergänze es in deiner Compose-Datei:

services:
  webserver:
    volumes:
      - ./export:/usr/src/paperless/export

Ohne dieses Volume-Mapping landet der Export nur innerhalb des Containers und geht beim Neustart verloren.

Was der Exporter erstellt

Nach dem Export findest du im Zielverzeichnis:

export/
├── manifest.json          # Alle Metadaten (Tags, Korrespondenten, etc.)
├── [Datum] [Korrespondent] [Titel].pdf          # Originaldokumente
├── [Datum] [Korrespondent] [Titel]_archive.pdf   # OCR-Versionen
└── [Datum] [Korrespondent] [Titel]_thumb.webp     # Thumbnails

Die manifest.json ist das Herzstück: Sie enthält alle Zuordnungen zwischen Dokumenten, Tags, Korrespondenten und Dokumenttypen. Ohne diese Datei sind die PDFs nur eine Sammlung loser Dateien.

Nützliche Export-Optionen

Flag	Funktion
-p	Sortiert Dateien in Unterordner: archive/, originals/, thumbnails/, json/
-d	Löscht Dateien aus dem Export-Verzeichnis, die in Paperless nicht mehr existieren
-c	Prüft Checksummen statt Dateiattribute — genauer, aber langsamer
-na	Exportiert keine Archiv-PDFs (spart Platz, wenn du nur Originale brauchst)
-nt	Exportiert keine Thumbnails
-z	Komprimiert den Export als ZIP-Datei (Importer akzeptiert ZIP direkt)
-sm	Erstellt individuelle JSON-Dateien pro Dokument statt einer großen manifest.json
--passphrase	Verschlüsselt sensible Felder (Mail-Passwörter, Tokens) mit AES — beim Import dieselbe Passphrase angeben
--no-progress-bar	Unterdrückt die Fortschrittsanzeige (für Scripts und Cron)

Für ein sauberes, inkrementelles Backup empfehle ich:

docker compose exec -T webserver document_exporter ../export -p -d --no-progress-bar

Das Flag -p sortiert die Dateien in Unterordner, -d räumt gelöschte Dokumente auf, und --no-progress-bar hält die Cron-Logs sauber.

Der Exporter arbeitet inkrementell: Er vergleicht den bestehenden Export mit der Datenbank und aktualisiert nur geänderte Dateien. Lösche das Export-Verzeichnis deshalb nicht manuell zwischen den Durchläufen — sonst muss der nächste Export alle Dokumente komplett neu schreiben.

PostgreSQL-Datenbank separat sichern

Der Document Exporter sichert die Metadaten in der manifest.json. Trotzdem erstelle ich zusätzlich einen separaten Datenbank-Dump. Der Grund: Ein SQL-Dump lässt sich schneller einspielen als ein vollständiger Document Import, und er dient als Fallback, falls mit dem Export etwas nicht stimmt.

Nutze dafür immer pg_dump über den laufenden Container — kopiere niemals die PostgreSQL-Dateien direkt aus dem Volume. Bei einer laufenden Datenbank kann das zu korrupten, unbrauchbaren Backups führen.

# PostgreSQL-Dump erstellen
docker compose exec -T db pg_dump -U paperless paperless > ~/paperless-backup/database/db_$(date +%Y%m%d_%H%M%S).sql

Passe den Benutzernamen (-U paperless) und den Datenbanknamen (paperless) an deine docker-compose.yml an. Die Werte stehen in den Umgebungsvariablen POSTGRES_USER und POSTGRES_DB.

⚠️ Wichtig: Der Datenbank-Dump enthält die Zugangsdaten im Klartext, die du in deiner .env-Datei oder docker-compose.yml definiert hast. Sichere die Dump-Dateien entsprechend ab — Leserechte nur für root.

Alte Dumps aufräumen

Damit sich die Datenbank-Dumps nicht stapeln, lösche regelmäßig ältere Versionen:

# Dumps älter als 30 Tage löschen
find ~/paperless-backup/database/ -name "db_*.sql" -mtime +30 -delete

Automatisches Backup per Cron

Ein Backup, das du manuell anstoßen musst, vergisst du irgendwann. Ein Cron-Job erledigt das zuverlässig jede Nacht.

Backup-Script erstellen

Erstelle ein Script, das Document Export und Datenbank-Dump kombiniert:

#!/bin/bash
# Paperless-NGX Backup Script
# Kombiniert Document Exporter + PostgreSQL Dump + CronWolf Monitoring

# Konfiguration — an deine Pfade anpassen
PAPERLESS_DIR="$HOME/paperless-ngx"
BACKUP_DIR="$HOME/paperless-backup"
DB_BACKUP_DIR="$BACKUP_DIR/database"
LOG_FILE="$BACKUP_DIR/backup.log"
KEEP_DB_DAYS=30

# CronWolf Monitoring (optional — leer lassen wenn nicht genutzt)
# Den Token findest du in deinem CronWolf-Dashboard unter dem jeweiligen Check
CRONWOLF_UUID=""

# Zeitstempel
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Fehlerzaehler — am Ende entscheidet dieser ob success oder fail
ERRORS=0

# Logging-Funktion
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
}

log "=== Backup gestartet ==="

# CronWolf: Start melden (misst die Laufzeit des Backups)
if [ -n "$CRONWOLF_UUID" ]; then
    curl -fsS --retry 3 "https://cronwolf.de/api/v2/ping/$CRONWOLF_UUID/start" > /dev/null 2>&1
fi

# In Paperless-Verzeichnis wechseln
cd "$PAPERLESS_DIR" || { log "FEHLER: Verzeichnis $PAPERLESS_DIR nicht gefunden"; ERRORS=$((ERRORS+1)); }

# 1. Document Exporter ausfuehren
log "Document Exporter laeuft..."
if docker compose exec -T webserver document_exporter ../export -p -d --no-progress-bar >> "$LOG_FILE" 2>&1; then
    log "Document Export erfolgreich"
else
    log "FEHLER: Document Export fehlgeschlagen (Exit Code: $?)"
    ERRORS=$((ERRORS+1))
fi

# 2. PostgreSQL-Dump erstellen
log "Datenbank-Dump laeuft..."
DB_FILE="$DB_BACKUP_DIR/db_${TIMESTAMP}.sql"
if docker compose exec -T db pg_dump -U paperless paperless > "$DB_FILE" 2>> "$LOG_FILE"; then
    # Dump komprimieren
    gzip "$DB_FILE"
    log "Datenbank-Dump erstellt: db_${TIMESTAMP}.sql.gz"
else
    log "FEHLER: Datenbank-Dump fehlgeschlagen"
    ERRORS=$((ERRORS+1))
    rm -f "$DB_FILE"
fi

# 3. docker-compose.yml und .env sichern
cp "$PAPERLESS_DIR/docker-compose.yml" "$BACKUP_DIR/docker-compose.yml.backup" 2>/dev/null
cp "$PAPERLESS_DIR/.env" "$BACKUP_DIR/env.backup" 2>/dev/null
log "Konfigurationsdateien gesichert"

# 4. Alte Datenbank-Dumps aufraeumen
DELETED=$(find "$DB_BACKUP_DIR" -name "db_*.sql.gz" -mtime +$KEEP_DB_DAYS -delete -print | wc -l)
log "Alte Dumps geloescht: $DELETED Dateien (aelter als $KEEP_DB_DAYS Tage)"

# 5. CronWolf benachrichtigen (falls konfiguriert)
if [ -n "$CRONWOLF_UUID" ]; then
    if [ "$ERRORS" -eq 0 ]; then
        # Erfolg: Basis-URL ohne Suffix
        curl -fsS --retry 3 "https://cronwolf.de/api/v2/ping/$CRONWOLF_UUID/" > /dev/null 2>&1
        log "CronWolf: success gemeldet"
    else
        curl -fsS --retry 3 "https://cronwolf.de/api/v2/ping/$CRONWOLF_UUID/fail" > /dev/null 2>&1
        log "CronWolf: fail gemeldet ($ERRORS Fehler)"
    fi
fi

log "=== Backup abgeschlossen (Fehler: $ERRORS) ==="

# Exit-Code setzen — wichtig fuer Cron-Mailbenachrichtigung
exit $ERRORS

Speichere das Script und mache es ausführbar:

# Script speichern
nano ~/paperless-backup/backup.sh

# Ausführbar machen
chmod +x ~/paperless-backup/backup.sh

Script testen

Bevor du den Cron-Job einrichtest, teste das Script einmal manuell:

~/paperless-backup/backup.sh

Prüfe danach das Logfile:

cat ~/paperless-backup/backup.log

Du solltest Einträge wie “Document Export erfolgreich” und “Datenbank-Dump erstellt” sehen. Falls Fehler auftreten, prüfe:

• Stimmt der Pfad in PAPERLESS_DIR?
• Läuft der PostgreSQL-Container? (docker compose ps)
• Hat der Benutzer Docker-Rechte? (Gruppe docker)

Cron-Job einrichten

Öffne die Crontab und füge den Job hinzu:

crontab -e

# Paperless-NGX Backup taeglich um 3:00 Uhr
0 3 * * * /home/DEIN_USER/paperless-backup/backup.sh

Ersetze DEIN_USER durch deinen tatsächlichen Benutzernamen auf dem Pi.

💡 Tipp: 3:00 Uhr nachts ist ein guter Zeitpunkt — da werden in der Regel keine neuen Dokumente gescannt. Die Paperless-NGX Dokumentation empfiehlt, Backups zu erstellen, wenn gerade keine Dokumente verarbeitet werden.

Backup-Job überwachen

Ein Cron-Job, der still fehlschlägt, fällt erst auf, wenn du das Backup brauchst — also im schlimmsten Moment. Das Backup-Script oben zählt deshalb Fehler mit und setzt am Ende einen passenden Exit-Code. Darauf kannst du auf mehreren Wegen aufbauen:

Stufe 1: Logfile prüfen (schon eingebaut)

Das Script schreibt jeden Schritt ins Logfile. Am Ende steht Fehler: 0 oder die Anzahl der fehlgeschlagenen Schritte. Für den Anfang reicht ein gelegentlicher Blick:

tail -5 ~/paperless-backup/backup.log

Stufe 2: E-Mail bei Fehler (Cron-Bordmittel)

Cron kann die Ausgabe eines Jobs automatisch per Mail verschicken. Trage in deiner Crontab eine MAILTO-Adresse ein — dann bekommst du eine E-Mail, sobald das Script Fehlerausgaben produziert:

MAILTO="deine@email.de"
0 3 * * * /home/DEIN_USER/paperless-backup/backup.sh

Voraussetzung: Ein lokaler Maildienst wie msmtp oder ssmtp muss auf dem Pi eingerichtet sein.

Stufe 3: Cron-Monitoring mit CronWolf

Noch zuverlässiger: Das Script meldet am Ende aktiv success oder fail an einen Monitoring-Dienst. CronWolf ist mein eigener, DSGVO-konformer Cron-Monitoring-Service — gehostet in Deutschland, ohne Tracking. Du erstellst dort einen Check, der einen Ping in einem bestimmten Intervall erwartet. Bleibt der Ping aus — z.B. weil der Pi offline ist oder der Cron-Daemon nicht läuft — bekommst du eine Benachrichtigung per E-Mail, Slack, Discord oder Webhook. Das ist der entscheidende Vorteil gegenüber MAILTO: CronWolf erkennt auch, wenn ein Job gar nicht erst startet.

So richtest du es ein:

1. Registriere dich kostenlos auf cronwolf.de
2. Erstelle einen neuen Check mit Typ Cron und trage den Cron-Ausdruck ein, der zu deinem Crontab passt — z.B. 0 3 * * * für täglich um 3:00 Uhr. CronWolf erwartet den Ping dann genau zu dieser Zeit. Die Grace Period (z.B. 30 Minuten) gibt dem Backup-Script etwas Spielraum, falls es mal länger braucht.
3. Kopiere die UUID aus den Ping-URLs im Dashboard
4. Trage die UUID im Backup-Script unter CRONWOLF_UUID ein

CronWolf stellt dir drei Ping-Endpunkte bereit:

URL	Bedeutung
https://cronwolf.de/api/v2/ping/UUID/	Erfolg (Success)
https://cronwolf.de/api/v2/ping/UUID/start	Job gestartet (misst Laufzeit)
https://cronwolf.de/api/v2/ping/UUID/fail	Job fehlgeschlagen

Das Backup-Script nutzt alle drei: /start am Anfang, dann je nach Ergebnis die Basis-URL (Erfolg) oder /fail. So siehst du im Dashboard nicht nur ob das Backup lief, sondern auch wie lange es gedauert hat. Mehr Details zur Einrichtung findest du im Artikel CronWolf — Cron-Job Monitoring einfach erklärt.

Restore — Backup wiederherstellen

Ein Backup ist nur so gut wie der getestete Restore. Hier sind die Schritte, um aus einem Export eine funktionierende Paperless-NGX Instanz wiederherzustellen.

Voraussetzung: Leere Installation

Der Document Importer funktioniert nur mit einer komplett leeren Paperless-NGX Installation — leere Datenbank und leere Verzeichnisse. Auf einem neuen Pi oder in einer frischen Docker-Umgebung ist das gegeben.

Schritt 1: Frische Paperless-NGX Instanz starten

Stelle deine gesicherte docker-compose.yml und .env auf dem Zielsystem bereit:

# Backup-Konfiguration kopieren
mkdir -p ~/paperless-ngx
cp docker-compose.yml.backup ~/paperless-ngx/docker-compose.yml
cp env.backup ~/paperless-ngx/.env

# Container starten
cd ~/paperless-ngx
docker compose up -d

Warte, bis alle Container laufen:

docker compose ps

Schritt 2: Document Importer ausführen

Kopiere den Export in das Export-Volume und starte den Import:

# Import starten
docker compose exec -T webserver document_importer ../export

Der Importer liest die manifest.json und stellt alle Dokumente mit ihren Metadaten wieder her — Tags, Korrespondenten, Dokumenttypen, Benutzerberechtigungen. Nur API-Tokens müssen danach neu generiert werden.

Schritt 3: Installation prüfen

Nach dem Import:

1. Öffne die Web-GUI (http://PI-IP:PORT — den Port findest du in deiner docker-compose.yml)
2. Melde dich mit deinen Zugangsdaten an
3. Prüfe ob alle Dokumente vorhanden sind
4. Kontrolliere Tags, Korrespondenten und Dokumenttypen
5. Öffne stichprobenartig einzelne Dokumente — PDFs und OCR-Text

Alternative: Restore aus dem Datenbank-Dump

Falls du nur die Datenbank wiederherstellen musst (z.B. nach einem fehlgeschlagenen Update), kannst du den PostgreSQL-Dump direkt einspielen:

# Dump entpacken falls komprimiert
gunzip db_20260329_030000.sql.gz

# Datenbank wiederherstellen
cat db_20260329_030000.sql | docker compose exec -T db psql -U paperless paperless

# Datenbank-Cache invalidieren (Pflicht nach DB-Restore!)
docker compose exec -T webserver python3 manage.py invalidate_cachalot

Nach einem Datenbank-Restore muss der Befehl invalidate_cachalot ausgeführt werden. Paperless-NGX nutzt einen internen Read-Cache (django-cachalot) — ohne Invalidierung arbeitet die Anwendung mit veralteten Daten. Alternativ: Den Webserver-Container nach dem Restore neu starten (docker compose restart webserver), das leert den Cache ebenfalls.

⚠️ Wichtig: Das überschreibt die aktuelle Datenbank. Im Zweifel: Erst ein neues Backup erstellen, dann den alten Dump einspielen.

Backup auf ein externes Ziel kopieren

Ein Backup auf dem gleichen Raspberry Pi schützt nicht vor Hardware-Ausfall. Kopiere die Daten regelmäßig auf ein anderes Gerät.

Per rsync auf ein NAS

# Backup auf NAS kopieren (ohne --delete!)
rsync -avz ~/paperless-backup/ /mnt/nas/backups/paperless/

Falls dein NAS per Netzwerkfreigabe eingebunden ist, zeigt dir mein Artikel zum Mounten von NAS-Freigaben wie du das einrichtest.

Speichereffizient mit Hardlinks

Wenn du mehrere Backup-Versionen aufbewahren willst, ohne den Speicherplatz zu verdoppeln, nutze rsync mit --link-dest. Dabei werden unveränderte Dateien als Hardlinks angelegt — sie belegen keinen zusätzlichen Platz:

# Tagesbackup mit Hardlinks auf die letzte Version
HEUTE=$(date +%Y-%m-%d)
BACKUP_ZIEL="/mnt/nas/backups/paperless/$HEUTE"
LETZTES="/mnt/nas/backups/paperless/latest"

rsync -avz --link-dest="$LETZTES" ~/paperless-backup/ "$BACKUP_ZIEL"

# Symlink auf das neueste Backup aktualisieren
ln -snf "$BACKUP_ZIEL" "$LETZTES"

So hast du tägliche Snapshots, aber nur geänderte Dateien verbrauchen tatsächlich Speicher.

Per rsync über SSH

# Backup auf einen zweiten Server kopieren
rsync -avz -e "ssh -p 22" ~/paperless-backup/ user@DEIN_SERVER:/backups/paperless/

Du kannst den rsync-Befehl direkt ans Ende deines Backup-Scripts hängen — dann wird das Offsite-Backup gleich miterledigt.

Wenn du das Backup über SSH auf einen entfernten Server kopierst, nutze einen dedizierten SSH-Key ohne Passphrase für den Cron-Job. Der Key sollte auf dem Zielserver nur Schreibrechte auf das Backup-Verzeichnis haben. Mehr zu SSH-Keys findest du im Artikel SSH-Verbindung unter einem Namen speichern.

Restore regelmäßig testen

Ein Backup ohne Restore-Test ist wie ein Fallschirm, den du nie gepackt hast. Solange du nicht weißt, ob der Import funktioniert, hast du kein Backup — du hast eine Kopie und eine Hoffnung.

Manueller Test (alle 3 Monate)

1. Frische Paperless-NGX Instanz in einem separaten Docker-Stack starten
2. Export und Datenbank-Dump einspielen (wie im Restore-Abschnitt oben)
3. Prüfen: Dokumentenanzahl, Tags, Korrespondenten, stichprobenartig PDFs öffnen
4. Ergebnis dokumentieren — wann getestet, welche Version, alles OK?

Automatischer Restore-Test per Script

Noch besser: Ein Script, das den Restore automatisch in einem isolierten Docker-Stack testet. Das lässt sich z.B. monatlich per Cron ausführen:

#!/bin/bash
# Automatischer Paperless-NGX Restore-Test
# Startet eine frische Instanz, importiert das Backup, prueft das Ergebnis

BACKUP_DIR="$HOME/paperless-backup"
TEST_DIR="/tmp/paperless-restore-test"
LOG_FILE="$BACKUP_DIR/restore-test.log"
RESTORE_OK=false

# CronWolf Monitoring fuer den Restore-Test (optional)
# Eigener Check, getrennt vom Backup-Check!
CRONWOLF_RESTORE_UUID=""

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
}

log "=== Restore-Test gestartet ==="

# Altes Testverzeichnis aufraeumen
rm -rf "$TEST_DIR"
mkdir -p "$TEST_DIR"

# docker-compose.yml fuer den Test kopieren
cp "$BACKUP_DIR/docker-compose.yml.backup" "$TEST_DIR/docker-compose.yml"
cp "$BACKUP_DIR/env.backup" "$TEST_DIR/.env"

# Ports aendern damit kein Konflikt mit der laufenden Instanz
# Port 8010 -> 8099 fuer den Test
sed -i 's/8010:8000/8099:8000/g' "$TEST_DIR/docker-compose.yml"

# Test-Stack starten
cd "$TEST_DIR"
docker compose -p paperless-restore-test up -d 2>> "$LOG_FILE"

# Warten bis die Datenbank bereit ist
log "Warte auf Datenbank-Initialisierung..."
sleep 30

# Document Import ausfuehren
log "Starte Document Import..."
if docker compose -p paperless-restore-test exec -T webserver document_importer ../export --no-progress-bar 2>> "$LOG_FILE"; then
    log "Import erfolgreich"
    RESTORE_OK=true
else
    log "FEHLER: Import fehlgeschlagen!"
fi

# Test-Stack wieder herunterfahren und aufraeumen
docker compose -p paperless-restore-test down -v 2>> "$LOG_FILE"
rm -rf "$TEST_DIR"

# CronWolf benachrichtigen (falls konfiguriert)
if [ -n "$CRONWOLF_RESTORE_UUID" ]; then
    if [ "$RESTORE_OK" = true ]; then
        curl -fsS --retry 3 "https://cronwolf.de/api/v2/ping/$CRONWOLF_RESTORE_UUID/" > /dev/null 2>&1
        log "CronWolf: Restore-Test success"
    else
        curl -fsS --retry 3 "https://cronwolf.de/api/v2/ping/$CRONWOLF_RESTORE_UUID/fail" > /dev/null 2>&1
        log "CronWolf: Restore-Test fail"
    fi
fi

log "=== Restore-Test abgeschlossen (OK: $RESTORE_OK) ==="

Das Script startet eine komplett isolierte Paperless-Instanz auf einem anderen Port (8099), importiert den Export und prüft, ob der Import durchläuft. Durch den -p Flag (Projektname) läuft der Test-Stack komplett getrennt von deiner Produktionsinstanz. Nach dem Test wird alles automatisch aufgeräumt.

Wie beim Backup-Script ist auch hier die CronWolf-Überwachung eingebaut — als separater Check mit eigenem Token (CRONWOLF_RESTORE_TOKEN). Damit hast du zwei Checks in deinem Dashboard: Einen für das tägliche Backup, einen für den monatlichen Restore-Test. Falls du CronWolf nicht nutzt, lässt du den Token einfach leer — das Script funktioniert trotzdem und schreibt das Ergebnis ins Logfile.

In den Cron trägst du den Test z.B. am ersten Sonntag im Monat ein:

# Restore-Test am 1. Sonntag im Monat um 5:00 Uhr
0 5 1-7 * 0 /home/DEIN_USER/paperless-backup/restore-test.sh

Prüfe danach gelegentlich das Logfile unter ~/paperless-backup/restore-test.log. Solange dort “Import erfolgreich” steht, weißt du: Dein Backup funktioniert.

Falls du bereits mein Docker Backup Script nutzt, deckt das die Container und Volumes ab. Der Document Exporter ergänzt das um eine Paperless-spezifische Sicherungsebene mit validiertem Import.

Alle Schritte im Überblick

Hier die Kurzfassung als Checkliste:

• Backup-Verzeichnis auf externem Speicher anlegen
• Document Exporter manuell testen
• PostgreSQL-Dump manuell testen
• Backup-Script erstellen und ausführbar machen
• Cron-Job einrichten (täglich, z.B. 3:00 Uhr)
• Offsite-Kopie per rsync einrichten
• Restore auf einer leeren Installation testen
• Vierteljährlich: Restore-Test wiederholen

Wer seine Dokumente mit Paperless-NGX verwaltet, hat viel Arbeit in das Scannen, Taggen und Sortieren gesteckt. Ein automatisiertes Backup mit geprüftem Restore schützt diese Arbeit — und kostet nach der Einrichtung genau null Aufwand.

Weiterführende Artikel

• Paperless-NGX mit Docker installieren — Komplette Installationsanleitung für Paperless-NGX auf dem Raspberry Pi
• Dokumentenscanner für Paperless-NGX im Vergleich — Welcher Scanner passt zu deinem Setup
• Docker Backup für Raspberry Pi — Mein allgemeines Docker-Backup-Script für Container und Volumes
• Raspberry Pi — Docker ohne Probleme installieren — Docker-Setup als Basis
• NAS-Freigaben auf dem Raspberry Pi mounten — Netzwerkfreigabe als Backup-Ziel einrichten