Lars/Kansho
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
32acdc220b
Kansho/docs/work_orders/home_environment_setup.md
Lars 32acdc220b Ship the laptop journal backup via self-hosted Gitea. 
USB and NAS are unavailable on this machine; the zip is the only path for personal SQLite and media. Provider keys stay out of git.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 09:22:24 +02:00

6.7 KiB
Raw Blame History

title status date document_role canonical_handover
Kanshō – Arbeitsauftrag Heim-Entwicklung, Server, Docker, Postgres Arbeitsauftrag für die Session nach dem Laptop-Transfer 2026-09-07 Cursor Implementation Brief / Home Environment Setup 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:
.\scripts\backup-local.ps1 restore -Archive .\transfer\kansho-laptop-20260907.zip -Confirm -Replace

  1. Start: Backend --port 8018, Frontend npm run dev (5188).

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