From 8aebe3b03da6fb0af0e4aca8beab707489cb5a5f Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Sun, 2 Aug 2026 12:00:00 +0000 Subject: [PATCH] AAR fuer die Wiki-/Client-Nacht + Wiki-Adresse korrigiert Das Verfahren verlangt einen AAR nach Deploys; er fehlte und ist damit die Luecke, die die zweite Konventionspruefung aufgedeckt hat. Neun Befunde, sieben Lehren - darunter 'zuerst in die Traefik-Logs', 'thumbnail vergroessert nicht' und 'Testumgebung ist nicht Zielumgebung'. Nebenbei: Verweise auf wiki.lab auf die real genutzte Adresse axionwiki.lab korrigiert. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj --- README.md | 2 +- .../2026-08-02-wiki-und-desktop-clients.md | 80 +++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 verfahren/aar/2026-08-02-wiki-und-desktop-clients.md diff --git a/README.md b/README.md index bea9f86..1c13eea 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ dieser Ausnahme sind Folgearbeit. | `verfahren/` | Wie wir arbeiten: [Deploy-Übergabe/DoD](verfahren/deploy-uebergabe.md), [Refinement & Retro](verfahren/refinement.md), [AARs](verfahren/aar/), Werkzeuge | | `hosts/`, `shared/` | **Bestand + Historie** je Host/Thema — offene Punkte sind Issues | -Gelesen wird das alles auch gebündelt unter **[wiki.lab](https://wiki.lab)** — +Gelesen wird das alles auch gebündelt unter **[axionwiki.lab](https://axionwiki.lab)** — dort stehen Plattform-Wiki, Homelab-Doku und dieses Repo nebeneinander ([ADR-0006](decisions/0006-wikis-konsolidieren-docusaurus.md), Konfiguration in [`homelab/wiki`](https://git.lab/homelab/wiki)). **Geändert wird immer hier, nie dort.** diff --git a/verfahren/aar/2026-08-02-wiki-und-desktop-clients.md b/verfahren/aar/2026-08-02-wiki-und-desktop-clients.md new file mode 100644 index 0000000..3949232 --- /dev/null +++ b/verfahren/aar/2026-08-02-wiki-und-desktop-clients.md @@ -0,0 +1,80 @@ +# AAR — Wiki-Rollout, Themes und Desktop-Clients (Nacht 2026-08-01/02) + +**Datum:** 2026-08-01 22:00 – 2026-08-02 09:30 · **Beteiligt:** sorb + Mac-Session +**Umfang:** Wiki-Konsolidierung, Docusaurus-Deploy, BookStack-Gegenentwurf, +11 neue Themes, Desktop-Clients für vier Plattformen, Rebrand-Start + +## 1. Ergebnis + +| Was | Stand | +|---|---| +| gitops-Wiki (15 Seiten) auf git.lab, inhaltlich korrigiert | ✅ | +| Docusaurus-Wiki unter `axionwiki.lab` | ✅ live, eigenes Zertifikat | +| BookStack als Gegenentwurf (`homelab/wiki-bookstack`) | ⚠️ Stack fertig, Deploy hakt noch an der Domain | +| 11 neue Themes (aXion1337 Light + 10 Paletten) | ✅ Web live, in allen Clients | +| Desktop-Clients Linux/Windows/macOS | ✅ Release `desktop-1.12.17-themes` | +| Rebrand Schritt 1 (Name + Icons) | ✅ macOS, Linux/Windows nach Rebuild | + +## 2. Befunde + +| # | Befund | Schwere | Status | +|---|---|---|---| +| 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, `cc3f860` | +| 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 + erst bei der Konventionsprüfung auf). + +## 5. Offen + +- **BookStack-Deploy**: Domain-Maske in Dokploy (Service `bookstack`, Port 80) — + gleiche Stelle wie beim Wiki. Danach Entscheidung DOC-03 (#20). +- **Navbar-Logo im Wiki**: HTML, CSS und Bild werden nachweislich korrekt + ausgeliefert, im Browser aber nicht sichtbar. Braucht einen Blick in die + Entwicklerkonsole. +- **macOS reproduzierbar bauen** (#22), **Windows-VM-Robustheit** (#21). +- **Rebrand-Rest**: About-Attribution im Client, `brand` in der Prod-Config, + Signing (ThreadNet-Web#6) — ohne Signatur bleibt für Nutzer auf macOS der + `xattr`-Schritt und auf Windows die SmartScreen-Warnung.