lokale-scripte/macos/backup-paperless-ngx/README.md

Paperless-ngx-Backup von TrueNAS auf macOS

Das Script ist fuer die auf bfds erkannte Installation vorbereitet:

• TrueNAS 25.04.2.6
• TrueNAS-App paperless-ngx 1.6.37
• Paperless-ngx 3.0.2
• Container ix-paperless-ngx-paperless-1

Es pflegt einen dauerhaften Paperless-Export und synchronisiert ihn ungezippt auf den Mac. Nach dem ersten vollstaendigen Lauf werden nur neue, geaenderte oder geloeschte Dateien abgeglichen. Es entstehen keine Archive und keine taeglichen Vollkopien.

Der lokale Stand befindet sich hier:

~/Backups/paperless-ngx/current/
├── backup-info.txt
├── paperless-export/
│   ├── manifest.json
│   ├── metadata.json
│   ├── archive/
│   ├── originals/
│   └── thumbnails/
└── truenas-app-config/

paperless-export enthaelt Dokumente, Thumbnails, Metadaten, Benutzer und die exportierten Datenbankinhalte. truenas-app-config enthaelt zusaetzlich die TrueNAS-App-Einstellungen und die Konfiguration frueherer App-Versionen.

Testen und ausfuehren

./backup-paperless-ngx.sh --check
./backup-paperless-ngx.sh

--check prueft SSH, Container und Mounts. Ausserdem wird ein kleiner temporaerer document_exporter --data-only-Lauf ausgefuehrt und dessen Manifest kontrolliert. Der Testexport wird sofort wieder entfernt.

Alle Werte lassen sich ueber ~/.config/paperless-backup/config aendern; siehe config.example. Voraussetzung ist, dass ssh -o BatchMode=yes bfds true ohne Passwortdialog funktioniert.

Taeglich um 03:00 Uhr ausfuehren

./install-launchagent.sh

Der Installer kopiert das Script nach ~/Library/Application Support/PaperlessBackup, legt bei Bedarf die Konfiguration an und registriert einen LaunchAgent. Ein manueller Lauf des installierten Jobs ist mit folgendem Befehl moeglich:

launchctl kickstart -k gui/$(id -u)/de.rob.paperless-ngx-backup

Logs stehen in ~/Library/Logs/paperless-ngx-backup.log sowie in den beiden paperless-ngx-launchd.*.log-Dateien.

Wiederherstellung

1. Eine frische Paperless-Instanz mit derselben Paperless-Version wie in backup-info.txt bereitstellen.
2. Den Inhalt von current/paperless-export in das Export-Volume der neuen Instanz kopieren und dort document_importer ausfuehren.
3. current/truenas-app-config dient als Referenz fuer Ports, Storage, Umgebungswerte und Secrets. Diese Dateien nicht blind in eine laufende TrueNAS-App zurueckkopieren.

Der Paperless-Exporter sichert keine API-Tokens; sie muessen nach einem Import neu erzeugt werden.

Verhalten und Sicherheit

Das ist ein Spiegel des aktuellen Paperless-Stands. Wird ein Dokument in Paperless geloescht, wird es beim naechsten erfolgreichen Lauf auch aus diesem Export entfernt. Fuer historische Staende sollte der Ordner zusaetzlich durch Time Machine oder ein anderes versionierendes Backup gesichert werden.

Der Export enthaelt alle Dokumente und moegliche Klartext-Secrets aus der TrueNAS-App-Konfiguration. Das uebergeordnete Zielverzeichnis ist nur fuer den aktuellen macOS-Benutzer zugaenglich. FileVault sollte aktiviert sein.

Auf dem TrueNAS-Apps-Pool bleibt ebenfalls ein ungezipptes Exportverzeichnis macos-backup-current bestehen. Es wird von Paperless bei jedem Lauf inkrementell aktualisiert.

Bereits mit einer aelteren Scriptversion erzeugte .tar.gz-Archive werden nicht automatisch geloescht. Sie koennen nach erfolgreicher Kontrolle des neuen current-Ordners manuell entfernt werden.