# Raspberry Pi 5 – Backup-Orchestrator v0.3 **Status: Test- und Integrationsversion.** Keine produktiven Backups, Timer, Crontabs oder Datenbanken werden durch Installation, `--check`, `--plan` oder `--status` verändert. Die vorhandenen Backup-Skripte sind **noch nicht vollständig standardisiert**, zusätzliche Datenbank-Jobs fehlen und eine vollständige Systemwiederherstellung ist noch nicht getestet. `--run` bleibt bewusst mehrfach gesperrt. ## 1. Enthaltene Dateien - `orchestrator.py`: phasenbasierter Python-Controller (Python 3.11 / Debian 12, nur Standardbibliothek). - `jobs.csv`: bestehende acht Jobs. **Alle `enabled=false`** und verweisen derzeit auf die alten, vorhandenen Skriptpfade. - `notifications.json.example`: eine zentrale Konfigurationsdatei für ausgehende HTTP-POST-Webhooks und Uptime-Kuma-Push-Monitore; keine echten Secrets. - `tests/test_orchestrator.py`: Tests mit künstlichen Shellskripten und simulierten HTTP-Antworten; niemals produktive Datenbanken oder das NAS. ## 2. Sichere Installation auf raspberrypi5 ZIP auf den Raspberry Pi übertragen und dort entpacken. Im entpackten Verzeichnis: ```bash python3 -m unittest discover -s tests -v sudo cp -a /usr/local/sbin/backup-orchestrator /usr/local/sbin/backup-orchestrator.before-v03 sudo install -m 755 orchestrator.py /usr/local/sbin/backup-orchestrator # Die vorhandene /etc/backup-orchestrator/jobs.csv NICHT überschreiben. # Die Benachrichtigungskonfiguration nur bei erstmaliger Einrichtung kopieren. sudo install -d -m 750 /etc/backup-orchestrator if ! sudo test -e /etc/backup-orchestrator/notifications.json; then sudo install -m 600 notifications.json.example /etc/backup-orchestrator/notifications.json fi sudo backup-orchestrator --check ``` Ohne bereits installierte ältere Version entfällt die Zeile `sudo cp -a ...before-v03`. > **Keine `--run`-Befehle ausführen**, solange die alten Cronjobs und der raspiBackup-Timer aktiv sind und die alten Dump-Skripte noch nicht gehärtet wurden. Den Produktiv-Cutover führen wir später kontrolliert durch. ## 3. Konfiguration der Phasen Die vorhandene Tabelle unter `/etc/backup-orchestrator/jobs.csv` hat **keine Uhrzeiten**: ```csv phase,id,script,critical,timeout_seconds,enabled 10,paperless-db,/home/lars/db-backup.sh,true,600,false 10,tandoor-db,/home/lars/db-Tandoor.sh,true,600,false 20,nas-data,/home/lars/backupPaperlessData.sh,true,10800,false 30,system-image,/usr/local/bin/raspiBackup.sh,true,14400,false ``` Die Beispiele sind ein Ausschnitt; die mitgelieferte Datei enthält acht Jobs. - **Innerhalb derselben Phase** laufen bis zu drei Jobs gleichzeitig (per `--max-parallel N` einstellbar). - **Zwischen Phasen** gilt eine Barriere: Die nächste Phase beginnt erst, wenn die aktuelle vollständig abgeschlossen ist. - Ein **kritischer Fehler** blockiert nachfolgende Phasen; laufende Jobs derselben Phase werden beendet bzw. bis zum Abschluss abgewartet. - Ein **unkritischer Fehler** wird protokolliert und führt zu einem fehlgeschlagenen Gesamtergebnis, blockiert aber die nächste Phase nicht. - Zeitüberschreitung beendet die Skript-Prozessgruppe; Service-Neustart und Datenbankkonsistenz müssen in den jeweiligen Jobs abgesichert sein. Zentrale Zeitsteuerung per *einem* systemd-Timer ist eine spätere Cutover-Aufgabe, **nicht Bestandteil der Installation**. ## 4. Externe Schnittstellen ### A. Ausgehende Webhooks, HTTP POST `/etc/backup-orchestrator/notifications.json` bearbeiten: ```json { "timeout_seconds": 3, "webhooks": ["http://192.168.2.100:5678/webhook/backup-events"], "kuma": { "overall_push_url": "http://192.168.2.63:3010/api/push/GESAMT_MONITOR_TOKEN", "job_push_urls": { "nas-data": "http://192.168.2.63:3010/api/push/NAS_MONITOR_TOKEN", "paperless-db": "http://192.168.2.63:3010/api/push/PAPERLESS_MONITOR_TOKEN" } } } ``` Alle URLs sind Beispiele – vorhandene echte Push-Tokens nur auf dem Pi eintragen. Einträge mit `""` sind deaktiviert. Es gibt **keinen HTTP-Listener und keinen permanent laufenden Webserver**; Webhooks sind *ausgehend*. Die echten URLs können auch komplett aus der Uptime-Kuma-Oberfläche kopiert werden (`...?status=up&msg=OK&ping=`). Diese Beispiel-Query wird beim Laden entfernt und beim Push durch den tatsächlichen Status ersetzt. Diese Datei enthält Zugriffstokens: `sudo chmod 600 /etc/backup-orchestrator/notifications.json`. Sie gehört in eine vertrauliche Konfigurationssicherung, nicht in ein öffentliches Repository. ### B. Ereignisse und Beispiele Alle Ereignisse werden als **JSON je Zeile** in `/var/log/backup-orchestrator//events.jsonl` geschrieben; jede Zeile wird auch an die konfigurierten POST-Webhooks gesendet. - `RUN_STARTED`, `PHASE_STARTED`, `JOB_STARTED` - `JOB_SUCCESS`, `JOB_FAILED`, `JOB_TIMEOUT`, `JOB_ERROR`, `JOB_CANCELLED`, `JOB_BLOCKED` - `PHASE_COMPLETED`, `PHASE_BLOCKED`, `RUN_FINISHED` Beispiel einer Webhook-Nachricht (ohne Geheimnisse): ```json { "event": "JOB_FAILED", "timestamp": "2026-10-29T01:02:00+01:00", "run_id": "20261029-010000-1234", "host": "raspberrypi5", "phase": 10, "job": "shinkan-prod-db", "critical": true, "state": "failed", "exit_code": 1, "duration_seconds": 12.3, "log": "/var/log/backup-orchestrator/20261029-010000-1234/shinkan-prod-db.log" } ``` Webhooks versenden **Ereignismetadaten**, nicht den Inhalt der Backup-Skripte oder SQL-Dumps. ### C. Uptime Kuma - `JOB_SUCCESS` → `status=up` für den konfigurierten Job-Monitor. - `JOB_FAILED`, `JOB_TIMEOUT`, `JOB_ERROR`, `JOB_CANCELLED` und `JOB_BLOCKED` → `status=down`. - `RUN_FINISHED` → `status=up` nur beim Gesamtergebnis `ok`, sonst `down`. - Ausbleibende Backups meldet Kuma über den konfigurierten Push-Heartbeat, z.B. bei einem täglichen Lauf ein zum Zeitplan passender Wert. - Schlägt die Zustellung fehl, schreibt der Controller eine Warnung in `notifications.log`. Der Backup-Exit-Code bleibt unverändert. **Keine doppelten Push-Meldungen erzeugen:** Wenn `nas-data` künftig durch den Orchestrator gemeldet wird, die Push-Funktion im Skript `backupPaperlessData.sh` deaktivieren oder nur einen der beiden Sender verwenden. ### D. Lokaler Status, JSON-Abfrage Während des Laufs wird der aktuelle Stand atomar aktualisiert: ```text /var/log/backup-orchestrator/latest.json /var/log/backup-orchestrator//status.json /var/log/backup-orchestrator//summary.json /var/log/backup-orchestrator//events.jsonl ``` CLI für andere Skripte, Home Assistant oder eine spätere GUI: ```bash sudo backup-orchestrator --status sudo backup-orchestrator --status --json sudo cat /var/log/backup-orchestrator/latest.json ``` Die Statusdateien enthalten keine Push-Tokens oder Zugangsdaten, aber interne Pfade und Jobnamen. Daher nur für vertrauenswürdige lokale Nutzer freigeben. Es gibt derzeit **keine eingehende REST-API**; dies kann später als separater schreibgeschützter Dienst ergänzt werden. ## 5. Sichere Bedienung ```bash sudo backup-orchestrator --check # nur Prüfungen, keine Backups sudo backup-orchestrator --plan # nur aktivierte Jobs anzeigen sudo backup-orchestrator --status --json # letzter Status bzw. no_runs ``` `--run`, `--run --phase 10` und `--run --job paperless-db` sind für einen **späteren**, explizit kontrollierten Produktiv-Cutover vorgesehen. Der Controller verweigert Ausführung, solange keine Jobs aktiviert sind, der NAS-Mount fehlt, aktive alte Zeitpläne gefunden werden oder `BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES` fehlt. Das stellt keine vollständige Sicherheitsfreigabe dar: Skripte und Restore müssen zusätzlich getestet werden. ## 6. Offene Arbeiten für den Produktivbetrieb 1. Vorhandene Datenbank-Dump-Skripte unter `scripts/` konsolidieren und auf atomare Dumps unter festen Dateinamen umstellen; Zugänge sicher verwahren. 2. Weitere Datenbanken (Kairo, Tsumugu, Kanshō, Buying Agent, BookStack, NetBox usw.) und zu sichernde Docker-Volumes/Bind-Mounts aufnehmen. 3. rsync-Skript prüfen: nas-data sendet bei der Umstellung **nicht** gleichzeitig selbst und über Orchestrator Pushs. 4. raspiBackup: zuverlässiger vollständiger Restore, korrekt gestoppte Docker-Dienste, Restart-/Timeout-Verhalten nach Fehler. 5. Alte Cronjobs/Timer **erst beim kontrollierten Cutover** ersetzen und einen einzigen orchestrator-Timer installieren. 6. Vollständigen Testlauf, Restore-Test und erwartete Kuma-Ereignisse prüfen. 7. Zweiten unabhängigen/offsite Backup-Standort erwägen; NAS-Ausfall bleibt sonst Single Point of Failure. **Hinweis zur bisherigen Zeitplanung:** Die Root-Crontab-Einträge sind nach der letzten Nutzerprüfung auskommentiert; die aktive User-Crontab sowie `raspiBackup.timer` werden weiterhin als aktive Konflikte erkannt.