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/.gitea/workflows/test.yml b/.gitea/workflows/test.yml index 5cf8f19..aee8c47 100644 --- a/.gitea/workflows/test.yml +++ b/.gitea/workflows/test.yml @@ -1,15 +1,16 @@ name: Test Suite -# develop: push/PR → Tests gegen Dev (parallel oder vor Deploy Development). -# main: kein push/PR-Trigger — vermeidet doppelten Dev-Lauf beim Merge develop→main; -# Prod-Tests nur via workflow_run nach erfolgreichem Deploy Production. +# Eigener Workflow, getrennt von Deploy Development. +# push/PR auf develop: diese Datei, Ziel ist das Testsystem. +# workflow_run nur nach Deploy Production. Nicht nach dem Dev-Deploy: +# der Listener auf main nutzt bei fehlendem Namen sonst das Prod-Verzeichnis. on: push: branches: [develop] pull_request: branches: [develop] workflow_run: - workflows: ["Deploy Development", "Deploy Production"] + workflows: ["Deploy Production"] types: [completed] jobs: @@ -25,18 +26,24 @@ jobs: REF_NAME="${{ github.ref_name }}" BASE_REF="${{ github.base_ref }}" RUN_WORKFLOW="${{ github.event.workflow_run.name }}" - APP_DIR="/home/lars/docker/shinkan" - COMPOSE_FILE="docker-compose.yml" + HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}" if [ "$EVENT_NAME" = "workflow_run" ]; then - if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then - APP_DIR="/home/lars/docker/shinkan-dev" - COMPOSE_FILE="docker-compose.dev-env.yml" + if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then + echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)." + echo "Produktion wird nicht angefasst." + exit 1 fi + APP_DIR="/home/lars/docker/shinkan" + COMPOSE_FILE="docker-compose.yml" elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then APP_DIR="/home/lars/docker/shinkan-dev" COMPOSE_FILE="docker-compose.dev-env.yml" + else + echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch." + exit 1 fi + echo "CI-Ziel: $APP_DIR ($COMPOSE_FILE)" cd "$APP_DIR" echo "Warte auf stabilen backend-Container …" @@ -70,16 +77,24 @@ jobs: run: | EVENT_NAME="${{ github.event_name }}" REF_NAME="${{ github.ref_name }}" + BASE_REF="${{ github.base_ref }}" RUN_WORKFLOW="${{ github.event.workflow_run.name }}" - APP_DIR="/home/lars/docker/shinkan" + HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}" if [ "$EVENT_NAME" = "workflow_run" ]; then - if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then - APP_DIR="/home/lars/docker/shinkan-dev" + if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then + echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)." + echo "Produktion wird nicht angefasst." + exit 1 fi - elif [ "$REF_NAME" = "develop" ]; then + APP_DIR="/home/lars/docker/shinkan" + elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then APP_DIR="/home/lars/docker/shinkan-dev" + else + echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch." + exit 1 fi + echo "CI-Ziel: $APP_DIR" python3 -m py_compile "$APP_DIR/backend/main.py" echo "✓ Backend syntax OK" @@ -92,16 +107,24 @@ jobs: run: | EVENT_NAME="${{ github.event_name }}" REF_NAME="${{ github.ref_name }}" + BASE_REF="${{ github.base_ref }}" RUN_WORKFLOW="${{ github.event.workflow_run.name }}" - APP_DIR="/home/lars/docker/shinkan" + HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}" if [ "$EVENT_NAME" = "workflow_run" ]; then - if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then - APP_DIR="/home/lars/docker/shinkan-dev" + if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then + echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)." + echo "Produktion wird nicht angefasst." + exit 1 fi - elif [ "$REF_NAME" = "develop" ]; then + APP_DIR="/home/lars/docker/shinkan" + elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then APP_DIR="/home/lars/docker/shinkan-dev" + else + echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch." + exit 1 fi + echo "CI-Ziel: $APP_DIR" cd "$APP_DIR/frontend" npm install @@ -129,6 +152,9 @@ jobs: echo "mode=prod" >> $GITHUB_OUTPUT echo "base_url=https://shinkan.jinkendo.de" >> $GITHUB_OUTPUT echo "→ k6 gegen Prod-Basis." + elif [ "$EVENT" = "workflow_run" ]; then + echo "workflow_run ist nicht Deploy Production (name=$WF_NAME). Abbruch." + exit 1 else echo "mode=dev" >> $GITHUB_OUTPUT echo "base_url=${DEV_BASE}" >> $GITHUB_OUTPUT @@ -219,6 +245,9 @@ jobs: echo "mode=prod" >> $GITHUB_OUTPUT echo "base_url=https://shinkan.jinkendo.de" >> $GITHUB_OUTPUT echo "→ Prod. Secrets: E2E_PROD_TEST_EMAIL / E2E_PROD_TEST_PASSWORD." + elif [ "$EVENT" = "workflow_run" ]; then + echo "workflow_run ist nicht Deploy Production (name=$WF_NAME). Abbruch." + exit 1 else echo "mode=dev" >> $GITHUB_OUTPUT echo "base_url=${DEV_BASE}" >> $GITHUB_OUTPUT 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/routers/content_reports.py b/backend/routers/content_reports.py index 30c9362..3c6c2e7 100644 --- a/backend/routers/content_reports.py +++ b/backend/routers/content_reports.py @@ -456,12 +456,12 @@ def submit_content_report( - Journaleintrag im Medien-Audit-Log (wenn target_type=media_asset) - E-Mail-Bestaetigung an Melder + Benachrichtigung an Plattform-Admins (best-effort) """ - limiter._check_request_limit(request, _content_report_rate_marker, False) if not body.good_faith_confirmed: raise HTTPException( status_code=400, detail="Die Gutglaubenserklärung (good_faith_confirmed) muss bestätigt werden.", ) + limiter._check_request_limit(request, _content_report_rate_marker, False) priority = "high" if body.report_reason in HIGH_PRIORITY_REASONS else "normal" diff --git a/backend/scripts/media_retention_job.py b/backend/scripts/media_retention_job.py index 2ef70cc..9de197c 100644 --- a/backend/scripts/media_retention_job.py +++ b/backend/scripts/media_retention_job.py @@ -2,12 +2,12 @@ """ Automatische Medien-Retention (Papierkorb Stufe 1→2, Purge wenn fällig). -Lauf z. B. täglich per Cron: +Einzellauf (der tägliche Planer ist media_retention_scheduler.py): cd /path/to/backend && python scripts/media_retention_job.py Umgebung wie Backend (DB_*), optional: MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS (Default 30) - MEDIA_TRASH_HIDDEN_TO_PURGE_DAYS (Default 90) + MEDIA_TRASH_HIDDEN_TO_PURGE_DAYS (Default 30) """ from __future__ import annotations diff --git a/backend/scripts/media_retention_scheduler.py b/backend/scripts/media_retention_scheduler.py new file mode 100644 index 0000000..7ced2b3 --- /dev/null +++ b/backend/scripts/media_retention_scheduler.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +"""Täglicher Start von media_retention_job.py um 03:00 Europe/Berlin. + +Der Prozess löscht beim Start nichts. Ein Lauf sofort nach dem Start nur mit +RETENTION_RUN_ON_START=1. Ein fehlgeschlagener Lauf bleibt im Log +(RETENTION_FAIL); der Prozess bleibt aktiv, damit Docker ihn nicht sofort +erneut startet. +""" +from __future__ import annotations + +import logging +import os +import subprocess +import sys +import time +from datetime import datetime, timedelta +from zoneinfo import ZoneInfo + +LOG = logging.getLogger("retention.scheduler") + +DEFAULT_TZ = "Europe/Berlin" +_RUN_ON_START = "RETENTION_RUN_ON_START" +_TZ_ENV = "RETENTION_TZ" + + +def retention_zone() -> ZoneInfo: + name = os.environ.get(_TZ_ENV, DEFAULT_TZ).strip() or DEFAULT_TZ + return ZoneInfo(name) + + +def next_run_at(now: datetime, *, hour: int = 3) -> datetime: + """Nächste Uhrzeit `hour`:00 in der Zeitzone von `now`. + + `now` muss zeitzonenbewusst sein. Die Zone von `now` ist die Planungszone. + """ + if now.tzinfo is None: + raise ValueError("now muss eine Zeitzone tragen") + zone = now.tzinfo + local = now.astimezone(zone) + day = local.date() + target = datetime(day.year, day.month, day.day, hour, 0, 0, tzinfo=zone) + if target.timestamp() <= local.timestamp(): + day = day + timedelta(days=1) + target = datetime(day.year, day.month, day.day, hour, 0, 0, tzinfo=zone) + return target + + +def seconds_until_next_0300(now: datetime, *, hour: int = 3) -> float: + """Sekunden bis zum nächsten Lauf, als absolute Dauer. + + `target - now` zieht bei gleicher tzinfo die Wanduhr ab und liegt an + Umstellungstagen um eine Stunde daneben. `timestamp()` rechnet in UTC. + """ + target = next_run_at(now, hour=hour) + local = now.astimezone(target.tzinfo) + return target.timestamp() - local.timestamp() + + +def _job_path() -> str: + return os.path.join(os.path.dirname(os.path.abspath(__file__)), "media_retention_job.py") + + +def _run_on_start() -> bool: + return os.environ.get(_RUN_ON_START, "").strip() == "1" + + +def run_job() -> int: + """Startet den Retention-Job. Führt keine Löschung in diesem Prozess aus.""" + LOG.info("Retention-Lauf startet") + completed = subprocess.run([sys.executable, "-u", _job_path()], check=False) + if completed.returncode != 0: + LOG.error("RETENTION_FAIL exit=%s", completed.returncode) + else: + LOG.info("RETENTION_OK") + return int(completed.returncode) + + +def serve( + *, + iterations: int | None = None, + sleep=time.sleep, + clock=None, + run=None, +) -> None: + zone = retention_zone() + if clock is None: + def clock() -> datetime: + return datetime.now(zone) + + execute = run if run is not None else run_job + if _run_on_start(): + LOG.info("Sofortlauf wegen RETENTION_RUN_ON_START=1") + execute() + + completed = 0 + while iterations is None or completed < iterations: + target = next_run_at(clock()) + LOG.info("Nächster Retention-Lauf %s", target.isoformat(timespec="seconds")) + while True: + remaining = target.timestamp() - clock().timestamp() + if remaining <= 1: + break + LOG.info("Warte %.0f Sekunden bis %s", remaining, target.isoformat(timespec="seconds")) + sleep(remaining) + execute() + completed += 1 + + +def main() -> int: + logging.basicConfig( + level=logging.INFO, + format="%(asctime)s %(levelname)s %(message)s", + stream=sys.stdout, + force=True, + ) + serve() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/tests/test_media_retention_scheduler.py b/backend/tests/test_media_retention_scheduler.py new file mode 100644 index 0000000..93ef523 --- /dev/null +++ b/backend/tests/test_media_retention_scheduler.py @@ -0,0 +1,167 @@ +"""Scheduler für den Papierkorb-Job: 03:00 Europe/Berlin, ohne echten Löschlauf.""" +from __future__ import annotations + +import logging +from datetime import datetime, timedelta +from pathlib import Path +from zoneinfo import ZoneInfo + +import pytest + +from scripts.media_retention_scheduler import ( + next_run_at, + run_job, + seconds_until_next_0300, + serve, +) + +BERLIN = ZoneInfo("Europe/Berlin") + + +def _compose_file() -> Path | None: + """Repo-Root lokal. Im Backend-Image liegt nur /app, ohne docker-compose.yml.""" + for parent in Path(__file__).resolve().parents: + candidate = parent / "docker-compose.yml" + if candidate.is_file(): + return candidate + return None + + +def test_winter_afternoon_waits_until_next_morning() -> None: + now = datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN) + assert next_run_at(now).isoformat() == "2026-01-16T03:00:00+01:00" + assert seconds_until_next_0300(now) == 17 * 3600 + + +def test_summer_before_three_is_same_morning() -> None: + now = datetime(2026, 7, 15, 2, 0, tzinfo=BERLIN) + assert next_run_at(now).isoformat() == "2026-07-15T03:00:00+02:00" + assert seconds_until_next_0300(now) == 3600 + + +def test_exactly_0300_waits_until_next_day() -> None: + now = datetime(2026, 1, 15, 3, 0, tzinfo=BERLIN) + assert next_run_at(now).isoformat() == "2026-01-16T03:00:00+01:00" + assert seconds_until_next_0300(now) == 24 * 3600 + + +def test_spring_forward_sleeps_absolute_22_hours() -> None: + now = datetime(2026, 3, 28, 4, 0, tzinfo=BERLIN) + target = next_run_at(now) + assert target.isoformat() == "2026-03-29T03:00:00+02:00" + assert seconds_until_next_0300(now) == 22 * 3600 + assert (target - now).total_seconds() == 23 * 3600 + + +def test_fall_back_sleeps_absolute_24_hours() -> None: + now = datetime(2026, 10, 24, 4, 0, tzinfo=BERLIN) + target = next_run_at(now) + assert target.isoformat() == "2026-10-25T03:00:00+01:00" + assert seconds_until_next_0300(now) == 24 * 3600 + assert (target - now).total_seconds() == 23 * 3600 + + +def test_naive_datetime_is_rejected() -> None: + with pytest.raises(ValueError): + next_run_at(datetime(2026, 1, 15, 10, 0)) + + +def test_serve_sleeps_before_first_run(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("RETENTION_RUN_ON_START", raising=False) + state = {"now": datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN)} + events: list[tuple] = [] + + def clock() -> datetime: + return state["now"] + + def sleep(seconds: float) -> None: + events.append(("sleep", seconds)) + state["now"] = state["now"] + timedelta(seconds=seconds) + + def run() -> None: + events.append(("run",)) + + serve(iterations=1, sleep=sleep, clock=clock, run=run) + assert events == [("sleep", 17 * 3600), ("run",)] + + +def test_serve_can_run_once_on_start(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("RETENTION_RUN_ON_START", "1") + state = {"now": datetime(2026, 7, 15, 2, 0, tzinfo=BERLIN)} + events: list[str] = [] + + def sleep(seconds: float) -> None: + events.append("sleep") + state["now"] = state["now"] + timedelta(seconds=seconds) + + serve( + iterations=1, + sleep=sleep, + clock=lambda: state["now"], + run=lambda: events.append("run"), + ) + assert events == ["run", "sleep", "run"] + + +def test_serve_continues_after_failed_run(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("RETENTION_RUN_ON_START", raising=False) + state = {"now": datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN)} + runs: list[int] = [] + + def sleep(seconds: float) -> None: + state["now"] = state["now"] + timedelta(seconds=seconds) + + def run() -> int: + runs.append(1) + return 1 + + serve(iterations=2, sleep=sleep, clock=lambda: state["now"], run=run) + assert runs == [1, 1] + + +def test_run_job_logs_failure_without_starting_real_job( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + class Done: + returncode = 1 + + monkeypatch.setattr( + "scripts.media_retention_scheduler.subprocess.run", + lambda *args, **kwargs: Done(), + ) + with caplog.at_level(logging.INFO, logger="retention.scheduler"): + assert run_job() == 1 + assert "RETENTION_FAIL exit=1" in caplog.text + + +def test_run_job_logs_success( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + class Done: + returncode = 0 + + seen: list[list[str]] = [] + + def fake_run(cmd, check=False): + seen.append(list(cmd)) + return Done() + + monkeypatch.setattr("scripts.media_retention_scheduler.subprocess.run", fake_run) + with caplog.at_level(logging.INFO, logger="retention.scheduler"): + assert run_job() == 0 + assert seen and seen[0][-1].endswith("media_retention_job.py") + assert "RETENTION_OK" in caplog.text + assert "RETENTION_FAIL" not in caplog.text + + +def test_compose_starts_scheduler_script() -> None: + compose = _compose_file() + if compose is None: + pytest.skip("docker-compose.yml liegt nicht im Backend-Image") + text = compose.read_text(encoding="utf-8") + start = text.index(" retention-cron:") + block = text[start : text.index("\nvolumes:", start)] + assert 'command: ["python", "-u", "scripts/media_retention_scheduler.py"]' in block + assert "python -c" not in block + assert 'PYTHONUNBUFFERED: "1"' in block + assert "RETENTION_RUN_ON_START" not in block diff --git a/backend/tests/test_p13_content_reports.py b/backend/tests/test_p13_content_reports.py index eee82a2..2cf6525 100644 --- a/backend/tests/test_p13_content_reports.py +++ b/backend/tests/test_p13_content_reports.py @@ -73,8 +73,24 @@ def test_submit_requires_good_faith(): good_faith_confirmed=False, ) from routers.content_reports import submit_content_report + from starlette.requests import Request + + request = Request( + { + "type": "http", + "http_version": "1.1", + "method": "POST", + "scheme": "http", + "path": "/api/content-reports", + "raw_path": b"/api/content-reports", + "query_string": b"", + "headers": [], + "client": ("127.0.0.1", 50000), + "server": ("testserver", 80), + } + ) with pytest.raises(HTTPException) as exc: - submit_content_report(body) + submit_content_report(request, body) assert exc.value.status_code == 400 assert "Gutglauben" in exc.value.detail diff --git a/backend/version.py b/backend/version.py index 5a671ec..97f9f6d 100644 --- a/backend/version.py +++ b/backend/version.py @@ -1,7 +1,7 @@ # Shinkan Jinkendo Version Information -APP_VERSION = "0.8.243" -BUILD_DATE = "2026-10-13" +APP_VERSION = "0.8.246" +BUILD_DATE = "2026-10-29" DB_SCHEMA_VERSION = "20261012096" MODULE_VERSIONS = { @@ -49,10 +49,31 @@ MODULE_VERSIONS = { "membership": "1.0.0", "catalogs": "1.5.0", # Updated: Trainer Contexts API (Migration 012) "maturity_models": "1.4.0", # matrix_stack_bundle: vollständiger Katalog+Modelle+Bindings Export/Import - "content_reports": "1.5.2", # POST /content-reports: 10 Meldungen pro Stunde und IP + "content_reports": "1.5.3", # Gutglauben vor dem Stundenlimit; Direktaufruf im Test mit Request } 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", + "changes": [ + "Papierkorb-Retention läuft täglich um 03:00 Uhr Europe/Berlin. Ein fehlgeschlagener Lauf bleibt im Container-Log sichtbar und löscht beim Containerstart nichts.", + ], + }, + { + "version": "0.8.244", + "date": "2026-10-13", + "changes": [ + "Inhaltsmeldungen ohne Gutglaubenserklärung zählen nicht auf das Stundenlimit.", + ], + }, { "version": "0.8.243", "date": "2026-10-13", 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 diff --git a/docker-compose.yml b/docker-compose.yml index 56fabb0..b2f05ba 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -89,20 +89,7 @@ services: context: ./backend dockerfile: Dockerfile container_name: shinkan-retention-cron - command: > - python -c " - import time, subprocess, sys, os, datetime - def next_3am(): - now = datetime.datetime.now() - target = now.replace(hour=3, minute=0, second=0, microsecond=0) - if target <= now: - target += datetime.timedelta(days=1) - return (target - now).total_seconds() - subprocess.run([sys.executable, 'scripts/media_retention_job.py'], check=False) - while True: - time.sleep(next_3am()) - subprocess.run([sys.executable, 'scripts/media_retention_job.py'], check=False) - " + command: ["python", "-u", "scripts/media_retention_scheduler.py"] working_dir: /app environment: DB_HOST: postgres @@ -110,6 +97,7 @@ services: DB_NAME: shinkan DB_USER: shinkan_user DB_PASSWORD: ${DB_PASSWORD} + PYTHONUNBUFFERED: "1" MEDIA_ROOT: "${MEDIA_ROOT:-/app/media}" # Loeschkonzept (Audit P-03b): 30 Tage Soft-Trash, dann 30 Tage Hidden, dann Purge (gesamt 60 Tage). MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS: "${MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS:-30}" diff --git a/scripts/ci/run-deployed-checks.sh b/scripts/ci/run-deployed-checks.sh new file mode 100644 index 0000000..36e1a53 --- /dev/null +++ b/scripts/ci/run-deployed-checks.sh @@ -0,0 +1,116 @@ +#!/bin/sh +# Prüfungen gegen den bereits deployten Stack. Ziel ist Pflicht: dev oder prod. +# Kein Default auf Produktion. +set -eu + +TARGET="${1:-}" +CHECK="${2:-}" + +case "$TARGET" in + dev) + APP_DIR="/home/lars/docker/shinkan-dev" + COMPOSE_FILE="docker-compose.dev-env.yml" + BASE_URL="https://dev.shinkan.jinkendo.de" + HEALTH_TRIES=90 + HEALTH_SLEEP=2 + ;; + prod) + APP_DIR="/home/lars/docker/shinkan" + COMPOSE_FILE="docker-compose.yml" + BASE_URL="https://shinkan.jinkendo.de" + HEALTH_TRIES=60 + HEALTH_SLEEP=5 + ;; + *) + echo "Ziel muss dev oder prod sein, war: '${TARGET}'." >&2 + exit 1 + ;; +esac + +echo "CI-Ziel: $TARGET ($APP_DIR, $BASE_URL), Prüfung: $CHECK" + +wait_health() { + echo "Warte auf $BASE_URL/health …" + i=1 + while [ "$i" -le "$HEALTH_TRIES" ]; do + if curl -sf "$BASE_URL/health" >/dev/null 2>&1; then + echo "Health OK (Versuch $i)" + return 0 + fi + i=$((i + 1)) + sleep "$HEALTH_SLEEP" + done + echo "Timeout: $BASE_URL/health nicht erreichbar" + curl -v "$BASE_URL/health" || true + return 1 +} + +run_pytest() { + cd "$APP_DIR" + echo "Warte auf stabilen backend-Container …" + i=1 + while [ "$i" -le 60 ]; do + if docker compose -f "$COMPOSE_FILE" exec -T backend true 2>/dev/null; then + echo "Backend bereit (Versuch $i)" + break + fi + if [ "$i" -eq 60 ]; then + echo "Timeout: backend-Container nicht bereit" + docker compose -f "$COMPOSE_FILE" ps || true + docker compose -f "$COMPOSE_FILE" logs backend --tail 80 || true + exit 1 + fi + i=$((i + 1)) + sleep 5 + done + docker compose -f "$COMPOSE_FILE" exec -T backend sh -lc " + pip install -r /app/requirements-dev.txt && + cd /app && + ACCESS_LAYER_STRICT=1 python scripts/check_access_layer_hints.py && + python scripts/security_release_checks.py && + ACCESS_LAYER_INTEGRATION=1 TRAINING_PLANNING_INTEGRATION=1 SKIP_DB_MIGRATE=1 python -m pytest tests -m 'not slow' -ra -vv --tb=short + " +} + +run_lint() { + python3 -m py_compile "$APP_DIR/backend/main.py" + echo "Backend syntax OK" +} + +run_frontend() { + cd "$APP_DIR/frontend" + npm install + npm run build + echo "Frontend build OK" +} + +run_k6() { + wait_health + K6_VER="v0.55.0" + ARCH=$(uname -m) + case "$ARCH" in + x86_64) K6_ARCH=amd64 ;; + aarch64|arm64) K6_ARCH=arm64 ;; + *) echo "k6: unbekannte Architektur: $ARCH" >&2; exit 1 ;; + esac + echo "Installing k6 ${K6_VER} linux-${K6_ARCH}" + curl -sSL "https://github.com/grafana/k6/releases/download/${K6_VER}/k6-${K6_VER}-linux-${K6_ARCH}.tar.gz" -o /tmp/k6.tgz + tar -xzf /tmp/k6.tgz -C /tmp + sudo mv "/tmp/k6-${K6_VER}-linux-${K6_ARCH}/k6" /usr/local/bin/k6 + k6 version + cd "$APP_DIR" + echo "k6 gegen BASE_URL=$BASE_URL" + BASE_URL="$BASE_URL" k6 run scripts/load/k6-health-baseline.js + echo "k6 Health-Baseline passed" +} + +case "$CHECK" in + pytest) run_pytest ;; + lint) run_lint ;; + frontend) run_frontend ;; + k6) run_k6 ;; + *) + echo "Prüfung muss pytest, lint, frontend oder k6 sein, war: '${CHECK}'." >&2 + exit 1 + ;; +esac