Deploy production to llm-node alongside the Pi.
Deploy Development / deploy (push) Successful in 55s
Test Suite / pytest-backend (push) Successful in 51s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 17s
Test Suite / k6 /health Baseline (push) Successful in 35s
Test Suite / playwright-tests (push) Failing after 7m46s

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 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-10-29 15:47:38 +01:00
1 parent ad7c7ad4e5
commit 36d51d4c33
7 files changed
+515 -3

No files matched your search

@@ -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.
+200
View File
@@ -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/<storage_key>` |
| 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 <pfad>` (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 <datei> --out-dir <verzeichnis> --result <json>
```
Schreibt neben den Dump:
- `<dump>.sha256`
- `<dump>.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)
- `<dump>.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 <datei> --result <json>
[--confirm <db>@<host>] [--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, `<dump>.sha256` vorhanden und passend (sonst Exit 4), Zielkonfiguration vorhanden.
2. **In eine Staging-DB einspielen,** nicht direkt in die Live-DB: `shinkan_restore_<zeitstempel>` 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/<eintrag>.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_<zeitstempel>`.
- Staging-DB umbenennen: `shinkan_restore_<zeitstempel>` → `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_<zeitstempel>` → `shinkan`), Dienste starten, erneut prüfen. Exit 5 mit beiden Ergebnissen im JSON.
9. **Aufräumen:** `shinkan_before_<zeitstempel>` bleibt stehen, bis jemand sie ausdrücklich löscht (eigener Befehl `--drop-previous <name>` 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 <datei> --result <json> [--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 <json> [--manifest <dump>.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.
+166
View File
@@ -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 ==="
+15
View File
@@ -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
+7 -1
View File
@@ -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]
+9 -2
View File
@@ -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",
+32
View File
@@ -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