Files
backup-orchestrator/docs/APP_MIGRATION_CONTRACT.md
T

128 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
````