Kansho/docs/architecture/technical/runtime_and_deploy.md

---
title: "Kanshō – Runtime, Migrationen und Deploy"
version: "0.1"
status: "Arbeitsstand"
date: "2026-08-19"
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 |

## 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.

### 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.

## 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/`