tessera-ctl/.planning/quick/260909-cx0-dateisicherung-nachruesten-und-versionsa/260909-cx0-SUMMARY.md

---
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 <automated> — 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 <automated> — 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