Files
backup-orchestrator/docs/APP_MIGRATION_CONTRACT.md

6.8 KiB
Raw Permalink Blame History

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.

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:

{
  "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:

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.