From 36d51d4c33663570fa339a88359e8e3fb4b49806 Mon Sep 17 00:00:00 2001 From: Lars Date: Thu, 29 Oct 2026 15:47:38 +0100 Subject: [PATCH] Deploy production to llm-node alongside the Pi. A separate workflow on the linux_host runner deploys main to llm-node with its own checkout, /etc/shinkan/prod.env and a compose override that mounts the NAS media without creating host paths. Media retention stays off there until it is explicitly enabled, because both installations share the media pool. The deploy only passes when /api/health/ready reports a ready database and complete schema. The Pi workflow keeps its name and label and now aborts on any other host. Also documents both deployments and the recovery contract with the backup orchestrator. version: 0.8.246 (backend) Co-Authored-By: Claude Opus 5.5 --- .claude/docs/technical/PROD_DEPLOYMENTS.md | 86 +++++++++ .claude/docs/technical/RECOVERY_CONTRACT.md | 200 ++++++++++++++++++++ .gitea/workflows/deploy-prod-llm-node.yml | 166 ++++++++++++++++ .gitea/workflows/deploy-prod.yml | 15 ++ CLAUDE.md | 8 +- backend/version.py | 11 +- docker-compose.llm-node.yml | 32 ++++ 7 files changed, 515 insertions(+), 3 deletions(-) create mode 100644 .claude/docs/technical/PROD_DEPLOYMENTS.md create mode 100644 .claude/docs/technical/RECOVERY_CONTRACT.md create mode 100644 .gitea/workflows/deploy-prod-llm-node.yml create mode 100644 docker-compose.llm-node.yml 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