# 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.