Paperless-ngx Backup-Script

Export und anschließende Sicherung von Datenbankinhalten, Metadaten, Benutzerprofilen, Einstellungen usw. von Paperless-ngx

Mithilfe des hier vorgestellten Skripts sollen der Export und die anschließende lokale Sicherung von Datenbankinhalten, Metadaten, Benutzerprofilen, Einstellungen usw. von Paperless-ngx erleichtert werden. Hierzu werden Funktionen genutzt, die sowohl Paperless-ngx als auch PostgreSQL selbst anbieten. Mit rsync werden darüber hinaus weitere wichtige Konfigurationsdateien wie die YAML- und die ENV-Datei gesichert. Das eigentliche Dockerverzeichnis von Paperless-ngx (z.B. /volume1/docker/Pakerless-ngx) wird dabei jedoch nicht gesichert, da mit den oben genannten Export-Funktionen und rsync-Aufgaben bereits alle relevanten Daten für eine spätere Wiederherstellung erfasst wurden.

Für eure Fragen, Probleme, Lösungs- und/oder Verbesserungsvorschläge nutzt bitte den nachfolgend verlinkten Thread.

  • Version 1.0-600

    • Tommes
    • May 5, 2026 at 5:35 PM
    • 48 Downloads

    Version 1.0-600 vom 05.05.2026

    • Fälschlicherweise wurde das -T Flag sowohl aus dem [ docker exec ] als auch aus dem [ docker compose exec ] Befehl entfernt, wobei bei letzteren Befehl das -T Flag erhalten bleiben sollte. Fehler wurde korrigiert.

  • Version 1.0-500

    • Tommes
    • May 4, 2026 at 5:22 PM
    • 3 Downloads

    Version 1.0-500 vom 04.05.2026

    • Das im docker-Befehl [ docker exec -T ] bzw. [ docker compose exec -T ] enthaltene -T Flag löste unter gewissen Umständen einen Fehler aus, daher wurde das Flag wieder entfernt.

  • Version 1.0-400

    • Tommes
    • April 18, 2026 at 5:33 PM
    • 34 Downloads

    Version 1.0-400 vom 18.04.2026

    • Das Skript wurde komplett überarbeitet.
    • Alle verbindlichen, benutzerspezifischen Angaben bzw. Variablen müssen daher neu festgelegt werden.
    • Alle optionalen, benutzerspezifische Angaben bzw. Variablen wurden vollständig entfernt.
    • Docker-Container werden primär über ihren Servicenamen identifiziert und angesprochen, alternativ über den Containernamen oder die Container-ID.
    • Welche Docker-Befehle verwendet werden, hängt davon ab, wie ein Docker-Container identifiziert wurde.
      • Bei Angabe des Servicenamens wird [ docker compose exec -T ] verwendet.
      • Bei Angabe des Containernamen bzw. der Container-ID wird [ docker exec -T ] verwendet.
      • Werden sowohl Servicename als auch Containername bzw. Container-ID angegeben, wird der Servicename und damit [ docker compose exec -T ] bevorzugt verwendet.
      • Der Benutzer kann somit den zu verwendenden Docker-Befehl beeinflussen, indem er entweder den Servicenamen oder den Containernamen bzw. die Container-ID angibt.
      • Damit TTY-Fehler in automatisierten, nicht-interaktiven Aufrufen verhindert werden, wurde den Docker-Befehlen das -T Flag hinzugefügt.
    • Dem Paperless-Export-Aufruf wurde das Flag -b hinzugefügt, um alle Dateien aus dem Exportverzeichnis zu löschen, die in Paperless-ngx nicht mehr vorhanden sind.
    • Dem Paperless-Export-Aufruf wurde das Flag -p hinzugefügt, um die exportierten Dateien in die entsprechenden Unterordner /archive, /originals und /thumbnails einzusortieren.
    • Dem Paperless-Export-Aufruf wurde das Flag -z hinzugefügt, um die exportieren Dateien in einer ZIP-Datei nach der Syntax export-YYYY-MM-DD.zip zu archivieren.
    • Das Skript durchsucht das Wurzelverzeichnis des Docker-Projekt-Verzeichnisses von Paperless-ngx nach allen Dateien mit den Endungen .yaml und .env und sichert sie.
    • Wird eine Datensicherung mit Versionsständen verwendet, werden im Datensicherungsziel Versionsordner im Format "YYYY-MM-DDTHH-MM-SS" angelegt.
    • Versionsordner werden nach Ablauf einer vom Benutzer festgelegten Zeit in Tagen automatisch aus dem Datensicherungsziel gelöscht.
    • Das Datensicherungsprotokoll wird immer im eigentlichen Wurzelverzeichnis des Datensicherungsziels abgelegt und bei jedem neuen Durchlauf überschrieben.
    • Weitere Stilverbesserungen und Codeoptimierungen vorgenommen.

  • Version 1.0-300

    • Tommes
    • April 6, 2026 at 9:51 AM
    • 13 Downloads

    Version 1.0-300 vom 06.04.2026

    • Im Skript wurde die Ausgabe von Informationen auf dem Bildschirm und im Protokoll umgestellt.
    • Es wird eine Fehlermeldung ausgegeben, wenn die YAML- oder die ENV-Datei nicht gefunden wird.

  • Version 1.0-200

    • Tommes
    • January 2, 2026 at 8:53 PM
    • 87 Downloads

    Version 1.0-200 vom 02.01.2026

    • Im Abschnitt "Verbindliche, benutzerspezifische Angaben" des Skriptes, wurde die Variable version_history hinzugefügt.
    • Im Abschnitt "Optionale, benutzerspezifische Angaben" des Skriptes, wurde die Variable tarfolder hinzugefügt.
    • Nachdem alle Sicherungen durchgeführt wurden, wird bei Bedarf eine gepackte .tgz-Archivdatei, benannt nach dem aktuellen Datum und der Uhrzeit im Unterverzeichnis tarfolder des Datensicherungsziels abgelegt.
    • Ältere Archivdateien bzw. Versionsstände werden aus dem Unterverzeichnis gelöscht, sobald eine angegebene Zeit in Tagen version_history überschritten wurde.

  • Version 1.0-100

    • Tommes
    • December 21, 2025 at 9:48 AM
    • 25 Downloads

    Version 1.0-100 vom 21.12.2025

    • Die Variablen username, groupname, paperless_service und postgresql_service wurden entfernt.
    • Die Variablen für optionale, benutzerspezifische Angaben wurden angepasst.
    • Um im Nachgang die Verzeichnis- und Dateirechte im Datensicherungsziel anzupassen, wurde die Ermittlung von Benutzer und Gruppe automatisiert.
    • Um sicherzustellen, dass die Befehle document_exporter und pg_dump innerhalb des Paperless-ngx-Verzeichnis ausgeführt werden, wurde ein automatischer Verzeichniswechsel implementiert.
    • Die Syntax der Befehle document_exporter und pg_dump wurden angepasst.

  • Version 1.0-000

    • Tommes
    • December 18, 2025 at 7:06 PM
    • 21 Downloads
