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. Host, Pfade, Domains und Ports sind seit 2026-09-07 festgelegt (gleicher Raspberry Pi wie die Schwesterprodukte, eigene Compose-Projekte, keine Mitai-bodytrack/-Pfade).

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.

Server (Raspberry Pi 5, 192.168.2.49):

	Development	Production
Branch	develop	main
Host-Pfad	/home/lars/docker/kansho-dev	/home/lars/docker/kansho
Domain	dev.kansho.jinkendo.de	kansho.jinkendo.de
Frontend-Port	3096	3006
Backend-Port	8096	8005
Postgres	eigene Instanz kansho_dev, nicht nach außen	eigene Instanz kansho, nicht nach außen
Compose	docker-compose.dev-env.yml	docker-compose.yml

Operative Schritte: docs/DEPLOYMENT.md. Gitea intern: http://192.168.2.144:3000/Lars/Kansho.git.

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
successful Dev deploy → test.yml (pytest on kansho_test, Live-Smoke /api/health, Frontend-Build)
merge in main → deploy-prod.yml

Status: entschieden. Workflows liegen unter .gitea/workflows/ (deploy-dev.yml, deploy-prod.yml, test.yml). Muster analog Kairo: git reset --hard, build --no-cache, Health GET /api/health.

Additiv 2026-09-07 (Qualitätssystem): Backend-Runner ist pytest (backend/pytest.ini, backend/tests/conftest.py). Gitea startet die Suite erst nach erfolgreichem Dev-Deploy (workflow_run auf Deploy Development), nicht parallel zum Image-Build. Destruktive Tests bleiben auf kansho_test. Zusätzlich ein nicht-schreibender Smoke gegen die laufende Dev-API (kansho_dev, nur /api/health). Öffentliche URLs nach Host-Nginx/TLS: https://dev.kansho.jinkendo.de und https://kansho.jinkendo.de. LAN-Ports 3096/8096 und 3006/8005 bleiben die Compose-Publish-Ziele.

Kanshō-Repo liegt auf Gitea (Lars/Kansho). HTTPS-Push ist eingerichtet. Der Pi-Runner (ubuntu-latest) ist derselbe wie bei Mitai/Shinkan/Kairo.

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	lokal 5188/8018; Server 3096/8096 und 3006/8005; *.kansho.jinkendo.de	entschieden 2026-09-07
Host	gleicher Raspberry Pi wie Mitai/Shinkan/Kairo, eigene Compose-Projekte kansho / kansho-dev	entschieden 2026-09-07
Postgres	eigene Instanz je Umgebung (kansho / kansho_dev), kein Shared-Schema	entschieden 2026-09-07
Gitea Workflows	.gitea/workflows/ analog Kairo	entschieden 2026-09-07
Auto-Rollback	nein	verworfen
Dual-Backend	SQLite nur Windows-App ohne Docker; Server Dev+Prod PostgreSQL. pytest auf der Dev-Instanz in DB kansho_test neben kansho_dev (keine dritte Instanz)	entschieden 2026-09-07, pytest 2026-09-07
Öffentliche URLs	https://dev.kansho.jinkendo.de / https://kansho.jinkendo.de (Host-Nginx + Let's Encrypt; Einrichtung parallel)	entschieden 2026-09-07
Urlaubs-Laptop ohne Docker/SQLite	Phase A auf dem Heimrechner restored	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? Entschieden: ja, Pi 192.168.2.49, Pfade /home/lars/docker/kansho und kansho-dev.
2. Gemeinsames oder separates Postgres? Entschieden: eigene Instanz je Umgebung, kein Shared-Schema mit Mitai.
3. Backup-Rhythmus nach dem Prod-Cutover. Die Urlaubs-SQLite-Restore auf dem Heimrechner (Welle 1) ist die Übung für den bestehenden Datenbestand. Postgres-Dump plus Medien: docs/DEPLOYMENT.md und scripts/backup-postgres.sh. Erste Restore-Übung auf Dev vor dem Prod-Import.

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). Dual-Backend: SQLite nur für die Windows-App ohne Docker; Postgres im Container (zwei Instanzen: Dev kansho_dev, Prod kansho). Die Test-Suite nutzt dieselbe Dev-Postgres, Datenbank kansho_test neben kansho_dev, weil sie das Schema zurücksetzt. Ein direkter Sprung „Laptop-SQLite nach Prod-Postgres“ ohne Zwischen-Restore ist verworfen. Import: sqlite_to_postgres.py --confirm, zuerst Dev, dann Prod.

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.

Transportartefakt 2026-09-07: transfer/kansho-laptop-20260907.zip (SHA256 EBF7455D5688588E8C6E50C05D16200CE191D79FB7CEACDBA9C25460B7497B07). Nach erfolgreichem Restore auf dem Heimrechner das Verzeichnis transfer/ aus dem Arbeitsbaum entfernen. Die Git-Historie behält das Zip.

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

Compose, Dockerfiles, .gitea/workflows/ und der Postgres-Adapter liegen im Repository. Mitai unter C:\Dev\mitai-jinkendo 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/