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.
This commit is contained in:
1 parent
3a367b7bcc
commit
d62673e48b
89 files changed
+13463
-241
No files matched your search
@@ -0,0 +1,103 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## 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/`
|
||||
Reference in new issue
Block a user