add: backup Paperless NGX to MacOS

2026-08-21 06:51:31 +02:00
1 parent b9a32c92d3
commit f36e243da7
@@ -0,0 +1,96 @@
+# 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:
+
+```text
+~/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
+
+```bash
+./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
+
+```bash
+./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:
+
+```bash
+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.