florian.wilde/betreuungs-cockpit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity

Doku: Wo die Daten liegen, wie man sie prüft, und drei Fallen im Betrieb #46

New Issue
Closed
opened 2026-09-01 13:43:44 +00:00 by florian.wilde · 1 comment
florian.wilde commented 2026-09-01 13:43:44 +00:00
Owner
Copy Link
Copy Source

Was fehlt

Aus einer Fehlersuche am 31.08.2026 sind vier Lücken in der Dokumentation übriggeblieben. Alle vier haben die Suche verlängert.

1. Es steht nirgends, wo die Daten liegen

Ein neuer Abschnitt zwischen Schritt 11 und Aktualisieren in INSTALLATION.md:

  • Die drei Orte: Dokumente im Volume minio-daten, Datenbank in postgres-daten, Sicherungen unter ./backups
  • Wie man den Pfad auf der Platte findet (docker volume inspect …)
  • Dass dort keine anklickbaren PDFs liegen, sondern MinIO-Fragmente, und der Inhalt verschlüsselt ist
  • Wie man prüft, ob Akte und Speicher übereinstimmen — für jeden Akteneintrag muss eine Datei existieren, sonst behauptet eine Prüfsumme ein Dokument, das es nicht gibt
  • Welche Schlüssel man ohne Rückweg braucht: ENC_KEY_V1, SICHERUNG_PASSWORT, ggf. MINIO_KMS_SECRET_KEY

Hinweis: Sobald #41 umgesetzt ist, ändert sich die Aussage zur Sicherung. Am besten danach schreiben oder beim Umsetzen von #41 mitziehen.

2. Der mc-Alias überlebt kein Neuerstellen des Containers

Schritt 6 setzt ihn einmalig:

docker compose exec minio mc alias set lokal …

Er liegt in /root/.mc im Container. Nach jedem docker compose up -d minio ist er weg, und mc ls lokal liefert kommentarlos nichts — man hält seine Dokumente für verschwunden. Genau das ist passiert.

Alle mc-Aufrufe in der Doku auf die selbsttragende Form umstellen:

docker compose exec minio sh -c '
  mc alias set lokal http://localhost:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" >/dev/null &&
  mc ls --recursive lokal/betreuungs-cockpit
'

Das nimmt die Zugangsdaten aus den Variablen des Containers — kein source .env, keine Passwörter in der Befehlszeile, überlebt jeden Neustart.

3. Der Bucket-Name ist hartkodiert

Schritt 6 legt lokal/betreuungs-cockpit an, die Anwendung liest den Namen aber aus S3_BUCKET. Weicht der ab, zeigen beide aneinander vorbei. "lokal/$S3_BUCKET" benutzen.

4. set -a && source .env überstimmt spätere Änderungen

Die Doku empfiehlt das an zwei Stellen, sagt aber nicht, dass die exportierten Werte anschließend jedes docker compose up überstimmen — Shell-Variablen haben Vorrang vor der .env-Datei. Wer danach die .env ändert und neu startet, sieht keine Wirkung und sucht den Fehler überall, nur nicht in der eigenen Shell.

Ein Warnkasten an beiden Stellen, mit dem Hinweis auf unset oder eine frische Shell.

5. Nebenbei

docker-compose.override.yml in die .gitignore aufnehmen und in der Doku als vorgesehenen Ort für eigene Anpassungen benennen. update.sh prüft nur versionierte Dateien (--untracked-files=no) und lässt sie deshalb in Ruhe — das ist der saubere Weg für Anpassungen, die ein Update überleben sollen.

Akzeptanzkriterien

  • Der neue Abschnitt beantwortet „wo liegen meine Daten" und „ist alles vollständig" ohne Rückfrage.
  • Kein mc-Aufruf in der Doku setzt einen zuvor angelegten Alias voraus.
  • Kein Bucket-Name ist hartkodiert.
  • Die source .env-Falle ist an beiden Fundstellen benannt.
  • docker-compose.override.yml ist ignoriert und dokumentiert.