September 7, 2026 at 9:03 AM

Zwei kleine Stellen, bei denen ich mir nicht sicher bin, ob ich das richtig lese – vielleicht kannst du kurz drüberschauen:

Bei postgresql_db="paperless" steht im Kommentar drüber "Passwort für die PostgreSQL-Datenbank" – ist das so gewollt, oder sollte das eigentlich "Datenbankname" heißen? Wird ja später bei pg_dump -d "${postgresql_db}" als Datenbankname verwendet, deshalb meine Frage.

Und beim ENV-Backup-Block:


Code
if [[ -s "${backup_dir}/${yamlfile##*/}" ]]; then

Sollte das an der Stelle nicht ${envfile} statt ${yamlfile} sein? So wie's dasteht, prüft er ja quasi die YAML-Datei nochmal, nicht die gerade kopierte ENV-Datei.

Kann sein, dass ich hier was übersehe – nur zur Sicherheit nachgefragt, bevor ich's selbst nutze. Hab mir für mich selbst auch mal was Ähnliches gebastelt, poste das aber bewusst nicht extra hier – ein funktionierendes Produkt reicht, ein zweites würde nur unnötige Unsicherheit stiften, welches man jetzt nehmen soll.

Auch gut, wenn ich mich komplett irre, irren ist menschlich, Nobody is perfect ;)
December 20, 2025 at 7:56 AM
Author

Hinweis: Ich habe mich gerade mit Mike0185 ausgetauscht und wir sind beide der gleichen Meinung: Der Bereich „Kommentare” ist eher dafür gedacht, Feedback zu sammeln, und nicht, um Support zu leisten. Daher kopiere ich die bisherige Konversation in den Thread Paperless-ngx Backup-Script ,um zukünftig dort eure Fragen, Probleme, Lösungs- und/oder Verbesserungsvorschläge zu thematisieren.
December 19, 2025 at 10:26 AM

Funktioniert leider nicht. Als Ausgabe kommt lediglich:

---------------------------------------------------------------------------------------------------------
Paperless-ngx Datensicherungsprotokoll vom 19.12.2025 um 10:25:14 Uhr
- Datensicherungsziel: /volume1/docker/backups/paperlessngxbackup
---------------------------------------------------------------------------------------------------------

Die integrierte Exportfunktion von Paperless-ngx wird ausgeführt....
read /volume1/docker: is a directory
root@DXP4800PLUS:/volume1/docker#
:/
December 19, 2025 at 10:55 AM
Author

Welchen Pfad hast du denn für paperless_dir eingesetzt?

Hast du in deinem Paperless Verzeichnis ein Unterverzeichnis mit dem Namen export?
December 19, 2025 at 7:03 PM

Unterverzeichnis export ist vorhanden. Der Pfad für paperless_dir lautet: paperless_dir="/volume1/docker/paperlessngx