feat: add universal-db-restore, app migration contract, targets for kairo/tandoor/bookstack, and uptime kuma guide

This commit is contained in:
Lars committed 2026-10-29 18:32:17 +01:00
1 parent a17afb4b13
commit feb469d47b
10 files changed
+1079 -12

No files matched your search

+127
View File
@@ -0,0 +1,127 @@
# App Migration Contract & Entwickler-Leitfaden für Coding-Agenten
**Gültig für:** Alle Docker-basierten Anwendungen, die von `raspberrypi5` auf `llm-node` umgezogen oder neu an den `backup-orchestrator` angebunden werden (z. B. Kairo, Tandoor Recipes, BookStack, Paperless-ngx, Mitai, Netbox, Tsumugu, Kansho).
---
## 1. Zielsetzung & Architektur
Der `backup-orchestrator` führt automatische Backups (Phase 10 Dumps, Phase 20 NAS-Sync) und risikolose Staging-Restores mit atomarem Swap und Rollback-Sicherheit durch.
Damit eine Anwendung ohne manuelle Eingriffe und ohne Datenverlust migriert und im Regelbetrieb gesichert werden kann, muss jeder Applikations-Entwickler bzw. Coding-Agent die folgenden **5 Kernanforderungen** einhalten.
```mermaid
flowchart TD
A["Anwendung (Docker Compose)"] --> B["1. DB & App Trennung"]
A --> C["2. Health/Readiness Endpoint (/api/health/ready)"]
A --> D["3. Deterministische Migrationen"]
A --> E["4. Stateless Container & NAS-Storage"]
A --> F["5. Invalidate Sessions bei Restore"]
```
---
## 2. Die 5 Kernanforderungen an jede Anwendung
### Anforderung 1: Docker Compose Architektur
1. **Container-Benennung**:
- DB-Container: `<app>-db-prod` (z. B. `kairo-db-prod`, `tandoor-db-prod`, `bookstack-db-prod`).
- App-/Backend-Container: `<app>-backend`, `<app>-frontend` oder sprechende Namen.
2. **Umgebungsvariablen (`.env` / `/etc/<app>/prod.env`)**:
- DB-Credentials dürfen niemals im Compose-File fest eincodiert sein.
- Für PostgreSQL: `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`.
- Für MariaDB: `MARIADB_DATABASE`, `MARIADB_USER`, `MARIADB_PASSWORD`.
3. **Multi-Architektur**:
- Docker-Images müssen Multi-Arch (`linux/amd64` für `llm-node`, `linux/arm64` für Pi) unterstützen oder direkt auf dem Ziel-Host baubar sein.
### Anforderung 2: Readiness / Health Endpoint (`ready_url`)
Jede Anwendung **muss** einen HTTP-Healthcheck bereitstellen (z. B. `http://127.0.0.1:<port>/api/health/ready` oder `.../healthz`):
- **HTTP 200 OK** darf **erst dann** zurückgegeben werden, wenn:
1. Die Datenbankverbindung steht und Abfragen erfolgreich sind.
2. Alle anstehenden Datenbankmigrationen vollständig ausgeführt wurden.
- Wenn die DB noch migriert, blockiert ist oder nicht antwortet, muss der Endpoint HTTP `503 Service Unavailable` zurückgeben.
- Bei JSON-Ausgabe sollte `{"status": "ready"}` oder `{"status": "ok"}` enthalten sein.
### Anforderung 3: Deterministische Datenbank-Migrationen
1. Schema-Änderungen müssen über Migrationstabellen nachvollziehbar sein:
- Django: `django_migrations`
- Laravel / BookStack: `migrations`
- Shinkan / Custom: `schema_migrations`
- Alembic / FastAPI: `alembic_version`
2. **Migrations-Kompatibilität**:
- Vor einem Restore prüft der Orchestrator, ob der Dump Migrationen enthält, die im deployten Code noch fehlen.
- Ein Rollback auf älteren Code bei neuerem DB-Dump wird verweigert (`EXIT_SCHEMA_INCOMPATIBLE`).
### Anforderung 4: Invalidation von Sessions bei Umgebungsumzug
- Bei einer Migration zwischen Servern (z. B. von Pi auf llm-node) dürfen alte Session-Tokens nicht unkontrolliert weiterleben.
- Die Session-Tabelle (z. B. `sessions` oder `django_session`) wird beim Restore geleert (`TRUNCATE TABLE`), sofern `--sessions clear` aktiv ist.
### Anforderung 5: Trennung von Code, Datenbank und Medien (Stateless Container)
- Uploads, Dokumente, PDF-Dateien und Bilder gehören **nicht** in die Datenbank und **nicht** in flüchtige Container-Layer!
- Medienverzeichnisse müssen auf persistenten Mounts (Synology NAS oder lokale Mountpoints wie `/srv/<app>/prod/media`) liegen.
- Der DB-Dump bleibt dadurch klein (< 50 MB), transaktionssicher und blitzschnell wiederherstellbar.
---
## 3. Konfiguration in `targets.json`
Sobald die Anwendung die Kriterien erfüllt, wird sie in `/etc/backup-orchestrator/targets.json` auf `llm-node` eingetragen:
```json
{
"kairo-llm-prod": {
"application": "kairo",
"environment": "production",
"host": "llm-node",
"arch": "x86_64",
"role": "production_target",
"allow_restore": true,
"require_confirm": "kairo@llm-node",
"app_dir": "/home/llmadmin/docker/kairo-prod",
"compose_project": "kairo-prod",
"compose_files": ["docker-compose.yml"],
"env_file": "/etc/kairo/prod.env",
"db_engine": "postgresql",
"db_container": "kairo-db-prod",
"db_name": "kairo",
"db_user": "kairo_user",
"ready_url": "http://127.0.0.1:8001/api/health/ready",
"services_to_stop": ["backend"],
"verify_tables_not_empty": ["django_migrations"],
"truncate_tables": ["django_session"]
}
}
```
---
## 4. Prompt-Vorlage für Coding-Agenten der Ziel-Anwendung
Wenn ein Coding-Agent (z. B. in Roo-Code, Claude Code, Cursor oder Gemini) beauftragt wird, eine Anwendung für den Umzug nach `llm-node` vorzubereiten, verwende folgenden Prompt:
````markdown
Du bereitest die Anwendung <APP_NAME> für den produktiven Betrieb auf unserem neuen Server `llm-node` (Ubuntu 24.04 LTS x86_64) und die Anbindung an den Backup-Orchestrator vor.
Bitte setze folgende Anforderungen um und verändere keine Produktionsdaten auf dem Raspberry Pi:
1. **Docker Compose & Multi-Arch Build:**
- Stelle sicher, dass `docker-compose.yml` (oder ein Override `docker-compose.llm-node.yml`) auf `llm-node` fehlerfrei baut (`linux/amd64`).
- Der Datenbank-Container muss den festen Namen `<APP_NAME>-db-prod` tragen.
- Alle DB-Credentials müssen aus einer externen Environment-Datei (`/etc/<APP_NAME>/prod.env` oder `.env`) geladen werden.
- Nicht-persistente App-Container müssen zustandslos (stateless) sein; persistente Medien/Uploads müssen auf ein Host-Verzeichnis gemountet werden.
2. **Health / Readiness Endpoint:**
- Implementiere oder verifiziere einen HTTP-Endpoint unter `/api/health/ready` (oder `/healthz`).
- Dieser Endpoint muss HTTP 200 liefern, sobald die Datenbank erreichbar ist UND alle Migrationen erfolgreich durchgelaufen sind.
- Solange Migrationen laufen oder die DB nicht bereit ist, muss HTTP 503 zurückgegeben werden.
3. **Migrations-Transparenz:**
- Dokumentiere, in welcher Tabelle die DB-Migrationen erfasst werden (z. B. `schema_migrations`, `django_migrations`, `migrations`).
- Dokumentiere, welche 1–2 Kern-Tabellen nach einem Restore mindestens befüllt sein müssen (z. B. `users`, `profiles`, `posts`).
- Dokumentiere den Namen der Session-Tabelle (z. B. `sessions`, `django_session`), damit alte Tokens beim Umzug bereinigt werden können.
4. **Verifikation auf llm-node:**
- Starte den Stack auf `llm-node` mit einer leeren Datenbank.
- Prüfe mit `curl -s -i http://127.0.0.1:<PORT>/api/health/ready`, dass der Readiness-Check grün meldet.
- Melde zurück: DB-Engine, Containername, DB-Name, DB-User, Health-URL, Session-Tabelle und nicht-leere Kern-Tabellen.
````
+107
View File
@@ -0,0 +1,107 @@
# Uptime Kuma Monitoring & Alerting Guide
Der `backup-orchestrator` verfügt über eine native, out-of-the-box Integration mit **Uptime Kuma**.
Dieses Dokument beschreibt das Monitoring-Konzept, die Schritt-für-Schritt-Einrichtung und die Konfiguration.
---
## 1. Duales Überwachungskonzept
Das Gesamtsystem wird auf zwei komplementären Ebenen überwacht:
```mermaid
flowchart TD
subgraph "1. Passive Push-Überwachung (Backup-Läufe & Restores)"
BO["backup-orchestrator<br/>(systemd daily 05:30)"]
BO -->|"HTTP Push: JOB_SUCCESS (up) / JOB_FAILED (down)"| K1["Uptime Kuma<br/>Push Monitor: Einzeljobs"]
BO -->|"HTTP Push: RUN_FINISHED (overall ok/failed)"| K2["Uptime Kuma<br/>Push Monitor: Täglicher Gesamtlauf"]
end
subgraph "2. Aktive Pull-Überwachung (Live-Dienste auf llm-node)"
K3["Uptime Kuma<br/>HTTP(s) Monitor: 60s Intervall"]
K3 -->|"GET /api/health/ready (Port 8003, 8001...)"| APP1["Shinkan / Kairo Backend"]
K3 -->|"GET / (Port 3003, 8080...)"| APP2["Frontend & Web-UIs"]
end
```
### A. Passive Push-Überwachung (Heartbeat / Dead Man's Snitch)
- **Problem bei Crons/Timern**: Wenn ein Cronjob gar nicht erst startet (Server abgestürzt, Timer deaktiviert, NAS-Mount fehlt), gibt es keine Fehlermeldung.
- **Lösung via Kuma Push**: Der Orchestrator sendet am Ende eines Laufs aktiv ein Signal (`/api/push/<token>?status=up&msg=OK`). Bleibt dieses Signal nach 24 Stunden aus, schlägt Uptime Kuma automatisch Alarm ("Monitor DOWN").
- Einzelne kritische Jobs (z. B. `paperless-db`, `shinkan-prod-db`, `nas-data`) können zudem dedizierte Push-Monitore bedienen.
### B. Aktive Pull-Überwachung (Service Health)
- Uptime Kuma pollt im Regelbetrieb alle 60 Sekunden die Health-Endpoints (`ready_url`) der Container.
- Nach einem Staging-Restore durch den Orchestrator wird so sofort verifiziert, ob die Anwendung auch von außen im Netzwerk wieder uneingeschränkt antwortet.
---
## 2. Einrichtung in Uptime Kuma (Schritt für Schritt)
### Schritt 1: Push-Monitor für den täglichen Backup-Lauf anlegen
1. In Uptime Kuma auf **"Neuen Monitor hinzufügen"** klicken.
2. Folgende Werte eintragen:
- **Monitortyp**: `Push`
- **Name**: `Backup: Täglicher Gesamtlauf (Pi 5)` (oder `Backup: Gesamtlauf llm-node`)
- **Intervall (Heartbeat)**: `86400` Sekunden (24 Stunden)
- **Wiederholungsintervall**: `300` Sekunden (5 Minuten)
- **Max. Wiederholungen**: `2`
3. Speichern. Uptime Kuma zeigt nun eine Push-URL an:
```text
http://<uptime-kuma-host>:3001/api/push/abc123token?status=up&msg=OK&ping=
```
4. Den Basis-Teil der URL kopieren: `http://<uptime-kuma-host>:3001/api/push/abc123token`.
### Schritt 2 (Optional): Push-Monitore für Einzeljobs anlegen
Wiederhole den Vorgang für kritische Einzel-Jobs:
- `Backup: Shinkan DB (Phase 10)`
- `Backup: Paperless DB (Phase 10)`
- `Backup: NAS Data Sync (Phase 20)`
---
## 3. Konfiguration im Backup-Orchestrator
Auf dem jeweiligen Server (`raspberrypi5` oder `llm-node`) wird die Datei `/etc/backup-orchestrator/notifications.json` gepflegt:
```json
{
"timeout_seconds": 3,
"webhooks": [],
"kuma": {
"overall_push_url": "http://192.168.2.xxx:3001/api/push/YOUR_OVERALL_TOKEN",
"job_push_urls": {
"shinkan-prod-db": "http://192.168.2.xxx:3001/api/push/YOUR_SHINKAN_TOKEN",
"paperless-db": "http://192.168.2.xxx:3001/api/push/YOUR_PAPERLESS_TOKEN",
"nas-data": "http://192.168.2.xxx:3001/api/push/YOUR_NAS_DATA_TOKEN"
}
}
}
```
> [!IMPORTANT]
> - Dateirechte: Die Datei muss mit `chmod 0600 /etc/backup-orchestrator/notifications.json` geschützt werden.
> - Der Orchestrator akzeptiert sowohl die reine Basis-URL (`.../api/push/<token>`) als auch die von Kuma kopierte Beispiel-URL (`.../api/push/<token>?status=up&msg=OK`); Abfrageparameter werden automatisch bereinigt.
---
## 4. Testen der Uptime Kuma Push-Benachrichtigung
Um die Benachrichtigung zu testen, ohne ein vollständiges Backup auszulösen:
```bash
# Trockenlauf / Status-Check (zeigt an, wie viele Kuma-URLs konfiguriert sind):
backup-orchestrator --check
# Testlauf für einen einzelnen Job:
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run --job shinkan-prod-db
```
In Uptime Kuma wechselt der Monitor sofort auf **"UP"** (grün) und zeigt im Ereignisprotokoll die Job-ID, den Laufzeit-Timestamp und die Run-ID an.
---
## 5. Fehlertoleranz & Logging
- **Entkopplung**: Push-Benachrichtigungen werden asynchron über einen Thread-Pool versendet.
- **Sicherheitsgarantie**: Netzwerk-Timeouts oder Fehler von Uptime Kuma verändern **niemals** den Exit-Code des Backup-Laufs. Ein erfolgreiches Backup bleibt immer `Exit 0`.
- Fehlerhafte Push-Versuche werden in `/var/log/backup-orchestrator/<run_id>/notifications.log` protokolliert.