# 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: `-db-prod` (z. B. `kairo-db-prod`, `tandoor-db-prod`, `bookstack-db-prod`). - App-/Backend-Container: `-backend`, `-frontend` oder sprechende Namen. 2. **Umgebungsvariablen (`.env` / `/etc//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:/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//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 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 `-db-prod` tragen. - Alle DB-Credentials müssen aus einer externen Environment-Datei (`/etc//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:/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. ````