Kansho/docs/architecture/technical/runtime_and_deploy.md

title	version	status	date	product_family	document_role	parent_document
Kanshō – Runtime, Migrationen und Deploy	0.1	Arbeitsstand	2026-09-07	Jinkendo	Technical Chapter / Runtime / Deploy / Migrations	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:

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). Persönliche Dialog- und Journaldaten liegen nicht in Gitea.

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.

Kanonisches Session-Handover: environment_handover.md. Aufträge: ../../work_orders/laptop_closeout.md, ../../work_orders/home_environment_setup.md.

Laptop-Backup dieser Session: local-backups/kansho-20260907-055703.zip (nur lokal, gitignoriert). .env reist getrennt.

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/