| 11 neue Themes (aXion1337 Light + 10 Paletten) | ✅ Web live, in allen Clients — ⚠️ **Paletten waren falsch**, korrigiert → [Nachtrag](#nachtrag-2026-08-02--die-paletten-waren-erfunden) |
| 1 | **Drei auseinandergelaufene Dokustände**: Gitea-Wiki-Repo (gepflegt, nicht gespiegelt), `wiki`-Branch im gitops-Repo (Mai-Abzug von `docs/`), `docs/` im main. Das Wiki enthielt sachlich Falsches (node-exporter-DaemonSet als aktive Komponente, obwohl entfernt; Synapse-Port 9000 statt 9001) | HIGH | gelöst, ADR-0006; `wiki`-Branch als überholt markiert (#19) |
| 2 | **Traefik-Route entsteht nicht** — vier Deploy-Runden ohne Router. Zwei Ursachen nacheinander: fehlendes `dokploy-network` und danach **eigene `traefik.*`-Labels neben denen von Dokploy** | HIGH | gelöst; Merksatz unten |
| 3 | **`/favicon.ico` lieferte HTTP 200 mit `text/html`** — die nginx-`try_files`-Kette gab die 404-Seite mit Erfolgsstatus aus. Safari hielt das Icon für vorhanden und zeigte den Buchstaben-Fallback | MEDIUM | gelöst: Datei im Wurzelverzeichnis + `try_files $uri =404` für Assets |
| 4 | **CI-Job-Container kennt die Lab-CA nicht** (`unable to get local issuer certificate`); der erste Fix als globale CI-Variable brach den Checkout des eigenen Repos | MEDIUM | gelöst: CA im Repo, `GIT_SSL_CAINFO`**im Sync-Skript** |
| 5 | **Icons wurden nie vergrößert**: `PIL.thumbnail()` skaliert ausschließlich nach unten, das 277-px-Motiv blieb in 1024er-Icons eine Briefmarke (54 % × 38 % Füllung) | MEDIUM | gelöst mit `resize()` aus dem Original: 81 % |
| 6 | **Nur macOS bekam neue Icons** — Windows (`.ico`) und Web (`res/vector-icons/`, `manifest.json`) blieben auf Element | MEDIUM | gelöst, `c51b681` |
| 7 | **BookStack-Stack hatte fünf Fehler**: nicht existierende Image-Tags, `healthcheck.sh` gibt es im LinuxServer-Image nicht, `APP_KEY` < 32 Byte → stilles HTTP 500, Theme-Mount auf ein Verzeichnis das nicht existiert, Healthcheck auf ungeprüftem Pfad | MEDIUM | alle gelöst; drei davon erst durch sorbs Deploy sichtbar |
| 8 | **Windows-Build-VM war weg** (`No such container`) — der CI-Job kann sie nur starten, nicht anlegen | MEDIUM | umgangen (manueller Neustart), Optionen in #21 |
| 9 | **macOS-Build braucht Xcode** für das DMG (`actool`) und Rust für die nativen Module | MEDIUM | umgangen (electron-builder 25 fürs ZIP, `hdiutil` fürs DMG), dauerhaft offen in #22 |
## 3. Was die Eingrenzung ermöglicht hat
**Die Traefik-Logs.** Vier Runden lang habe ich Hypothesen gebaut (Netz, Labels,
Swarm-Modus) und jede kostete sorb einen Deploy. Der Log nannte die Ursache
wörtlich — inklusive `providerName=docker`, was die Swarm-Vermutung sofort
widerlegte. **Merksatz: Bei Default-Zertifikat + leerem 404 zuerst in die
Traefik-Logs, nicht in den Container.**
**Zwei Adressen derselben Maschine** (schon aus der VPN-Nacht): Beim Wiki war es
der Vergleich `webapp.asar` vs. `app.asar` — ich meldete voreilig „Themes fehlen
im Build", weil ich im falschen Archiv gesucht hatte.
**Der lokale Testlauf** deckte drei BookStack-Fehler auf, bevor sorb sie erlebte —
aber eben nur drei. Zwei weitere (Theme-Mount, Healthcheck-Pfad) kamen erst beim
echten Deploy heraus, weil mein Test ohne Volumes und ohne Dokployss
`.env`-Behandlung lief. **Ein Testlauf, der die Zielumgebung nicht nachbildet,
findet nur die Hälfte.**
## 4. Lehren
1. **Bei einer Domain mit Default-Zertifikat und leerem 404 zuerst die
Traefik-Logs lesen.** Ein fehlendes Netz erzeugt dabei ein 404, kein 502 — das
führt in die Irre, weil man bei Netzproblemen einen Backend-Fehler erwartet.
2.**Keine eigenen `traefik.*`-Labels neben denen von Dokploy.** Ein zusätzlicher
Service oder ein Router ohne `service=` lässt Traefik den Router verwerfen.
3.**Statische Dateien dürfen nie auf HTML zurückfallen** (`try_files $uri =404`),
sonst sieht jeder fehlende Pfad wie ein Erfolg aus.
4.**`thumbnail()` vergrößert nicht.** Wer Icons erzeugt, braucht `resize()` — und
die Quelle in voller Auflösung.
5.**Ein Rebrand ist mehr als eine Datei.** Icons leben pro Plattform an eigenen
Orten; wer nur eine ersetzt, merkt es erst, wenn der Nutzer fragt.
6.**Testumgebung ≠ Zielumgebung.** Der lokale Docker-Lauf fand die Fehler, die
das Image betreffen — nicht die, die aus Dokployss `.env`-Handling und den
Volumes entstehen.
7.**Verweise auf Issues prüfen, bevor sie in ein Release wandern.** In den
Release-Notes stand ein Link auf ein Issue, das ich nie angelegt hatte (fiel
