From 954e35e1e7491bb93bcf41df457954ef0f1039e7 Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Thu, 13 Aug 2026 12:00:00 +0000 Subject: [PATCH] =?UTF-8?q?docs(aar):=20Wiki.js-Umzug=20=E2=80=94=20Wiki.j?= =?UTF-8?q?s/Flux=20stumbles=20for=20forkers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- STATUS.md | 3 +- docs/aar/2026-08-13-wikijs-umzug.md | 58 +++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 docs/aar/2026-08-13-wikijs-umzug.md diff --git a/STATUS.md b/STATUS.md index fa7147a..804c61c 100644 --- a/STATUS.md +++ b/STATUS.md @@ -70,7 +70,8 @@ _none active_ | [0014](docs/adr/0014-wikijs-loest-docusaurus-ab.md) | accepted | 0014 — Wiki.js löst Docusaurus ab: abgeschottete Betriebs-/Anwenderdoku, docs-as-code | | [0015](docs/adr/0015-wiki-git-storage-ueber-gitea-kanonisieren.md) | accepted | 0015 — Wiki.js Git-Storage: Inhalt fließt Cluster→Gitea→kanonisiert nach git.lab | -## Open AARs (2) +## Open AARs (3) - [AAR — Refinement, Betrieb voranbringen, Git-Historie anonymisiert](docs/aar/2026-08-09-refinement-und-betrieb.md) - [AAR — `@apo` konnte nicht telefonieren: fehlende Synapse-`profiles`-Zeile](docs/aar/2026-08-11-apo-calls-profile-zeile.md) +- [AAR — Wiki.js-Umzug: Deploy, Theming, Git-Storage, Inhalts-Migration](docs/aar/2026-08-13-wikijs-umzug.md) diff --git a/docs/aar/2026-08-13-wikijs-umzug.md b/docs/aar/2026-08-13-wikijs-umzug.md new file mode 100644 index 0000000..e7ec81a --- /dev/null +++ b/docs/aar/2026-08-13-wikijs-umzug.md @@ -0,0 +1,58 @@ +--- +type: aar +status: open +date: 2026-08-13 +related: [docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md, docs/issues/0048-wikijs-in-der-suite-deployen.md, docs/issues/0050-wikijs-theming-farben-logo.md, docs/adr/0014-wikijs-loest-docusaurus-ab.md, docs/adr/0015-wiki-git-storage-ueber-gitea-kanonisieren.md] +--- + +# AAR — Wiki.js-Umzug: Deploy, Theming, Git-Storage, Inhalts-Migration + +**Datum:** 2026-08-13 · **Stack:** `matrix`-Namespace (K3s Hetzner), gitops-Repo + Wiki.js +**Auftrag:** Docusaurus durch Wiki.js ablösen (ADR-0014): reproduzierbar/deploybar, mit +Authentik-OIDC-Login + Abschottung, Theming, Git-Storage (ADR-0015), Postgres-Backup und +Migration der alten Inhalte. + +## 1. Ergebnis + +Alles live und verifiziert: headless Deploy über einen Konfig-Job, Authentik-OIDC-only +Login (`hideLocal`), Rollen + Abschottung (403-Nachweis mit echtem Anwender-Konto), +Branding, Git-Storage Wiki.js→Gitea→git.lab, nächtliches Postgres-Backup, 10 alte Seiten +migriert. #0046/#0048/#0049/#0050 `done`, ADR-0014/0015 `accepted`. + +Der Weg dahin hatte mehrere nicht-offensichtliche Stolpersteine — das ist der eigentliche +Wert dieses AAR: Wiki.js- und Flux-Eigenheiten, die ein Forker oder eine spätere Session +sonst teuer neu lernt. + +## 2. Befunde / Stolpersteine + +| # | Stolperstein | Klasse | Dokumentiert | +|---|---|---|---| +| 1 | **Wiki.js-Login-Seite ist nicht per Custom-CSS themebar.** `master.pug` rendert kein `injectCSS`, der Login-Bundle wendet es nicht an → eine dunkle Login-Karte ist config-seitig unmöglich; bleibt hell. | tool | #0050 | +| 2 | **Config-Werte brauchen `{"v": value}`-Kodierung.** Auth-Strategy UND Storage-Target lesen jeden Wert via `_.get(JSON.parse(value),'v',null)`. Ohne die Kodierung sind alle Werte `null` („requires an issuer option"). | tool | `wikijs-config.py` | +| 3 | **`hideLocal` statt local deaktivieren.** Wiki.js braucht eine Formular-Strategie, sonst rendert die Login-Seite leer. „Nur OIDC" ⇒ local aktiv lassen + `authHideLocal=true`; Break-Glass `/login?all`. | tool | `wikijs-config.py` | +| 4 | **Branding als statische Datei, nicht als gated Asset.** Ein per Upload eingespieltes Logo hängt an `read:assets` → 403 auf der unauth. Login-Seite. Lösung: unter `/_assets/img/...` mounten (öffentlich). | tool | `wikijs.yaml` | +| 5 | **Flux streift Bilder aus dem Build-Artefakt** (`*.png`/`*.jpg` in der Default-Ignore) → `configMapGenerator` scheitert mit „no such file or directory". Fix: `.sourceignore` mit Negationen. | infra | `gitops/.sourceignore` | +| 6 | **Geänderte immutable Job-Spec blockiert den GANZEN Flux-Apply.** Ändert sich die `wikijs-config`-Job-env, scheitert der Apply an der immutable Job — und **auch unabhängige Änderungen (ConfigMaps, Mounts) kommen still nicht durch**, obwohl die Source-Revision schon aktuell ist. Fix: Job löschen, Flux legt ihn neu an. | infra | dieser AAR | +| 7 | **1-MiB-ConfigMap-Limit.** Hochskalierte Favicons + 604-KB-Hintergrund sprengten es (kurzzeitig ein Split in zwei ConfigMaps). Fix: Hintergrund runterskalieren (2560→1920 px, 400 KB), alles in EINER ConfigMap. Icons NICHT hochskalieren (Bloat + unscharf). | infra | #0050 | +| 8 | **Git-Storage braucht den Remote-Branch vorab.** Wiki.js: „Invalid branch! Make sure it exists on the remote first." Ziel-Repo mit leerem Initial-Commit auf `main` bootstrappen. Nach fehlgeschlagenem Init sitzt der lokale Klon fest → `purge`-Action + re-init. | tool | ADR-0015 | +| 9 | **Cluster erreicht git.lab nicht (Absicht).** Wiki.js pusht nach Gitea, ein CI-Job kanonisiert Gitea→git.lab (Muster `canonize_rotation`, umgekehrte Richtung). | infra | ADR-0015 | + +## 3. Learnings (knapp) + +- **`checkAccess` ist Default-Deny** (`match && !deny`): eine Gruppe mit globalem + `read:pages` + Pfad-Regel auf `anwender` sieht `betrieb/*` von allein nicht — Abschottung + ohne explizite Deny-Regeln. Aber **immer mit einem echten Anwender-Konto gegentesten** + (lokaler Testnutzer in `wiki-anwender`, HTTP-Status je Seite prüfen). +- **Wiki.js ist config-seitig mächtig, aber eigenwillig** — vieles ist nur über + Quellcode-Lesen im Pod (`/wiki/server/...`) herauszufinden. Der Konfig-Job + (`wikijs-config.py`) kapselt das reproduzierbar; er ist die Doku. +- **Browser cachen Favicons hartnäckig** — ein „falsches" Tab-Icon ist meist Cache, kein + Deploy-Fehler. Erst server-seitig 16/32/`favicon.ico` prüfen, dann hart neu laden. + +## 4. Actions + +- In-place dokumentiert: Kommentare in `wikijs-config.py`, `wikijs.yaml`, `.sourceignore` + (gitops); Notizen in #0048/#0050; Architektur in ADR-0015. +- **Offen (Harvest):** Befunde 1–8 in eine `docs/wiki/stolpersteine/wikijs.md` ziehen + (Wiki.js-Betriebswissen an einem Ort), dann `status: harvested`. Die Refinement-Session + geht diesen AAR durch.