## Was fehlt Aus einer Fehlersuche am 31.08.2026 sind vier Lücken in der Dokumentation übriggeblieben. Alle vier haben die Suche verlängert. ### 1. Es steht nirgends, wo die Daten liegen Ein neuer Abschnitt zwischen *Schritt 11* und *Aktualisieren* in `INSTALLATION.md`: - Die drei Orte: Dokumente im Volume `minio-daten`, Datenbank in `postgres-daten`, Sicherungen unter `./backups` - Wie man den Pfad auf der Platte findet (`docker volume inspect …`) - Dass dort **keine** anklickbaren PDFs liegen, sondern MinIO-Fragmente, und der Inhalt verschlüsselt ist - Wie man prüft, ob Akte und Speicher übereinstimmen — für jeden Akteneintrag muss eine Datei existieren, sonst behauptet eine Prüfsumme ein Dokument, das es nicht gibt - Welche Schlüssel man ohne Rückweg braucht: `ENC_KEY_V1`, `SICHERUNG_PASSWORT`, ggf. `MINIO_KMS_SECRET_KEY` Hinweis: Sobald #41 umgesetzt ist, ändert sich die Aussage zur Sicherung. Am besten danach schreiben oder beim Umsetzen von #41 mitziehen. ### 2. Der `mc`-Alias überlebt kein Neuerstellen des Containers Schritt 6 setzt ihn einmalig: ```bash docker compose exec minio mc alias set lokal … ``` Er liegt in `/root/.mc` **im Container**. Nach jedem `docker compose up -d minio` ist er weg, und `mc ls lokal` liefert kommentarlos nichts — man hält seine Dokumente für verschwunden. Genau das ist passiert. Alle `mc`-Aufrufe in der Doku auf die selbsttragende Form umstellen: ```bash docker compose exec minio sh -c ' mc alias set lokal http://localhost:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" >/dev/null && mc ls --recursive lokal/betreuungs-cockpit ' ``` Das nimmt die Zugangsdaten aus den Variablen des Containers — kein `source .env`, keine Passwörter in der Befehlszeile, überlebt jeden Neustart. ### 3. Der Bucket-Name ist hartkodiert Schritt 6 legt `lokal/betreuungs-cockpit` an, die Anwendung liest den Namen aber aus `S3_BUCKET`. Weicht der ab, zeigen beide aneinander vorbei. `"lokal/$S3_BUCKET"` benutzen. ### 4. `set -a && source .env` überstimmt spätere Änderungen Die Doku empfiehlt das an zwei Stellen, sagt aber nicht, dass die exportierten Werte anschließend **jedes** `docker compose up` überstimmen — Shell-Variablen haben Vorrang vor der `.env`-Datei. Wer danach die `.env` ändert und neu startet, sieht keine Wirkung und sucht den Fehler überall, nur nicht in der eigenen Shell. Ein Warnkasten an beiden Stellen, mit dem Hinweis auf `unset` oder eine frische Shell. ### 5. Nebenbei `docker-compose.override.yml` in die `.gitignore` aufnehmen und in der Doku als vorgesehenen Ort für eigene Anpassungen benennen. `update.sh` prüft nur versionierte Dateien (`--untracked-files=no`) und lässt sie deshalb in Ruhe — das ist der saubere Weg für Anpassungen, die ein Update überleben sollen. ## Akzeptanzkriterien - Der neue Abschnitt beantwortet „wo liegen meine Daten" und „ist alles vollständig" ohne Rückfrage. - Kein `mc`-Aufruf in der Doku setzt einen zuvor angelegten Alias voraus. - Kein Bucket-Name ist hartkodiert. - Die `source .env`-Falle ist an beiden Fundstellen benannt. - `docker-compose.override.yml` ist ignoriert und dokumentiert.
florian.wilde added the in-arbeit label 2026-09-01 14:32:33 +00:00
florian.wilde started working 2026-09-01 14:32:45 +00:00
florian.wilde worked for 4 minutes 2026-09-01 14:37:00 +00:00
florian.wilde commented 2026-09-01 14:37:41 +00:00
Author
Owner
Copy Link
Copy Source

