sorb/management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AAR-Nachtrag: BookStack-Inbetriebnahme und Rebrand-Runden

Browse Source 
Fuenf Ursachen bei BookStack, die einander maskierten; wichtigste neue Lehre:
ein unhealthy Container ist fuer Traefik unsichtbar und sieht dabei exakt aus wie
ein fehlendes Netz. Dazu die electron-builder-Feinheit name vs. productName und
das Muster hinter meinen teuersten Fehlern: ungeprueft geaenderte Dinge.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj
This commit is contained in:
Thore Cimbal
2026-08-02 12:00:00 +00:00
co-authored by Claude Fable 5
parent 9c3d2529b4
commit c079ec2d7d
1 changed files with 32 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
verfahren/aar/2026-08-02-wiki-und-desktop-clients.md
+32
View File
@@ -67,6 +67,38 @@ findet nur die Hälfte.**
Release-Notes stand ein Link auf ein Issue, das ich nie angelegt hatte (fiel
erst bei der Konventionsprüfung auf).
## 4a. Nachtrag (2026-08-02 vormittags): drei weitere Runden
**BookStack lief erst nach fünf Anläufen.** Die Ursachen kamen nacheinander und
maskierten einander:
| # | Ursache | Wie sie sich zeigte |
|---|---|---|
| 1 | Anführungszeichen im `APP_KEY` (Dokploy schreibt Werte 1:1 in eine `.env`) | Deploy bricht ab: `unterminated quoted value` |
| 2 | `BOOKSTACK_TAG=25.07` aus meiner ersten `.env.example` — den Tag gibt es nicht | `manifest unknown` |
| 3 | **Healthcheck auf `/login` schlug fehl → Container `unhealthy` → Traefik überspringt ihn komplett** | Default-Zertifikat + leeres 404, **identisch zum Bild eines fehlenden Netzes** |
| 4 | `DB_PASSWORD` nachträglich geändert; MariaDB legt Zugangsdaten nur beim ersten Start an | `Access denied for user 'bookstack'` |
| 5 | `APP_KEY` weder 32 Byte noch mit `base64:`-Präfix | `Unsupported cipher or incorrect key length` |
**Die wichtigste neue Lehre:** Ein **`unhealthy` Container ist für Traefik
unsichtbar** — kein Router, kein Service, egal wie korrekt die Labels sind. Das
Symptom ist ununterscheidbar von einem fehlenden Netz. Ein Healthcheck, der nicht
im laufenden Container verifiziert wurde, ist damit kein Sicherheitsnetz, sondern
ein Risiko. Ich hatte ihn zweimal ungeprüft geändert (`/status` → `/login`).
**Rebrand:** Der Name saß erst nach drei Anläufen überall. `productName` regelt
den App-Namen (macOS/Windows), **`name`** den Linux-Paketnamen, das Binary und den
`/opt`-Pfad — und die CI braucht `VARIANT_PATH`, sonst greift die Variante gar
nicht. Icons: `PIL.thumbnail()` skaliert **nur nach unten**, weshalb das Motiv in
1024er-Icons nie vergrößert wurde; und ein Rebrand betrifft `.png`, `.ico`,
`.icns`, sieben Web-Icons und das Manifest — nicht eine Datei.
**Muster über beide Nächte:** Meine teuersten Fehler entstanden nicht durch
falsche Analysen, sondern durch **ungeprüfte Änderungen** — ein Healthcheck ohne
Test, ein Issue-Verweis ohne Existenzprüfung, ein Icon-Skript ohne Blick aufs
Ergebnis. Die Diagnose war jedes Mal gut, sobald echte Daten vorlagen
(Traefik-Logs, Laravel-Log, `docker inspect`).
## 5. Offen
- **BookStack-Deploy**: Domain-Maske in Dokploy (Service `bookstack`, Port 80) —