Kansho/docs/work_orders/home_environment_setup.md

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