🚀 Umgesetzt und nach main übernommen.

Vorgehen

  1. Schritt 6 neu geschrieben — ein Befehl, der Alias und Bucket selbst mitbringt. Damit sind Falle 2, 3 und 4 auf einmal erledigt: kein Passwort in der Verlaufsdatei, kein source .env, kein fester Name, und er funktioniert nach jedem Neustart.
  2. Neuer Abschnitt „Wo deine Daten liegen" zwischen Schritt 11 und Aktualisieren, samt Eintrag im Inhaltsverzeichnis.
  3. docker-compose.override.yml in .gitignore und als vorgesehener Ort dokumentiert.
  4. tests/anleitung.test.ts — neun Prüfungen.

Die Reihenfolge hat sich gelohnt. Dieses Issue stand bewusst zuletzt: Die Aussage zur Sicherung hätte sonst zweimal geschrieben werden müssen. Jetzt steht dort schlicht „ja" statt einer Warnung.

Die Anleitung wird wie Code geprüft. Der Test liest den Text und besteht darauf: kein mc-Aufruf ohne mc alias set im selben Block, kein fest verdrahteter Bucket-Name, kein source .env außerhalb einer Erklärung, der Abschnitt vorhanden, alle drei Schlüssel genannt. Gegen vier Mutationen abgesichert.

Das ist ungewöhnlich für Dokumentation, aber hier angebracht: Alle vier Fallen waren sprachlich einwandfrei und trotzdem falsch. Ein Korrekturleser hätte sie nicht gefunden.

Geprüft: 769 Unit-Tests · tsc sauber · Lint sauber

Pull Request: #53 (gemergt)

🚀 **Umgesetzt und nach `main` übernommen.** <!-- claude-status pr: 53 --> **Vorgehen** 1. Schritt 6 neu geschrieben — ein Befehl, der Alias und Bucket selbst mitbringt. Damit sind Falle 2, 3 und 4 auf einmal erledigt: kein Passwort in der Verlaufsdatei, kein `source .env`, kein fester Name, und er funktioniert nach jedem Neustart. 2. Neuer Abschnitt „Wo deine Daten liegen" zwischen Schritt 11 und *Aktualisieren*, samt Eintrag im Inhaltsverzeichnis. 3. `docker-compose.override.yml` in `.gitignore` und als vorgesehener Ort dokumentiert. 4. `tests/anleitung.test.ts` — neun Prüfungen. **Die Reihenfolge hat sich gelohnt.** Dieses Issue stand bewusst zuletzt: Die Aussage zur Sicherung hätte sonst zweimal geschrieben werden müssen. Jetzt steht dort schlicht „ja" statt einer Warnung. **Die Anleitung wird wie Code geprüft.** Der Test liest den Text und besteht darauf: kein `mc`-Aufruf ohne `mc alias set` im selben Block, kein fest verdrahteter Bucket-Name, kein `source .env` außerhalb einer Erklärung, der Abschnitt vorhanden, alle drei Schlüssel genannt. Gegen vier Mutationen abgesichert. Das ist ungewöhnlich für Dokumentation, aber hier angebracht: Alle vier Fallen waren sprachlich einwandfrei und trotzdem falsch. Ein Korrekturleser hätte sie nicht gefunden. **Geprüft:** 769 Unit-Tests · `tsc` sauber · Lint sauber **Pull Request:** #53 (gemergt)
florian.wilde removed the in-arbeit label 2026-09-01 14:37:48 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blockiert
Offene Rueckfrage, Uhr steht
 in-arbeit
Claude arbeitet daran, Stopwatch laeuft
 zu-testen
Umgesetzt, PR offen, wartet auf Test
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
florian.wilde (Florian Wilde)
No Assignees
1 Participants
Notifications
Total Time Spent: 4 minutes
florian.wilde
4 minutes
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: florian.wilde/betreuungs-cockpit#46