Lars/Kansho
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
326a9a44c8
Kansho/docs/architecture/technical/runtime_and_deploy.md

127 lines
5.5 KiB
Markdown
Raw Normal View History

Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
---
title: "Kanshō – Runtime, Migrationen und Deploy"
version: "0.1"
status: "Arbeitsstand"
Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 08:25:20 +02:00
date: "2026-09-07"
Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
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 |
Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 08:25:20 +02:00
| 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 |
Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
## 7. Offene Fragen
1. Läuft Kanshō auf demselben Raspberry-Pi-Host wie Mitai, mit eigenen Compose-Projekten?
2. Gemeinsames oder separates Postgres?
Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 08:25:20 +02:00
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.
Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
MVP 0.92
2026-08-26 10:42:20 +02:00
### 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.
Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 08:25:20 +02:00
### 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.
Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
## 8. Querverweise
Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 08:25:20 +02:00
- Technisch: `product_frame_and_stack.md`, `security.md`, `environment_handover.md`, `mvp_implementation.md` §1
Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
2026-08-21 15:48:43 +02:00
- Fachlich: Offline und Sync bleiben `memory_storage_and_offline.md`; Deploy löst Offline nicht.
- Mitai: `MIGRATIONS.md`, `.gitea/workflows/`
Reference in New Issue Copy Permalink