32acdc220b
USB and NAS are unavailable on this machine; the zip is the only path for personal SQLite and media. Provider keys stay out of git. Co-authored-by: Cursor <cursoragent@cursor.com>
129 lines
6.0 KiB
Markdown
129 lines
6.0 KiB
Markdown
---
|
||
title: "Kanshō – Runtime, Migrationen und Deploy"
|
||
version: "0.1"
|
||
status: "Arbeitsstand"
|
||
date: "2026-09-07"
|
||
product_family: "Jinkendo"
|
||
document_role: "Technical Chapter / Runtime / Deploy / Migrations"
|
||
parent_document: "technische_zielarchitektur.md"
|
||
---
|
||
# Kanshō – Runtime, Migrationen und Deploy
|
||
|
||
Kanonisches Home für Container-Start, Schema-Evolution und Gitea-Pipelines. Mitai-Referenz: `MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md`, `docker-compose.yml`, `docker-compose.dev-env.yml`, `.gitea/workflows/`.
|
||
|
||
## 1. Umgebungen
|
||
|
||
Muster der Familie: zwei Umgebungen, zwei Branches.
|
||
|
||
| Umgebung | Git-Branch | Rolle |
|
||
|---|---|---|
|
||
| Development | `develop` | Auto-Deploy nach Push |
|
||
| Production | `main` | Auto-Deploy nach Merge |
|
||
|
||
**Status: entschieden** als Betriebsmuster. Konkrete Domains, Host-Pfade und **Produktions-Ports** sind **offen** und werden nicht aus Mitai (`3002`/`8002`, `3099`/`8099`, `bodytrack/`) kopiert.
|
||
|
||
Lokale Entwicklung (ohne Docker) verwendet eigene Ports, nicht die Vite-/FastAPI-Defaults und nicht die Ports anderer lokaler Repos:
|
||
|
||
| Dienst | Port | Bindung |
|
||
|---|---|---|
|
||
| Frontend (Vite) | 5188 | `strictPort`, kein Ausweichen |
|
||
| Backend (Uvicorn) | 8018 | explizit |
|
||
|
||
Nicht verwenden: 5173, 5174, 4000, 4001, 8000.
|
||
|
||
Hypothese für spätere Benennung: `kansho.jinkendo.de` / `dev.kansho.jinkendo.de`, analog zur Foundation-Tabelle. Nicht festgelegt.
|
||
|
||
## 2. Container
|
||
|
||
Docker Compose mit mindestens:
|
||
|
||
- Frontend (Nginx + gebündelte PWA in Prod; Vite-Dev optional lokal)
|
||
- Backend (FastAPI)
|
||
- PostgreSQL 16
|
||
|
||
Secrets und SMTP nur in Server-`.env`, nicht im Repository. Vorlage: `.env.example`.
|
||
|
||
Watchtower oder gleichwertiges Image-Update: Mitai-Betrieb, für Kanshō **später prüfen**.
|
||
|
||
## 3. Schema-Migrationen
|
||
|
||
**Status: entschieden** (Muster)
|
||
|
||
1. Nummerierte SQL-Dateien `backend/migrations/XXX_*.sql`.
|
||
2. Tracking-Tabelle `schema_migrations`.
|
||
3. Startup: Postgres ready → Migrationen → App-Prozess.
|
||
4. Idempotenz wo möglich (`IF NOT EXISTS`).
|
||
5. Kein automatisches Schema-Downgrade.
|
||
|
||
Greenfield-Basis analog Mitai `schema.sql` ist zulässig. Änderungen danach nur über nummerierte Migrationen.
|
||
|
||
Fail-fast beim Start, wenn Migrationen scheitern. Kein stilles Weiterlaufen mit Drift.
|
||
|
||
## 4. Gitea CI/CD
|
||
|
||
Mitai-Pipeline als Vorlage:
|
||
|
||
```text
|
||
push develop → deploy-dev.yml → compose build/up → Healthcheck
|
||
push/PR nach Tests → test.yml (pytest, Frontend-Build)
|
||
merge in main → deploy-prod.yml
|
||
```
|
||
|
||
**Status: bevorzugte Richtung.** Workflow-Dateien erst anlegen, wenn Code und Runner-Pfade existieren.
|
||
|
||
Kanshō-Repo liegt bereits auf Gitea (`Lars/Kansho`). HTTPS-Push ist eingerichtet.
|
||
|
||
## 5. Was Deploy nicht übernimmt
|
||
|
||
- Blue-Green oder Multi-Region
|
||
- Automatisches Rollback der Datenbank
|
||
- Mitai-Verzeichnisnamen auf dem Pi
|
||
- Fachliche Datenberechnungen
|
||
|
||
## 6. Entscheidungsstand
|
||
|
||
| Thema | Stand | Status |
|
||
|---|---|---|
|
||
| Compose + Postgres + nummerierte SQL-Migrationen | ja | entschieden |
|
||
| develop → Dev, main → Prod | ja | entschieden |
|
||
| Ports/Domains/Hostpfade | Prod offen; lokal Frontend 5188 / Backend 8018 | lokal festgelegt, Prod offen |
|
||
| Gitea Workflows | Mitai-Muster | bevorzugte Richtung |
|
||
| Auto-Rollback | nein | verworfen |
|
||
| Urlaubs-Laptop ohne Docker/SQLite | Ist bis Transfer Welle 1 | dokumentiert 2026-09-07 |
|
||
| Transfer vor Postgres | SQLite-Restore auf dem Heimrechner zuerst | entschieden als Reihenfolge |
|
||
|
||
## 7. Offene Fragen
|
||
|
||
1. Läuft Kanshō auf demselben Raspberry-Pi-Host wie Mitai, mit eigenen Compose-Projekten?
|
||
2. Gemeinsames oder separates Postgres?
|
||
3. Backup-Rhythmus und Restore-Übung vor erstem persönlichen Dialogdatenbestand. Die Urlaubs-SQLite-Restore auf dem Heimrechner (Welle 1) ist diese Übung für den bestehenden Datenbestand; Produktions-Backup für Postgres bleibt offen.
|
||
|
||
### 7.1 Lokales Backup für die Urlaubs-Testphase (2026-08-25)
|
||
|
||
Kein Ersatz für Produktions-Backup, Docker oder Verschlüsselung.
|
||
|
||
- Erzeugen: `.\scripts\backup-local.ps1 create` oder `python backend\local_backup.py create --out <pfad>`
|
||
- Standardziel: `local-backups/` (gitignoriert)
|
||
- Wiederherstellen: `.\scripts\backup-local.ps1 restore -Archive <pfad> -Confirm`; bestehender Stand nur mit `--replace` nach automatischem Sicherheitsbackup
|
||
- SQLite-Backup-API, Journalmedien, Manifest mit Checksummen. Keine `.env` oder Keys. Das Archiv kann persönliche unverschlüsselte Daten enthalten.
|
||
|
||
### 7.2 Transfer Laptop → Heim-Entwicklung und Server (2026-09-07)
|
||
|
||
Die Urlaubsinstanz lief ohne Docker auf SQLite (`backend/data/kansho.sqlite`, Ports 5188/8018).
|
||
|
||
**Reihenfolge entschieden:** zuerst Kontinuität (Clone + SQLite-Restore + Smoke), danach Betriebsrahmen (Compose, Postgres 16, Gitea-Runner). Postgres bleibt Ziel; `backend/db.py` ist weiterhin SQLite. Ein direkter Sprung „Laptop-SQLite nach Prod-Postgres“ ohne Zwischen-Restore ist verworfen.
|
||
|
||
**Additiv 2026-09-07 (Transportweg):** Auf dem Urlaubs-Laptop dürfen weder USB-Stick noch NAS verbunden werden. Der einzige Weg für Datenbank und persönliche Journaldaten ist das **selbst gehostete** Gitea (`gitea.stommer.de`, nur eigene Infrastruktur). Das ist eine einmalige Transportentscheidung, kein Produktregelwechsel: Provider, OpenRouter und öffentliche Remotes bleiben ausgeschlossen. Provider-Keys und `backend/.env` bleiben **außerhalb** Git.
|
||
|
||
Aktuelles Transportartefakt: `transfer/kansho-laptop-20260907.zip` (SHA256 `EBF7455D5688588E8C6E50C05D16200CE191D79FB7CEACDBA9C25460B7497B07`). Nach erfolgreichem Restore auf dem Zielrechner das Verzeichnis `transfer/` aus dem Arbeitsbaum entfernen.
|
||
|
||
Kanonisches Session-Handover: `environment_handover.md`. Aufträge: `../../work_orders/laptop_closeout.md`, `../../work_orders/home_environment_setup.md`.
|
||
|
||
Noch nicht im Repository: Dockerfiles, Compose, `.gitea/workflows/`, Postgres-Adapter. Mitai unter `C:\dev\mitai` bleibt Muster, nicht Quelle für Ports oder `bodytrack/`-Pfade.
|
||
|
||
## 8. Querverweise
|
||
|
||
- Technisch: `product_frame_and_stack.md`, `security.md`, `environment_handover.md`, `mvp_implementation.md` §1
|
||
- Fachlich: Offline und Sync bleiben `memory_storage_and_offline.md`; Deploy löst Offline nicht.
|
||
- Mitai: `MIGRATIONS.md`, `.gitea/workflows/`
|