--- phase: quick-260909-cx0 plan: 01 subsystem: infra tags: [docker-compose, docker-volume, backup, documentation, stack-versions] requires: [] provides: - "Benanntes Docker-Volume `user-files`, gemountet auf `/app/user-files` im Dienst `api`, in `docker-compose.yml` und `docker-compose.prod.yml`" - "Betriebshandbuch-Kapitel 6/7 beschreiben den Speicher korrekt als dauerhaft und weisen auf die abweichende Serverdatei hin" - "CLAUDE.md Technik-Block zeigt den installierten Stand statt der 2026-06/07-Empfehlung, mit eigenem Abschnitt fuer nie uebernommene Empfehlungen" - ".planning/research/STACK.md traegt eine datierte Hinweiszeile ohne Zahlenaenderung" affects: [dokumentation, betrieb, onboarding] actuals: tokens: 5226 tasks: 2 commits: 2 plan_head_before: dab72eb^ tech-stack: added: [] patterns: ["Benanntes Docker-Volume statt Bind-Mount fuer Container-interne Schreibverzeichnisse mit fester uid-Eigentuemerschaft"] key-files: created: [] modified: - docker-compose.yml - docker-compose.prod.yml - docs/anleitung-betrieb.md - CLAUDE.md - .planning/research/STACK.md key-decisions: - "Benanntes Volume user-files statt Bind-Mount: das Image legt /app/user-files an und uebereignet es uid 1001, ein leeres benanntes Volume uebernimmt das beim ersten Mounten, ein frisch von Docker erzeugtes Host-Verzeichnis gehoert dagegen root" - "docker-compose.dev.yml bleibt unveraendert, da Compose Mount-Listen ueber das Ziel zusammenfuehrt und die Kombination Basis+Dev den neuen Mount automatisch mittraegt" - "Nie uebernommene Empfehlungen (Keycloak, Redis, TanStack Query, shadcn/ui, Playwright, Husky, lint-staged) sowie zwei veraltete Hauptversionen (Next.js, Prisma) stehen in CLAUDE.md jetzt in einer Aufzaehlung statt in den Ist-Tabellen" - "STACK.md bleibt als datiertes Rechercheergebnis unveraendert, nur eine Hinweiszeile ergaenzt - keine Regeneration wuerde die korrigierten CLAUDE.md-Zahlen zurueckholen, ohne dass jemand die Herkunftsvermerke sieht" requirements-completed: [WINDOWS-17] coverage: - id: D1 description: "Alle drei gerenderten Compose-Konfigurationen (Basis, Prod, Basis+Dev) mounten fuer den Dienst api genau ein benanntes Volume user-files auf /app/user-files; Betriebshandbuch nennt die Mount-Zeile woertlich" requirement: "WINDOWS-17" verification: - kind: other ref: "node -e Skript aus PLAN.md Task 1 — docker compose config --format json fuer Basis/Prod/Basis+Dev plus String-Suche im Betriebshandbuch" status: pass human_judgment: false - id: D2 description: "CLAUDE.md nennt den tatsaechlich installierten Stand (Next.js 15.5.19, Prisma 6.19.3 etc.), keine nie eingebaute Technik mehr als Ist-Tabellenzeile, package.json/pnpm-lock.yaml unveraendert" verification: - kind: other ref: "node -e Skript aus PLAN.md Task 2 — Zeilenpruefung auf 15.5.19/6.19.3 plus Ausschlusspruefung; git diff --exit-code auf alle package.json/pnpm-lock.yaml" status: pass human_judgment: false - id: D3 description: "Lokaler Beweis, dass hochgeladene Dateien ein --force-recreate ueberleben, und Uebernahme der Mount-Zeilen auf /opt/tessera/docker-compose.yml auf alpha" verification: [] human_judgment: true rationale: "Beide Pruefungen erfordern einen Neubau der Container (lokal bzw. auf alpha) durch den Nutzer selbst - ausserhalb dieses Ausfuehrungsschritts, siehe execution_notes/constraints des Plans" duration: 12min completed: 2026-09-09 status: complete --- # Quick Task 260909-cx0: Dateisicherung nachgeruestet und Versionsangaben korrigiert Summary **Hochgeladene Dateien liegen jetzt in einem benannten Docker-Volume statt in der fluechtigen Container-Schicht, und CLAUDE.md nennt die tatsaechlich installierten Paketversionen statt der 2026-06/07-Empfehlung.** ## Performance - **Duration:** ca. 12 min - **Started:** 2026-09-09T07:25:00Z (ungefaehr, kein exakter Start-Zeitstempel erfasst) - **Completed:** 2026-09-09T07:37:39Z - **Tasks:** 2/2 - **Files modified:** 5 ## Accomplishments - WINDOWS #17 (Datenverlust bei `--force-recreate`) im Repository behoben: `docker-compose.yml` und `docker-compose.prod.yml` mounten `/app/user-files` im Dienst `api` jetzt auf das benannte Volume `user-files` - Betriebshandbuch (`docs/anleitung-betrieb.md`) Kapitel 6 beschreibt den Speicher korrekt als dauerhaft, nennt die Mount-Zeile woertlich zum Kopieren und weist ausdruecklich auf die vom Repository abweichende `/opt/tessera/docker-compose.yml` hin; Kapitel 7 Fehlertabelle passt dazu - `CLAUDE.md` zeigt jetzt den installierten Stand (Next.js 15.5.19, Prisma 6.19.3, NestJS 11.1.27, Express 5.2.1, Node `node:24-alpine`, Vitest je App, Docker/Compose als gemessene Wirtseigenschaft, eigenes Auth-Stack statt Keycloak) statt der alten Empfehlung - Nie uebernommene Empfehlungen (Keycloak, Redis, TanStack Query, shadcn/ui, Playwright, Husky, lint-staged) sowie zwei veraltete Hauptversionen (Next.js 16 statt 15, Prisma 7 statt 6) stehen jetzt sichtbar in einer eigenen Aufzaehlung "Recommended But Not Adopted" statt als Ist-Tabellenzeile - `.planning/research/STACK.md` traegt eine datierte Hinweiszeile, Zahlen darin unveraendert ## Task Commits Each task was committed atomically: 1. **Task 1: user-files dauerhaft speichern und das Betriebshandbuch nachziehen (WINDOWS #17)** - `dab72eb` (fix) 2. **Task 2: Versionsangaben in CLAUDE.md auf den installierten Stand bringen** - `c807049` (docs) _Kein separater Plan-Metadaten-Commit gemaess Konstellation dieses Ausfuehrungsschritts (SUMMARY.md/STATE.md werden vom Orchestrator committet)._ ## Files Created/Modified - `docker-compose.yml` - `api`-Dienst mountet `user-files:/app/user-files`, Top-Level-Volume `user-files` ergaenzt - `docker-compose.prod.yml` - identisch zu `docker-compose.yml` - `docs/anleitung-betrieb.md` - Kapitel 6 (Datenhaltung, Mount-Zeile, Server-Hinweis) und Kapitel 7 (Fehlertabelle) korrigiert, Schreibfehler "daürhafte" behoben - `CLAUDE.md` - Technik-Block zwischen `GSD:stack-start`/`GSD:stack-end` auf installierten Stand gebracht, neuer Abschnitt "Recommended But Not Adopted", Herkunftsvermerk, angepasste Alternatives Considered/Version Pinning Strategy/Sources/Multi-Tenancy Strategy - `.planning/research/STACK.md` - Hinweiszeile unter der Ueberschrift "v1.0 Base Stack (reference — unchanged)", sonst unveraendert ## Die tatsaechlich eingetragene Mount-Zeile (zum Kopieren auf den Server) In beiden Compose-Dateien beim Dienst `api` (vor `healthcheck:`): ```yaml volumes: - user-files:/app/user-files ``` Im Top-Level-Block `volumes:` (neben `pgdata:`): ```yaml volumes: pgdata: user-files: ``` Genau diese zwei Aenderungen (Dienst-Zeile + Top-Level-Eintrag) muss der Nutzer selbst in `/opt/tessera/docker-compose.yml` eintragen, um die Reparatur auf alpha wirksam zu machen (vorher sichern). ## Ergebnis der beiden Tore, vor und nach der Arbeit **Tor 1 (Task 1, Mount):** Vor der Aenderung: `docker compose config --format json` fuer Basis, Prod und Basis+Dev meldete dreimal `FEHLT`, das Betriebshandbuch enthielt die Mount-Zeile nicht — Ruckgabewert 1. Nach der Aenderung: alle drei Konfigurationen melden `OK volume:user-files`, das Betriebshandbuch enthaelt die Zeile — Ruckgabewert 0. Selbst ausgefuehrt und bestaetigt (siehe Ausfuehrungsprotokoll dieses Schritts). **Tor 2 (Task 2, Versionen):** Vor der Aenderung: Next.js-Zeile nannte 16.2.x (nicht 15.5.19), Prisma-Zeile nannte 7.8.x (nicht 6.19.3), acht Tabellenzeilen fuehrten nie eingebaute Technik als Ist-Zeile — Ruckgabewert 1. Nach der Aenderung: alle drei Teilpruefungen `OK`, Ruckgabewert 0. Der Abhaengigkeits-Guard (`git diff --exit-code` auf alle `package.json` und `pnpm-lock.yaml`) war vor und nach der Arbeit gruen (Ruckgabewert 0) — bestaetigt, dass keine Abhaengigkeit angefasst wurde. ## Beim Nachschlagen gefundene Abweichungen von der Versionstabelle des Plans Keine. Die eigene Pruefung gegen `pnpm-lock.yaml` (`importers:`-Abschnitt), die Compose-/Dockerfiles und die lokal gemessenen Docker-/Compose-Versionen (Docker 29.8.0, Compose v5.5.1) deckt sich in jedem Punkt mit der im Plan-`objective` dokumentierten Tabelle vom 2026-09-09. Keine Abweichung zu vermerken. ## Decisions Made - Benanntes Volume statt Bind-Mount fuer `user-files` — Begruendung: Eigentuemerschaft. Das Image legt `/app/user-files` an und uebereignet es uid 1001 (`apps/api/Dockerfile:23-26`), der Prozess laeuft als dieser Nutzer (`:36`). Ein leeres benanntes Volume uebernimmt beim ersten Mounten Inhalt und Eigentuemerschaft des Image-Verzeichnisses; ein von Docker frisch angelegtes Host-Verzeichnis gehoert dagegen root und wuerde ohne eine zusaetzliche manuelle Uebereignung durch den Betreiber zu kaputten Uploads fuehren. - `docker-compose.dev.yml` bewusst nicht angefasst — Compose fuehrt Mount-Listen ueber das Ziel zusammen, die Kombination Basis+Dev traegt den neuen Mount automatisch mit (selbst am gerenderten Ergebnis geprueft). - Nie uebernommene Empfehlungen und veraltete Hauptversionen in CLAUDE.md aus den Ist-Tabellen entfernt und in einen eigenen, deutlich benannten Aufzaehlungs-Abschnitt verschoben, statt sie dort stehen zu lassen wo "ist eingebaut" impliziert wuerde. - `.planning/research/STACK.md` inhaltlich nicht angetastet (nur eine Hinweiszeile) — es ist ein datiertes Rechercheergebnis, keine Live-Dokumentation. ## Deviations from Plan None - plan executed exactly as written. ## Issues Encountered None. ## User Setup Required **Reparatur auf alpha steht noch aus.** `/opt/tessera/docker-compose.yml` auf dem Testserver ist keine Arbeitskopie dieses Repositorys — sie wurde dort von Hand bearbeitet und weicht ab; ein Deploy holt ausschliesslich Images und fasst diese Datei nicht an. Diese Reparatur erreicht die laufende Installation deshalb **nicht von selbst**. **Naechster Schritt (durch den Nutzer):** 1. `/opt/tessera/docker-compose.yml` sichern. 2. Die beiden oben genannten Zeilen (Dienst-Mount + Top-Level-Volume) dort eintragen. 3. Container einmal neu erstellen. 4. Pruefen: `docker inspect tessera-api-1` → unter `Mounts` muss `/app/user-files` erscheinen. 5. Erst danach den Ledger-Eintrag schliessen: `gsd-tools windows fixed 17`. Bis dahin bleibt **WINDOWS #17 im Ledger offen** — dieser Ausfuehrungsschritt hat ihn absichtlich nicht geschlossen, weil die Luecke auf der laufenden Installation weiterbesteht. Zusaetzlich, falls gewuenscht (keine Voraussetzung fuer den Server-Schritt): lokaler Beweis, dass Dateien einen `--force-recreate` ueberleben (Container mit den geaenderten Compose-Dateien neu erstellen, Profilbild hochladen, `docker compose up -d --force-recreate api`, Seite neu laden — Bild muss noch da sein). ## Next Phase Readiness - Kein Blocker fuer weitere Arbeit. WINDOWS #17 bleibt bewusst offen, bis der Nutzer die Serverdatei ergaenzt hat. - CLAUDE.md und `docs/anleitung-entwicklung.md` wurden gegengelesen: keine Versionsangabe der beiden Dokumente widerspricht der jeweils anderen mehr. --- *Quick Task: 260909-cx0* *Completed: 2026-09-09* ## Self-Check: PASSED