--- title: "Kanshō – Arbeitsauftrag Heim-Entwicklung, Server, Docker, Postgres" status: "Arbeitsauftrag für die Session nach dem Laptop-Transfer" date: "2026-09-07" document_role: "Cursor Implementation Brief / Home Environment Setup" canonical_handover: "docs/architecture/technical/environment_handover.md" --- # Arbeitsauftrag: Heim-Entwicklungsumgebung, Server und Datenübernahme Arbeite **nicht** auf der Urlaubs-SQLite als führende Instanz. Voraussetzung: `laptop_closeout.md` ist erfüllt (`origin/main` inkl. `transfer/`-Zip). USB/NAS sind auf dem Laptop nicht der Weg. Lies zuerst: - `docs/architecture/technical/environment_handover.md` - `docs/architecture/technical/documentation_index.md` - `docs/architecture/technical/runtime_and_deploy.md` - `docs/architecture/technical/product_frame_and_stack.md` - `docs/architecture/technical/mvp_implementation.md` §1 und §4 - fachlich nur `docs/architecture/functional/guardrails.md`, falls Egress oder Mapping berührt wird Mitai-Muster liegen unter `C:\dev\mitai` (Compose, Workflows). Kanshō-Ports, Host-Pfade und Datenbanken nicht aus Mitai kopieren. Keine Slice-2- oder Memory-Implementierung in diesem Auftrag. Kein Commit, bis der Nutzer ihn verlangt. --- ## Offene Host-Fragen, vor Phase B klären In `runtime_and_deploy.md` §1/§6/§7 eintragen, nicht nur im Chat lassen: 1. Derselbe Raspberry-Pi wie Mitai, eigenes Compose-Projekt? 2. Eigenes Postgres (empfohlen) oder gemeinsame Instanz mit getrennter Database? 3. Host-Pfade analog `/home/lars/docker/…` – konkrete Kanshō-Verzeichnisse? 4. Dev-/Prod-Domains und **Kanshō-Ports** (lokal bleiben 5188/8018)? 5. Welle 2 zuerst SQLite im Volume oder direkt Postgres? Solange 1–4 offen sind: nur Phase A ausführen. --- ## Phase A – Kontinuität (SQLite, ohne Docker) Ziel: Dieselbe Anwendung wie auf dem Laptop, mit den Urlaubsdaten, auf dem Heimrechner. 1. `git clone https://gitea.stommer.de/Lars/Kansho.git` (Windows-Pfadempfehlung `C:\dev\Kansho`, wenn frei). 2. `git log -1` muss den Opening-Fix und die Transfer-Doku enthalten. Fehlt das, zuerst Laptop-Push nachholen. 3. `.\scripts\dev-setup.ps1` 4. `backend/.env` neu aus `backend/.env.example` plus Provider-Keys (Passwortmanager / OpenRouter). Keys sind **nicht** im Zip und nicht in Git. 5. Backend aus, dann Restore aus dem geklonten Tree: ```powershell .\scripts\backup-local.ps1 restore -Archive .\transfer\kansho-laptop-20260907.zip -Confirm -Replace ``` 6. Start: Backend `--port 8018`, Frontend `npm run dev` (5188). 7. Abnahme Phase A: - [ ] `GET /api/health` - [ ] Login mit bestehendem Admin - [ ] Space `Kroatien 2026` und Test-Space sichtbar - [ ] Journal Days und mindestens ein Entry mit Medien - [ ] Identity-Mappings unter Admin vorhanden, Keys nicht in der DB - [ ] Ein Dialogzug: ohne gültige Policy fail-closed; mit konfiguriertem Generate über Privacy Gateway - [ ] `.\scripts\test-mvp.ps1` grün (Temp-Isolation) Danach ist der Laptop nicht mehr Source of Truth. Weitere Dialoge nur noch hier. --- ## Phase B – Docker-Gerüst (noch ohne fachliche Postgres-Migration, falls so entschieden) Erst nach beantworteten Host-Fragen. Muster Mitai, eigene Namen: - `docker-compose.yml` (Prod-ähnlich: Frontend-Nginx, Backend, Postgres 16) - `docker-compose.dev.yml` / `docker-compose.dev-env.yml` nach Familienbrauch - `backend/Dockerfile`, `frontend/Dockerfile` - Root-`.env.example` für Compose-Secrets (DB-Passwort, Provider-Keys). Bestehendes `backend/.env.example` nicht stillschweigend ersetzen. - Volumes für App-Daten und Medien. Keine Mitai-Volume-Namen (`bodytrack_*`). - Healthcheck Backend; Startup: DB ready → Migrationen → Uvicorn. - Lokale Ports **nicht** 3002/8002/5173/8000. Zwischenstand zulässig: Compose startet Backend weiterhin auf SQLite im Volume, Postgres-Container schon mitlaufen, App noch nicht umgestellt. Das muss in `runtime_and_deploy.md` explizit stehen. Abnahme Phase B: - [ ] `docker compose up` startet die drei Dienste - [ ] Frontend erreicht Backend über `/api` - [ ] Secrets nur in Host-`.env` - [ ] Re-Restore oder Volume-Mount der Phase-A-Daten dokumentiert - [ ] `scripts/test-mvp.ps1` bleibt der lokale Nicht-Docker-Weg --- ## Phase C – PostgreSQL als App-Persistenz Eigene Implementierung, kein stilles Umbenennen von `db.py`. 1. Adapter oder Dual-Backend: SQLite bleibt für Laptop/Tests zulässig, bis Postgres abgenommen ist. 2. `schema.sql` und die bestehenden `schema_migrations` nach Postgres-Dialekt führen (kein `PRAGMA`, `datetime('now')` prüfen, Typen). 3. Startpfad wie entschieden: Postgres ready → nummerierte SQL-Dateien → App. Fail-fast. 4. Einmaliges Migrationsskript SQLite → Postgres (Profile, Spaces, Journal, Medien-Metadaten, Mappings, Prompts). Medien-Dateien separat ins Volume. 5. Probe auf Kopie, nicht auf dem einzigen Backup. 6. Danach Backup-Strategie für Postgres (nicht nur `backup-local.ps1`). Restore-Übung wiederholen. Abnahme Phase C: - [ ] Leere Instanz startet und migriert - [ ] Übernommene Urlaubsdaten: Entry-Anzahl, Message-Anzahl, ein Medien-GET - [ ] Privacy Gateway unverändert fail-closed - [ ] Tests gegen Postgres oder klar getrennte SQLite-Testmatrix - [ ] Additive Doku in `runtime_and_deploy.md`, `mvp_implementation.md` §1/§4, `data_architecture.md` nur soweit Persistenzgrenzen betroffen sind --- ## Phase D – Gitea CI/CD Erst wenn Runner und Host-Pfade existieren (`runtime_and_deploy.md` §4). Vorlage: `C:\dev\mitai\.gitea\workflows\` (`deploy-dev.yml`, `deploy-prod.yml`, `test.yml`). - Branch `develop` anlegen, wenn Dev-Deploy gewünscht - Kanshō-Pfade, nicht `/home/lars/docker/bodytrack` - Healthcheck auf Kanshō-Ports - Testjob: Backend-Tests + Frontend-Build; keine Live-Provider-Keys im Runner --- ## Phase E – Transfer testen (Ende-zu-Ende) Nach Phase A zwingend, nach B/C erneut: 1. Neues Backup auf der Heiminstanz erzeugen und an einem Temp-Pfad wiederherstellen. 2. Einen Journal Day öffnen, kurzen Dialog, Generate nur wenn Keys gesetzt. 3. Opening-Invariante: abgeschlossener Vortag erzeugt keinen falschen Plan-Impuls. 4. Admin → Schnittstellen: Keys aus `.env`, nicht aus der DB. 5. Kein Klartext-Detect in `KANSHO_ENV=production` ohne `KANSHO_ALLOW_REMOTE_DETECT`. Der Operator-Übergang bis Ollama ist explizit, kein Umdeuten nach Development. 6. Regression: `.\scripts\test-mvp.ps1` --- ## Grenzen - Keine Mitai-Körperlogik, keine gemeinsamen Tabellen mit Mitai. - Keine Lockerung der Guardrails „weil Docker intern ist“. - Keine Produktiv-Domain erfinden. - Watchtower nicht still einschalten. - `Idea_seconmd_sclide.md` und Memory-Handover nicht in diesem Auftrag implementieren. ## Abschlussbericht 1. Welche Phasen tatsächlich gelaufen sind 2. Gewählte Host-Pfade, Ports, Compose-Projektnamen 3. Ob Daten SQLite oder Postgres führen 4. Restore-Nachweis (Anzahlen, ein Medienbeispiel ohne Inhalt zu zitieren) 5. Offene Punkte für die nächste Session ## Stand 2026-09-07 (Heimrechner) Phase A: Restore aus `transfer/kansho-laptop-20260907.zip` nach `backend/data/` (1 Profil, 2 Spaces inkl. `Kroatien 2026`, 17 Days/Entries, 20 Conversations, 379 Messages, 70 Mediendateien). Health `GET /api/health` ok. `backend/.env` neu aus Example (Keys vom Nutzer nachzutragen). `transfer/` danach aus dem Tree genommen. Phase B–D im Repository: Compose, Dual-Backend, Workflows, `docs/DEPLOYMENT.md`. Pi-Verzeichnisse und Host-nginx sind einmalig auf `192.168.2.49` anzulegen. Persönlicher Postgres-Import zuerst nach Dev, dann Prod.