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-08-19	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

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.

8. Querverweise

• Technisch: product_frame_and_stack.md, security.md
• Fachlich: Offline und Sync bleiben memory_storage_and_offline.md; Deploy löst Offline nicht.
• Mitai: MIGRATIONS.md, .gitea/workflows/