diff --git a/.claude/docs/technical/PROD_DEPLOYMENTS.md b/.claude/docs/technical/PROD_DEPLOYMENTS.md new file mode 100644 index 0000000..f6d78a1 --- /dev/null +++ b/.claude/docs/technical/PROD_DEPLOYMENTS.md @@ -0,0 +1,86 @@ +# Produktions-Deployments (Raspberry Pi + llm-node) + +Stand: 2026-10-29 + +Zwei unabhängige Prod-Deployments laufen parallel. Beide starten bei jedem Push auf `main`, jeweils als eigener Workflow-Lauf auf eigenem Runner. Ein Fehler im einen blockiert das andere nicht. + +Backup, Recovery und Erstbefüllung der llm-node-DB: `RECOVERY_CONTRACT.md`. + +| | Raspberry Pi (alt) | llm-node (neu) | +|---|---|---| +| Workflow | `.gitea/workflows/deploy-prod.yml` | `.gitea/workflows/deploy-prod-llm-node.yml` | +| Workflow-Name | `Deploy Production` | `Deploy Production llm-node` | +| Host | 192.168.2.49, `raspberrypi5`, aarch64 | 192.168.2.144, `llm-node`, x86_64 | +| Runner | `Raspi5-Paperless`, Label `ubuntu-latest` (Host-Modus) | `llm-node-runner`, Label `linux_host` (Host-Modus) | +| Deploy-Verzeichnis | `/home/lars/docker/shinkan` | `/home/llmadmin/docker/shinkan-prod` | +| Compose | `docker-compose.yml`, Projekt `shinkan` (Verzeichnisname) | `docker-compose.yml` + `docker-compose.llm-node.yml`, Projekt `shinkan-prod` | +| Konfiguration | `/home/lars/docker/shinkan/.env` | `/etc/shinkan/prod.env` (Workflow-Variable `ENV_FILE`) | +| Datenbank | Volume `shinkan_shinkan-db-data` auf dem Pi | Volume `shinkan-prod_shinkan-db-data` auf llm-node | +| Medien (Host) | `SHINKAN_MEDIA_HOST` laut Pi-`.env` | `/srv/shinkan/prod/media` (NFSv4 von `192.168.2.63:/volume1/shinkan-media/prod`) | +| Medien (Container) | `/app/media` | `/app/media` | +| Medienbereinigung | `retention-cron` läuft immer mit | aus; nur mit `MEDIA_RETENTION: enabled` | +| Ports | 3003, 127.0.0.1:8003, 127.0.0.1:5434 | 3003, 127.0.0.1:8003, 127.0.0.1:5434 | +| Manuell auslösen | nur per Push auf `main` | Push auf `main` oder Gitea „Run workflow“ (`workflow_dispatch`) | + +Die Runner-Labels sind am 2026-10-29 aus den `.runner`-Dateien beider Hosts abgelesen worden (act_runner v0.2.11). Jeder Workflow prüft im ersten Schritt Hostname und Architektur und bricht auf einem fremden Runner ab. Wer Labels an einem Runner ändert, muss beide Workflows mitprüfen; `ubuntu-latest` darf nicht auf llm-node, `linux_host` nicht auf dem Pi registriert werden. + +Das llm-node-Deployment braucht vom Pi nichts: Code kommt aus dem Gitea auf llm-node selbst, DB und Konfiguration liegen lokal, Medien direkt auf dem NAS. + +## Server-Voraussetzungen auf llm-node + +Außerhalb des Repos eingerichtet und nicht Teil des Workflows: + +- `/etc/shinkan/prod.env`, lesbar für `llmadmin` (Runner-User), Pflicht: `DB_PASSWORD`. `SHINKAN_MEDIA_HOST` und `MEDIA_ROOT` sind optional; wenn gesetzt, müssen sie `/srv/shinkan/prod/media` bzw. `/app/media` sein. `COMPOSE_PROFILES` darf dort nicht stehen. +- NFS-Mount `/srv/shinkan/prod/media`, dauerhaft und beim Boot abgesichert. Erreichbarkeit und Monitoring des NAS liegen beim Server, nicht im Deployment. +- `/home/llmadmin/docker/shinkan-prod`; das Git-Checkout legt der Workflow beim ersten Lauf selbst an. + +## docker-compose.llm-node.yml + +Override nur für llm-node; Pi und Dev nutzen ihn nicht. Alle Compose-Aufrufe im Workflow (build, up, rm, ps, logs) laufen als + +```bash +docker compose -p shinkan-prod -f docker-compose.yml -f docker-compose.llm-node.yml --env-file /etc/shinkan/prod.env ... +``` + +- Ersetzt den Medien-Mount von `backend` und `retention-cron` durch einen Bind-Mount `/srv/shinkan/prod/media` → `/app/media` mit `create_host_path: false`. Ist der Mount nicht da, startet der Container nicht, statt Medien auf die lokale Platte zu schreiben. +- Hängt `retention-cron` an das Profil `media-retention`. Ohne Profil wird der Dienst weder gebaut noch gestartet. + +## Ablauf je Lauf (llm-node) + +1. Runner-Guard (`llm-node`/`x86_64`) +2. `ENV_FILE` prüfen: lesbar, `DB_PASSWORD` gesetzt, kein `COMPOSE_PROFILES`, Medienwerte passend. Es werden keine Werte ausgegeben. +3. `git fetch origin main` + `git reset --hard origin/main` im Deploy-Verzeichnis +4. `build --no-cache` und `up -d --remove-orphans`. Bei `MEDIA_RETENTION: disabled` wird ein noch vorhandener `retention-cron` entfernt. +5. Healthchecks mit Wiederholung (bis ca. 3 min je Prüfung): + - `127.0.0.1:8003/api/version` + - `127.0.0.1:8003/api/health/ready` mit `status=ready`, `database=true`, `schema_complete=true` (HTTP 200 allein reicht nicht) + - `127.0.0.1:3003/api/version` und `127.0.0.1:3003/api/health/ready` (gleiche Bedingung, über Frontend-Nginx) + - `127.0.0.1:3003/` + + Bei Fehler: `compose ps` und Backend-Logs, Lauf rot. + +## Medienbereinigung auf llm-node aktivieren + +Pi und llm-node nutzen denselben Medienbestand, aber getrennte Datenbanken. Eine Bereinigung auf einer Seite kann Dateien löschen, die die andere Datenbank noch referenziert. Deshalb ist `retention-cron` auf llm-node aus. + +Aktivieren erst, wenn nur noch eine Datenbank den Bestand führt (Pi-Bereinigung abgeschaltet bzw. Cutover erfolgt): + +1. In `deploy-prod-llm-node.yml` `MEDIA_RETENTION: disabled` auf `enabled` setzen. +2. Über `develop` → `main` ausrollen. Der Lauf baut und startet `retention-cron` mit Profil `media-retention`. + +Die Bereinigungslogik selbst (`backend/scripts/media_retention_scheduler.py`, täglich 03:00 Europe/Berlin, kein Löschen beim Start) ist dieselbe wie auf dem Pi. + +## Altes Deployment (Pi) abschalten + +Nur den Workflow abschalten, nicht den Pi-Runner: der Runner bedient auch `Deploy Development` und `Test Suite`. + +Eine der beiden Varianten: + +- **Gitea-UI (ohne Commit):** Repository → Actions → `Deploy Production` → „Disable workflow“. Rückgängig über „Enable workflow“. +- **Im Repo:** `.gitea/workflows/deploy-prod.yml` löschen oder den Trigger auf `on: workflow_dispatch` reduzieren und über `develop` → `main` ausrollen. + +Folgen: + +- `deploy-prod-llm-node.yml` ist davon unberührt. +- `test.yml` startet seine Prod-Prüfungen per `workflow_run` nach `Deploy Production`. Diese Prüfungen laufen gegen das Pi-Verzeichnis und entfallen mit dem Abschalten. Sie sind nicht auf llm-node umgestellt. +- Die Pi-Container laufen weiter, einschließlich der Pi-Medienbereinigung, bis sie dort mit `docker compose down` gestoppt werden. diff --git a/.claude/docs/technical/RECOVERY_CONTRACT.md b/.claude/docs/technical/RECOVERY_CONTRACT.md new file mode 100644 index 0000000..838841e --- /dev/null +++ b/.claude/docs/technical/RECOVERY_CONTRACT.md @@ -0,0 +1,200 @@ +# Shinkan Backup & Recovery – Schnittstelle zum Backup-Orchestrator + +Stand: 2026-10-29 · Status: **Entwurf zur Abstimmung, nichts umgesetzt** + +Dieses Dokument legt fest, wie der Backup-Orchestrator (`pi-backup-orchestrator`, eigenes Projekt) und Shinkan bei Backup, Wiederherstellung und Restore-Test zusammenarbeiten. Es richtet sich an den Orchestrator-Agenten und an die Umsetzung der Shinkan-Skripte. + +Grundsatz: **Der Orchestrator weiß, wann und wohin gesichert wird. Shinkan weiß, wie die eigene Datenbank sicher eingespielt und geprüft wird.** Der Orchestrator ruft Shinkan-Skripte auf und wertet Exit-Code und JSON aus. Shinkan-Interna (Migrationen, Sessions, Medienpfade, Healthchecks) stehen nicht im Orchestrator. + +Verwandt: `PROD_DEPLOYMENTS.md` (Deployments Pi + llm-node), `MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` (Medien-Lifecycle). + +--- + +## 1. Ist-Stand (geprüft am 2026-10-29, nur lesend) + +| Punkt | Stand | +|---|---| +| Orchestrator | `pi-backup-orchestrator` v0.3 auf dem Pi, Timer `backup-orchestrator-daily` täglich 05:30, Job `shinkan-prod-db` (Phase 10, kritisch), danach `nas-data` (Phase 20) | +| Dump | `pg_dump` im Container `shinkan-db-prod`, **Plain SQL**, PostgreSQL 16.12, ca. 1,2 MB, 94 Tabellen | +| Ablage | `/media/lars/paperless/db-backup/shinkan-prod.sql` auf der **lokalen NVMe** des Pi, fester Dateiname (bis 2026-10-28 mit Zeitstempel); auf das NAS über `nas-data` | +| Migrationen | Tabelle `schema_migrations(id, migration, executed_at)`; `migration` = Dateiname ohne `.sql`, z. B. `096_login_lockout_and_totp`. Maßgeblich ist `backend/run_migrations.py` (läuft beim Backend-Start). Die Variante in `db_init.py` (Spalte `filename`) wird beim Start nicht genutzt. | +| Medien | Gemeinsamer Bestand auf dem NAS (`192.168.2.63:/volume1/shinkan-media/prod`), im Container `/app/media`. `media_assets.storage_key` relativ (`library/…`) mit `sha256` und `byte_size`; ältere `exercise_media.file_path` als `/media/` | +| Ziel-Prod | llm-node, Compose-Projekt `shinkan-prod`, `docker-compose.yml` + `docker-compose.llm-node.yml`, Konfiguration `/etc/shinkan/prod.env`, Container `shinkan-db-prod` (Postgres nur `127.0.0.1:5434`) | + +## 2. Begriffe + +- **Backup-Satz:** Dump + Prüfsumme + Backup-Manifest + Medien-Manifest, alle mit demselben Zeitstempel. Nur ein vollständiger Satz gilt als Backup. +- **Ziel (target):** benannte, fest im Skript hinterlegte Umgebung. Kein freies Zusammenbauen von Pfaden über Parameter. + +| target | Host | Zweck | Schreibt in DB | +|---|---|---|---| +| `pi-prod` | raspberrypi5 | Manifest zum bestehenden Pi-Dump | nein (nur lesend) | +| `llm-prod` | llm-node | Manifest, Recovery, Erstbefüllung | ja, nur `restore` | +| `llm-restoretest` | llm-node | Restore-Test, wird danach entfernt | ja, nur eigene Wegwerf-DB | + +Jedes Skript prüft wie die Workflows Hostname und Architektur und bricht auf einem fremden Host ab. Restore auf `pi-prod` gibt es nicht. + +## 3. Schnittstelle + +Alle Skripte liegen im Shinkan-Repo unter `scripts/ops/` und laufen auf dem Host der Zielumgebung, aus dem jeweiligen Deploy-Checkout. Die Code-Version, gegen die geprüft wird, ist damit immer die dort deployte. + +Gemeinsam für alle Befehle: + +- Ergebnis als JSON in die Datei `--result ` (Orchestrator legt den Pfad fest, z. B. im Run-Log-Verzeichnis). Auf stdout nur menschenlesbares Log. +- Keine Secrets, keine Dump-Inhalte, keine personenbezogenen Daten in Log oder JSON. Tabellennamen, Zeilenzahlen, Dateipfade im Medienbestand und Versionsangaben sind erlaubt. +- Exit-Codes: + +| Code | Bedeutung | +|---|---| +| 0 | erfolgreich | +| 1 | Fehler während der Ausführung (Details im JSON) | +| 2 | Aufruf oder Vorbedingung falsch (falscher Host, fehlende Datei, fehlende Bestätigung) | +| 3 | Dump passt nicht zum Code (enthält Migrationen, die der Code nicht kennt) | +| 4 | Prüfsumme stimmt nicht | +| 5 | Wiederherstellung durchgeführt, Prüfung danach fehlgeschlagen (Rollback ausgeführt bzw. im JSON beschrieben) | + +### 3.1 `shinkan-backup-manifest` + +Aufruf direkt nach dem Dump, im selben Orchestrator-Job. + +``` +shinkan-backup-manifest --target pi-prod|llm-prod --dump --out-dir --result +``` + +Schreibt neben den Dump: + +- `.sha256` +- `.manifest.json`: + - `created_at`, `host`, `target` + - `app_version` (aus `/api/version`), `git_commit` (Deploy-Checkout) + - `migrations`: Liste aus `schema_migrations.migration`, `last_migration` + - `dump_format` (`plain` | `custom`), `dump_bytes`, `dump_sha256` + - `row_counts` je Tabelle, nur informativ (eigener Lesezugriff, nicht derselbe Snapshot wie der Dump) + - `media_manifest` (Dateiname + sha256) +- `.media.jsonl`, eine Zeile je Datei im Medienbestand: `path` (relativ zu `/app/media`), `size`, `mtime`. `sha256` nur für neue oder geänderte Dateien (Cache über `path`+`size`+`mtime`), damit der Lauf bei wachsendem Bestand kurz bleibt. + +Der Manifest-Job liest nur; ein Fehler darin macht den Backup-Satz unvollständig, aber nicht den Dump ungültig. Empfehlung: Job unkritisch, Kuma-Meldung eigener Monitor. + +### 3.2 `shinkan-restore` + +``` +shinkan-restore --target llm-prod|llm-restoretest --dump --result + [--confirm @] [--allow-overwrite] [--sessions clear|keep] +``` + +- `--confirm shinkan@llm-node` ist bei `llm-prod` Pflicht. +- `--allow-overwrite` ist Pflicht, wenn die Ziel-DB echte Daten hat (mindestens ein Eintrag in `profiles`). Eine frisch migrierte DB ohne Profile gilt als leer. +- `--sessions`: Default `clear`. `keep` nur bei Recovery desselben Systems nach einem Crash, wenn angemeldete Nutzer angemeldet bleiben sollen. + +Ablauf (verbindlich): + +1. **Vorbedingungen:** Host-Guard, Dump lesbar, `.sha256` vorhanden und passend (sonst Exit 4), Zielkonfiguration vorhanden. +2. **In eine Staging-DB einspielen,** nicht direkt in die Live-DB: `shinkan_restore_` im laufenden Postgres-Container anlegen und den Dump in **einer Transaktion** einspielen, bei Fehler Abbruch ohne Teilstand. + - Plain SQL: `psql -v ON_ERROR_STOP=1 --single-transaction` + - Custom-Format (`PGDMP`-Kopf): `pg_restore --single-transaction --exit-on-error --no-owner --no-acl` +3. **Migrationsabgleich in der Staging-DB:** Jeder Eintrag in `schema_migrations.migration` muss als `backend/migrations/.sql` im deployten Code existieren. Sonst ist der Dump neuer als der Code → Staging-DB löschen, Exit 3. Fehlende Einträge (Dump älter als Code) sind normal; sie werden beim Backend-Start nachgezogen. +4. **Plausibilität in der Staging-DB:** Pflichttabellen wie im Ready-Check vorhanden; `profiles`, `skills` nicht leer. Abweichung der Zeilenzahlen zum Manifest nur als Hinweis im JSON. +5. **Sessions:** bei `clear` `TRUNCATE sessions` in der Staging-DB. +6. **Umschalten:** + - Backend, Frontend und `retention-cron` stoppen (Compose `stop`, Postgres läuft weiter). + - Live-DB umbenennen: `shinkan` → `shinkan_before_`. + - Staging-DB umbenennen: `shinkan_restore_` → `shinkan`. + - Backend und Frontend starten; `retention-cron` nur, wenn es im Deployment aktiviert ist (llm-node: `MEDIA_RETENTION`). +7. **Prüfen:** dieselben Healthchecks wie im Deploy-Workflow, insbesondere `/api/health/ready` mit `status=ready`, `database=true`, `schema_complete=true`. +8. **Bei Fehler in 6–7:** Dienste stoppen, Umbenennung rückgängig machen (`shinkan_before_` → `shinkan`), Dienste starten, erneut prüfen. Exit 5 mit beiden Ergebnissen im JSON. +9. **Aufräumen:** `shinkan_before_` bleibt stehen, bis jemand sie ausdrücklich löscht (eigener Befehl `--drop-previous ` oder manuell). Kein automatisches Löschen. + +Ergebnis-JSON u. a.: `dump_sha256`, `dump_last_migration`, `code_last_migration`, `migrations_applied_on_start`, `sessions`, `previous_db`, `health`, `duration_seconds`. + +### 3.3 `shinkan-restore-test` + +``` +shinkan-restore-test --dump --result [--playwright] [--keep] +``` + +Baut eine Wegwerf-Umgebung auf llm-node, spielt den Dump mit `shinkan-restore --target llm-restoretest` ein, prüft und räumt auf. + +- **Eigenes Compose-Projekt** `shinkan-restoretest` mit **eigener Compose-Datei ohne `container_name`**. Die Basisdatei setzt feste Namen (`shinkan-db-prod` …) und kollidiert sonst mit Prod auf demselben Host. +- **Ports:** Frontend und Backend nur auf `127.0.0.1`, Postgres ohne veröffentlichten Port. Konkrete Ports vor Umsetzung auf llm-node prüfen. +- **Medien nur lesend:** `/srv/shinkan/prod/media:/app/media:ro`. Der Medienbestand ist gemeinsam; ein Test darf dort nichts schreiben oder löschen. +- **Aus:** `retention-cron`, SMTP (Variablen leer), `AUTO_ADMIN_FIRST_USER`, `ADMIN_BOOTSTRAP_EMAILS`, OpenRouter. +- **Prüfungen:** Ready-Check, Plausibilität wie 3.2, Medien-Abgleich (3.4) gegen den aktuellen Bestand. +- **`--playwright`:** lesende Smoke-Tests gegen `PLAYWRIGHT_BASE_URL` der Testumgebung. Tests, die hochladen oder Medien ändern, müssen ausgeschlossen werden (schreibgeschützter Mount). Testzugang über einen eigens im Test angelegten Nutzer, nicht über echte Nutzerkonten. +- **Ende:** `docker compose -p shinkan-restoretest down -v`, außer bei `--keep` (zur Fehlersuche). + +Empfohlener Takt: wöchentlich mit dem jüngsten Backup-Satz, zusätzlich nach Änderungen an Dump-Format oder Migrationsrunner. + +### 3.4 `shinkan-media-diff` + +``` +shinkan-media-diff --target llm-prod|llm-restoretest --result [--manifest .media.jsonl] +``` + +Vergleicht die Medienverweise der (wiederhergestellten) DB mit dem aktuellen Medienbestand. Löscht und ändert nichts. + +Kategorien im Ergebnis: + +| Kategorie | Bedeutung | Folge | +|---|---|---| +| `missing` | in `media_assets` / `exercise_media` referenziert, Datei fehlt | reparieren oder Eintrag bereinigen | +| `mismatch` | Datei vorhanden, `byte_size` oder `sha256` passt nicht | prüfen | +| `added_after_backup` | Datei vorhanden, nicht referenziert, nicht im Medien-Manifest des Backups | Upload nach dem Backup; DB-Eintrag ging mit dem Restore verloren → Kandidat für Nachpflege | +| `orphan` | Datei vorhanden, nicht referenziert, bereits im Manifest | Kandidat zum Aufräumen | + +Solange Pi und llm-node denselben Bestand mit getrennten Datenbanken nutzen, gehören `orphan` und `added_after_backup` teilweise zur anderen Installation. **Keine automatische Bereinigung** auf Basis dieses Berichts. + +Der Bericht enthält immer das Versions-Tripel: App-Version und Commit des Ziels, letzte Migration der DB, Medien-Manifest des Backups. + +## 4. Zuständigkeiten + +| Aufgabe | Orchestrator | Shinkan | +|---|---|---| +| Zeitplan (täglich, später 2-stündlich) | ✓ | | +| Dump erzeugen (`pg_dump` im Container) | ✓ | | +| Manifest erzeugen | ruft auf | `shinkan-backup-manifest` | +| Ablage, Generationen, Kopie auf NAS | ✓ | | +| Meldungen (Kuma, Webhooks) | ✓ | liefert Exit-Code + JSON | +| Restore-Test planen | ✓ | `shinkan-restore-test` | +| Recovery auslösen | manuell über Orchestrator-CLI | `shinkan-restore` | +| Medienabgleich | ruft nach Restore auf | `shinkan-media-diff` | +| Installation auf llm-node | ✓ | | + +## 5. Anforderungen an den Orchestrator + +1. **Generationen auf dem NAS.** Mit festem Dateinamen gibt es lokal nur einen Stand. Auf dem NAS müssen mehrere Backup-Sätze erhalten bleiben. Vorschlag: 2-stündliche Sätze 2 Tage, tägliche 30 Tage, monatliche 12 Monate. Ein Satz wird erst überschrieben bzw. rotiert, wenn der neue vollständig ist (Dump + `.sha256` + Manifest). +2. **Atomar schreiben:** Dump erst in eine temporäre Datei, nach Erfolg umbenennen. Ein abgebrochener Dump darf den letzten guten nicht ersetzen. +3. **Dump-Format:** Plain SQL funktioniert. Empfohlen für die Zukunft: `pg_dump -Fc` (kleiner, Inhaltsverzeichnis mit `pg_restore --list`, gezielte Teil-Restores). `shinkan-restore` erkennt beide Formate. +4. **llm-node:** Eigene Orchestrator-Instanz auf llm-node für `shinkan-prod` (`docker exec shinkan-db-prod pg_dump …`). Postgres ist dort nur lokal erreichbar; Fern-Dumps vom Pi sind nicht vorgesehen. +5. **Bis zum Cutover** laufen beide Sicherungen: Pi für das alte Prod, llm-node für das neue. Ablage getrennt (`shinkan-prod-pi/`, `shinkan-prod-llm/`), damit Sätze nicht verwechselt werden. +6. **Takt für externe Kunden:** Vollständige Dumps alle 2 Stunden sind bei der aktuellen Größe unproblematisch und jeder Satz ist eigenständig einspielbar. Ein „Diff zum ersten Dump des Tages“ ist mit `pg_dump` nicht möglich; ein Textvergleich von SQL-Dumps ist kein verlässliches Backup. Für Datenverlust im Minutenbereich ist der Weg WAL-Archivierung mit Basis-Backup (z. B. pgBackRest oder WAL-G, Point-in-Time-Recovery). Das ändert die Postgres-Konfiguration und ist ein eigenes Vorhaben. + +## 6. Erstbefüllung llm-node (einmalig) + +Nutzt bewusst denselben Weg wie die Recovery; die Erstbefüllung ist damit der erste echte Recovery-Test. + +1. Deploy-Workflow `Deploy Production llm-node` ist mindestens einmal erfolgreich gelaufen (DB frisch migriert, keine Profile). +2. Jüngsten Pi-Backup-Satz (`shinkan-prod.sql` + `.sha256` + Manifest) nach llm-node kopieren, Ablage `/var/lib/shinkan/restore/` (Verzeichnis 700, Dateien 600, Eigentümer `llmadmin`). +3. Optional vorher `shinkan-restore-test` mit diesem Satz. +4. `shinkan-restore --target llm-prod --dump … --confirm shinkan@llm-node --sessions clear` (ohne `--allow-overwrite`, da die DB als leer gilt). +5. `shinkan-media-diff --target llm-prod` und Bericht ansehen. +6. Fachliche Stichprobe (Login, Übungen, Medien). + +Vor Schritt 4 klären: SMTP in `/etc/shinkan/prod.env` für die Testphase aus oder bewusst an (echte Nutzerdaten → echte Mails möglich). + +Für den Cutover wird Schritt 2–6 mit Schreibstopp auf dem Pi wiederholt (Pi-Backend stoppen, Dump, Restore mit `--allow-overwrite`). + +## 7. Sicherheit und Datenschutz + +- Dumps enthalten E-Mail-Adressen, Passwort-Hashes und TOTP-Geheimnisse. Ablage nur mit Rechten 600/640, Transport nur im LAN per SSH, nie ins Repo, nie in Webhooks, Logs oder Kuma-Nachrichten. +- Skripte geben keine Umgebungsvariablen aus und lesen Zugangsdaten nur aus der Zielkonfiguration bzw. dem Container. +- Auf dem Pi-Prod nur lesende Zugriffe (Manifest). Kein Restore auf dem Pi. +- Restore-Test nie mit beschreibbarem Medien-Mount, nie mit aktivem SMTP. + +## 8. Offene Entscheidungen + +1. Dump-Format künftig `-Fc` oder weiter Plain SQL? +2. Aufbewahrung der Generationen (Vorschlag in 5.1) und ob das NAS zusätzlich Snapshots führt. +3. Ports und Takt des Restore-Tests; welche Playwright-Tests als lesender Smoke-Satz gelten. +4. Default `--sessions` bei Crash-Recovery (`clear` sicherer, `keep` bequemer). +5. Zeitpunkt für WAL-Archivierung/PITR (spätestens mit dem ersten externen Kunden mit Zusage zur Verfügbarkeit). +6. Wiederherstellung einzelner Vereine bei mehreren Kunden: mit beiden Verfahren nicht direkt möglich; bei Bedarf eigenes Export/Import-Konzept je Mandant. diff --git a/.gitea/workflows/deploy-prod-llm-node.yml b/.gitea/workflows/deploy-prod-llm-node.yml new file mode 100644 index 0000000..50d4dca --- /dev/null +++ b/.gitea/workflows/deploy-prod-llm-node.yml @@ -0,0 +1,166 @@ +name: Deploy Production llm-node + +# Zweites, unabhängiges Prod-Deployment auf llm-node (192.168.2.144, AMD64). +# Läuft parallel zu "Deploy Production" (Raspberry Pi). Den Namen nicht auf +# "Deploy Production" ändern: test.yml hört per workflow_run exakt auf diesen Namen. +# Runner: llm-node-runner mit einzigem Label linux_host (Host-Modus). +# Der Pi-Runner (Raspi5-Paperless) hat nur ubuntu-latest und nimmt diesen Job nie an. +# Compose: docker-compose.yml + docker-compose.llm-node.yml, Konfiguration aus ENV_FILE. +# Doku: .claude/docs/technical/PROD_DEPLOYMENTS.md + +on: + push: + branches: [main] + workflow_dispatch: + +jobs: + deploy: + runs-on: linux_host + env: + APP_DIR: /home/llmadmin/docker/shinkan-prod + ENV_FILE: /etc/shinkan/prod.env + COMPOSE_PROJECT: shinkan-prod + REPO_URL: http://192.168.2.144:3000/Lars/shinkan-jinkendo.git + MEDIA_HOST: /srv/shinkan/prod/media + # Medienbereinigung (retention-cron): disabled | enabled. + # Pi und llm-node teilen den Medienbestand bei getrennten Datenbanken. + # Nur nach Abschalten der Pi-Bereinigung bzw. dem Cutover auf enabled setzen. + MEDIA_RETENTION: disabled + steps: + - name: Runner prüfen (nur llm-node) + shell: bash + run: | + set -euo pipefail + if [ "$(hostname)" != "llm-node" ] || [ "$(uname -m)" != "x86_64" ]; then + echo "✗ Falscher Runner: $(hostname)/$(uname -m), erwartet llm-node/x86_64. Abbruch." + exit 1 + fi + echo "✓ Runner $(hostname)/$(uname -m)" + + - name: Konfiguration prüfen + shell: bash + run: | + set -euo pipefail + if [ ! -r "$ENV_FILE" ]; then + echo "✗ $ENV_FILE fehlt oder ist nicht lesbar." + exit 1 + fi + env_value() { + grep -E "^$1=" "$ENV_FILE" | tail -1 | cut -d= -f2- | tr -d "\"'" || true + } + if [ -z "$(env_value DB_PASSWORD)" ]; then + echo "✗ DB_PASSWORD ist in $ENV_FILE nicht gesetzt." + exit 1 + fi + # Profile steuert allein MEDIA_RETENTION in diesem Workflow. + if grep -Eq "^COMPOSE_PROFILES=" "$ENV_FILE"; then + echo "✗ COMPOSE_PROFILES in $ENV_FILE entfernen; die Bereinigung schaltet MEDIA_RETENTION im Workflow." + exit 1 + fi + # Override mountet fest $MEDIA_HOST -> /app/media; abweichende Werte ergäben einen zweiten Mount. + media_host="$(env_value SHINKAN_MEDIA_HOST)" + media_root="$(env_value MEDIA_ROOT)" + if [ -n "$media_host" ] && [ "$media_host" != "$MEDIA_HOST" ]; then + echo "✗ SHINKAN_MEDIA_HOST=$media_host, erwartet $MEDIA_HOST." + exit 1 + fi + if [ -n "$media_root" ] && [ "$media_root" != "/app/media" ]; then + echo "✗ MEDIA_ROOT=$media_root, erwartet /app/media." + exit 1 + fi + case "$MEDIA_RETENTION" in + disabled|enabled) ;; + *) echo "✗ MEDIA_RETENTION=$MEDIA_RETENTION, erlaubt: disabled | enabled."; exit 1 ;; + esac + echo "✓ $ENV_FILE geprüft, Medien $MEDIA_HOST -> /app/media, Bereinigung $MEDIA_RETENTION" + + - name: Code aktualisieren + shell: bash + run: | + set -euo pipefail + cd "$APP_DIR" + if [ ! -d .git ]; then + git init -q + git remote add origin "$REPO_URL" + fi + git fetch origin main + git reset --hard origin/main + git log -1 --oneline + + - name: Build und Start + shell: bash + run: | + set -euo pipefail + echo "=== Deploying Shinkan to PRODUCTION (llm-node) ===" + cd "$APP_DIR" + dc() { + docker compose -p "$COMPOSE_PROJECT" -f docker-compose.yml -f docker-compose.llm-node.yml \ + --env-file "$ENV_FILE" "$@" + } + if [ "$MEDIA_RETENTION" = enabled ]; then + dc --profile media-retention build --no-cache + dc --profile media-retention up -d --remove-orphans + else + dc build --no-cache + dc up -d --remove-orphans + # Ein früher gestarteter retention-cron läuft sonst weiter. + dc --profile media-retention rm -s -f retention-cron + fi + + - name: Healthchecks + shell: bash + run: | + set -euo pipefail + cd "$APP_DIR" + dc() { + docker compose -p "$COMPOSE_PROJECT" -f docker-compose.yml -f docker-compose.llm-node.yml \ + --env-file "$ENV_FILE" "$@" + } + wait_for() { + local url="$1" label="$2" i + for i in $(seq 1 60); do + if curl -sf -o /dev/null "$url"; then + echo "✓ $label healthy ($url)" + return 0 + fi + sleep 3 + done + echo "✗ $label nicht erreichbar ($url)" + return 1 + } + # HTTP 200 reicht nicht: status=ready, database=true und schema_complete=true. + wait_ready() { + local url="$1" label="$2" i body="" + for i in $(seq 1 60); do + body="$(curl -sf "$url" || true)" + if [ -n "$body" ] && printf '%s' "$body" \ + | jq -e '.status == "ready" and .database == true and .schema_complete == true' >/dev/null 2>&1; then + echo "✓ $label ready ($url)" + return 0 + fi + sleep 3 + done + echo "✗ $label nicht ready ($url):" + printf '%s' "$body" | jq -c '{status, database, schema_complete}' 2>/dev/null || echo " keine gültige Antwort" + return 1 + } + ok=1 + wait_for http://127.0.0.1:8003/api/version "PROD API (direkt)" || ok=0 + if [ "$ok" = 1 ]; then + wait_ready http://127.0.0.1:8003/api/health/ready "PROD API (direkt)" || ok=0 + fi + if [ "$ok" = 1 ]; then + wait_for http://127.0.0.1:3003/api/version "PROD API über Frontend-Nginx" || ok=0 + fi + if [ "$ok" = 1 ]; then + wait_ready http://127.0.0.1:3003/api/health/ready "PROD API über Frontend-Nginx" || ok=0 + fi + if [ "$ok" = 1 ]; then + wait_for http://127.0.0.1:3003/ "PROD Frontend" || ok=0 + fi + if [ "$ok" != 1 ]; then + dc ps || true + dc logs backend --tail 120 || true + exit 1 + fi + echo "=== Shinkan PROD Deploy (llm-node) complete ===" diff --git a/.gitea/workflows/deploy-prod.yml b/.gitea/workflows/deploy-prod.yml index dda98e6..ff22f9d 100644 --- a/.gitea/workflows/deploy-prod.yml +++ b/.gitea/workflows/deploy-prod.yml @@ -1,5 +1,11 @@ name: Deploy Production +# Prod-Deployment auf dem Raspberry Pi. Parallel dazu: deploy-prod-llm-node.yml. +# Namen nicht ändern: test.yml hört per workflow_run exakt auf "Deploy Production". +# Runner: Raspi5-Paperless mit einzigem Label ubuntu-latest (Host-Modus); der +# llm-node-Runner trägt dieses Label nicht. Der Guard bricht auf jedem anderen Host ab. +# Abschalten: .claude/docs/technical/PROD_DEPLOYMENTS.md + on: push: branches: [main] @@ -8,6 +14,15 @@ jobs: deploy: runs-on: ubuntu-latest steps: + - name: Runner prüfen (nur Raspberry Pi) + run: | + set -e + if [ "$(hostname)" != "raspberrypi5" ] || [ "$(uname -m)" != "aarch64" ]; then + echo "✗ Falscher Runner: $(hostname)/$(uname -m), erwartet raspberrypi5/aarch64. Abbruch." + exit 1 + fi + echo "✓ Runner $(hostname)/$(uname -m)" + - name: Deploy to Production run: | set -e diff --git a/CLAUDE.md b/CLAUDE.md index 03e9f8a..5942ed8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -139,8 +139,14 @@ Git Workflow: develop → Auto-Deploy → dev.shinkan.jinkendo.de (shinkan-dev/, Port 3098/8098) main → Auto-Deploy → shinkan.jinkendo.de (shinkan/, Port 3003/8003) + main → Auto-Deploy → llm-node (192.168.2.144, /home/llmadmin/docker/shinkan-prod) + parallel, eigener Workflow deploy-prod-llm-node.yml + Compose-Override docker-compose.llm-node.yml, Config /etc/shinkan/prod.env + Details + Abschalten des Pi-Prod: .claude/docs/technical/PROD_DEPLOYMENTS.md + Gitea: http://192.168.2.144:3000/Lars/shinkan-jinkendo -Runner: Raspberry Pi (/home/lars/gitea-runner/) +Runner: Raspberry Pi (/home/lars/gitea-runner/, Label ubuntu-latest) + llm-node (act_runner.service, Label linux_host) Manuell: cd /home/lars/docker/shinkan[-dev] diff --git a/backend/version.py b/backend/version.py index 561ac59..97f9f6d 100644 --- a/backend/version.py +++ b/backend/version.py @@ -1,7 +1,7 @@ # Shinkan Jinkendo Version Information -APP_VERSION = "0.8.245" -BUILD_DATE = "2026-10-28" +APP_VERSION = "0.8.246" +BUILD_DATE = "2026-10-29" DB_SCHEMA_VERSION = "20261012096" MODULE_VERSIONS = { @@ -53,6 +53,13 @@ MODULE_VERSIONS = { } CHANGELOG = [ + { + "version": "0.8.246", + "date": "2026-10-29", + "changes": [ + "Zweites Prod-Deployment auf llm-node: eigener Workflow, Konfiguration aus /etc/shinkan/prod.env, Medien über docker-compose.llm-node.yml ohne automatisch angelegte Host-Pfade. Die Medienbereinigung startet dort nur nach ausdrücklicher Freigabe. Der Deploy gilt erst als erfolgreich, wenn /api/health/ready Datenbank und Schema bestätigt.", + ], + }, { "version": "0.8.245", "date": "2026-10-28", diff --git a/docker-compose.llm-node.yml b/docker-compose.llm-node.yml new file mode 100644 index 0000000..1f6ff16 --- /dev/null +++ b/docker-compose.llm-node.yml @@ -0,0 +1,32 @@ +# Ergänzung zu docker-compose.yml für das Prod-Deployment auf llm-node. +# Nur zusammen mit der Basisdatei verwenden: +# docker compose -p shinkan-prod -f docker-compose.yml -f docker-compose.llm-node.yml \ +# --env-file /etc/shinkan/prod.env ... +# Pi und Dev nutzen diese Datei nicht. + +services: + backend: + environment: + MEDIA_ROOT: /app/media + # Ersetzt den Medien-Mount der Basisdatei (gleiches Ziel /app/media). + # Kein create_host_path: fehlt das NFS-Verzeichnis, startet der Container nicht, + # statt auf die lokale Platte zu schreiben. + volumes: + - type: bind + source: /srv/shinkan/prod/media + target: /app/media + bind: + create_host_path: false + + # Pi und llm-node teilen den Medienbestand, haben aber getrennte Datenbanken. + # Die Bereinigung startet hier nur mit Profil media-retention (siehe PROD_DEPLOYMENTS.md). + retention-cron: + profiles: ["media-retention"] + environment: + MEDIA_ROOT: /app/media + volumes: + - type: bind + source: /srv/shinkan/prod/media + target: /app/media + bind: + create_host_path: false