Paperless-ngx Backup and Restore

Es gibt verschiedene Optionen deine Instanz von Paperless-ngx zu sichern, ich stelle hier meine Variante für TrueNas in Verbindung zu einem AWS Cloud Backup vor.

Der Dokumenten Export ist die wohl bequemste Art: Paperless-ngx Document exporter

Da die TrueNas Applikation bei der Konfiguration kein “external” volume anbietet und stattdessen in das verseckte .ixVolume speichert, müssen wir mit einem sich ändernden Systempfad rumärgern oder andersweitig behelfen und manuell den export festlegen.

Die Ausgangssituation

Lassen wir den Dokumenten Exporter laufen, funktioniert dies zwar nur finden wir nichts in unserem zuvor Konfigurierten Daten Volume.

truenas[~]$ sudo docker exec ix-paperless-ngx-paperless-1 document_exporter ../export -z
100%|██████████| 274/274 [00:01<00:00, 156.70it/s]

truenas[/mnt/ssd-pool/paperless/data]$ ll
total 221910
drwxrwx--- 4 apps         8 Sep  8 16:11 ./
drwxrwx--- 7 root         7 Jan 28  2025 ../
-rwxrwx--- 1 apps         2 Jan 28  2025 .index_version*
-rwxrwx--- 1 apps    524288 Sep  8 16:09 celerybeat-schedule.db*
-rwxrwx--- 1 apps 227149405 Sep  2 16:06 classification_model.pickle*
drwxrwx--- 2 apps         5 Sep  8 00:00 index/
drwxrwx--- 2 apps        28 Sep  7 20:00 log/
-rwxrwx--- 1 apps         0 Apr  1 16:05 migration_lock*

Schauen wir uns den Docker Container via docker insepct an.

truenas[~]$ sudo docker ps
CONTAINER ID   IMAGE
db3dbc446478   paperlessngx/paperless-ngx:2.18.4   

truenas[~]$ sudo docker inspect -f '{{ json .Mounts }}' db3dbc446478 | python -m json.tool
[
    {
        "Type": "bind",
        "Source": "/mnt/ssd-pool/paperless/media",
        "Destination": "/usr/src/paperless/media",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    },
    {
        "Type": "bind",
        "Source": "/mnt/ssd-pool/paperless/trash",
        "Destination": "/usr/src/paperless/trash",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    },
    {
        "Type": "bind",
        "Source": "/mnt/ssd-pool/paperless/consume",
        "Destination": "/usr/src/paperless/consume",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    },
    {
        "Type": "bind",
        "Source": "/mnt/ssd-pool/paperless/data",
        "Destination": "/usr/src/paperless/data",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    },
    {
        "Type": "volume",
        "Name": "a4b118b7cd57d68b33834cb65833f7fb413d0964b91216bd4b3b992493ba3ea3",
        "Source": "/mnt/.ix-apps/docker/volumes/a4b118b7cd57d68b33834cb65833f7fb413d0964b91216bd4b3b992493ba3ea3/_data",
        "Destination": "/usr/src/paperless/export",
        "Driver": "local",
        "Mode": "",
        "RW": true,
        "Propagation": ""
    }
]

Da wir den HostPath für das /export Verzeichnis nicht in der App Konfiguration anlegen und als bind-mount einbinden können, wird dies standardmässig über das .ix-apps docker Volume gemanaged. Weiterführend: ix-apps Dataset

Dennoch finden wir unseren Export mithilfe des in docker inspect ermittelte Pfades:

truenas[~]$ sudo docker exec ix-paperless-ngx-paperless-1 document_exporter ../export -z
100%|██████████| 274/274 [00:01<00:00, 156.70it/s]

truenas_admin@truenas[~]$ sudo ls -l /mnt/.ix-apps/docker/volumes/a4b118b7cd57d68b33834cb65833f7fb413d0964b91216bd4b3b992493ba3ea3/_data
total 338299
-rw-r--r-- 1 apps apps 346239727 Oct  6 12:19 export-2025-10-06.zip

Die Alternative

Wir erstellen uns ein ‘export’ Verzeichnis unter einem der als bind-mount gemappten Verzeichnisse auf die der paperlessngx zugreifen kann und passen das paperless export Kommando wie folgt an:

truenas[~]$ sudo mkdir /mnt/ssd-pool/paperless/media/export

truenas[~]$ sudo chown apps:apps /mnt/ssd-pool/paperless/media/export

truenas[~]$ sudo docker exec ix-paperless-ngx-paperless-1 document_exporter ../media/export

truenas[~]$ sudo ls -l /mnt/ssd-pool/paperless/media/export
 ...
-rwxrwx--- 1 apps apps 936712 Sep 2 15:14 '2025-09-02.jpg'
-rwxrwx--- 1 apps apps 6288544 Sep 23 11:56 manifest.json
-rwxrwx--- 1 apps apps 25 Sep 23 11:56 metadata.json

Backup & Restore

Wir legen uns einen Cron Job über die TrueNas UI an und sichern diesen auf einem anderen Volume/Dataset. Das Kommando kann vorab wie folgt getestet werden.

truenas[~]$ sudo tar cfz /mnt/WD16TB/TN-App-Backup/paperless-export-$(date '+%Y-%m-%d').tar.gz /mnt/ssd-pool/paperless/media/export

Weiterführend Cron Jobs: Creating Cron Jobs | TrueNAS Documentation Hub

Das Backup kann dann über den document importer wie folgt importiert werden.

1.) Wir schauen uns den Inhalt des Tar Backups an und entpacken dieses wieder in unserem /export Verzeichnis

tar -tvf /mnt/WD16TB/TN-App-Backup/paperless-export.tar.gz
tar -xvf /mnt/WD16TB/TN-App-Backup/paperless-export.tar.gz -C /mnt/ssd-pool/paperless/media/export

2.) Wir nutzen den Dokumenten Import um das Backup wieder herzustellen

docker exec ix-paperless-test-paperless-1 document_importer ../media/export

Weiterführend: Documentation Import – Paperless-ngx