management/docs/aar/2026-08-13-wikijs-umzug.md

type, status, date, related

type	status	date	related
aar	open	2026-08-13	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.