docs(wiki): harvest Wiki.js stumbles; mark AAR harvested
Consolidate the 13 findings + learnings from the Wiki.js AAR into docs/wiki/stolpersteine/wikijs.md (config/deploy, theming, navigation, locale/timezone incl. the standing fork patch, access control, git-storage), link it from the wiki index, and set the AAR status to harvested. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Thore Cimbal
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
168fccc235
commit
8fd23274d8
@@ -71,8 +71,7 @@ _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 (3)
|
||||
## Open AARs (2)
|
||||
|
||||
- [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)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
type: aar
|
||||
status: open
|
||||
status: harvested
|
||||
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]
|
||||
---
|
||||
@@ -57,9 +57,9 @@ sonst teuer neu lernt.
|
||||
|
||||
- In-place dokumentiert: Kommentare in `wikijs-config.py`, `wikijs.yaml`, `.sourceignore`
|
||||
(gitops); Notizen in #0048/#0050; Architektur in ADR-0015.
|
||||
- **Offen (Harvest):** Befunde 1–13 in eine `docs/wiki/stolpersteine/wikijs.md` ziehen
|
||||
(Wiki.js-Betriebswissen an einem Ort), dann `status: harvested`. Die Refinement-Session
|
||||
geht diesen AAR durch.
|
||||
- **Geerntet 2026-08-14:** Befunde 1–13 + Learnings sind in
|
||||
[`docs/wiki/stolpersteine/wikijs.md`](../wiki/stolpersteine/wikijs.md) zusammengezogen
|
||||
(Wiki.js-Betriebswissen an einem Ort); dieser AAR ist damit `status: harvested`.
|
||||
|
||||
## 5. Nachtrag 2026-08-14 — Deutsch-Locale, Zeitzone & stehende Fork-Abweichung
|
||||
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ mit Inhalt. Projektfassung des neckbeard-Index (Original:
|
||||
| `vision/` | Eine Datei je Linie: [axion1337.chat](vision/axion1337-chat.md) · [Homelab](vision/homelab.md) · [ThreadNet](vision/threadnet.md) | belegt |
|
||||
| `user-guide/` | Für Nicht-Owner | entfällt — Gate 0: Publikum ist Owner + Sessions |
|
||||
| `requirements/` | Eigenständige Anforderungssicht | nur bei echtem Bedarf |
|
||||
| `faq/`, `stolpersteine/` | Nur aus AARs und geschlossenen Issues geerntet — nie auf Vorrat: [neckbeard-migration](stolpersteine/neckbeard-migration.md) | wächst im Refinement |
|
||||
| `faq/`, `stolpersteine/` | Nur aus AARs und geschlossenen Issues geerntet — nie auf Vorrat: [neckbeard-migration](stolpersteine/neckbeard-migration.md), [wikijs](stolpersteine/wikijs.md) | wächst im Refinement |
|
||||
|
||||
## Seitenregeln
|
||||
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
type: wiki-page
|
||||
area: stolpersteine
|
||||
sources:
|
||||
- "docs/aar/2026-08-13-wikijs-umzug.md"
|
||||
related:
|
||||
- "docs/adr/0014-wikijs-loest-docusaurus-ab.md"
|
||||
- "docs/adr/0015-wiki-git-storage-ueber-gitea-kanonisieren.md"
|
||||
---
|
||||
|
||||
# Stolpersteine: Wiki.js (Betrieb & Config)
|
||||
|
||||
Geerntet aus dem AAR zum Wiki.js-Umzug (2026-08-13/14); Belege, Diagnosen und Commits dort.
|
||||
Grundregel: **Wiki.js ist config-seitig mächtig, aber eigenwillig** — vieles ist nur durch
|
||||
Quellcode-Lesen im Pod (`/wiki/server/...`) herauszufinden. Der Konfig-Job
|
||||
(`gitops:apps/production/wikijs-config.py`) kapselt das reproduzierbar und ist die eigentliche Doku.
|
||||
|
||||
## Config & Deploy
|
||||
|
||||
- **Config-Werte brauchen `{"v": value}`-Kodierung.** Auth-Strategy, Storage-Target UND
|
||||
Renderer-Config lesen jeden Wert via `_.get(JSON.parse(value),'v',null)`. Ohne die Kodierung
|
||||
sind alle Werte `null` (z.B. „requires an issuer option").
|
||||
- **`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 über `/login?all`.
|
||||
- **Geänderte immutable Job-Spec blockiert den GANZEN Flux-Apply** — auch unabhängige
|
||||
ConfigMaps/Mounts kommen dann still nicht durch, obwohl die Source-Revision aktuell ist.
|
||||
Fix: Job löschen (`kubectl delete job …`), Flux legt ihn neu an.
|
||||
- **ConfigMap ohne Hash-Suffix (`disableNameSuffixHash`) aktualisiert in-place**, die Job-Spec
|
||||
ändert sich nicht → kein Immutable-Block, aber der fertige Job läuft nicht von selbst neu:
|
||||
ebenfalls Job löschen für den Rerun. (Propagation kann kurz nachhängen — vor dem Rerun den
|
||||
CM-Inhalt gegenprüfen.)
|
||||
- **1-MiB-ConfigMap-Limit.** Hochskalierte Favicons + großer Hintergrund sprengen es. Fix:
|
||||
Hintergrund runterskalieren (1920 px), Icons NICHT hochskalieren, alles in EINER ConfigMap.
|
||||
- **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.
|
||||
|
||||
## Theming & Branding
|
||||
|
||||
- **Die 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.
|
||||
- **Branding als statische Datei, nicht als gated Asset.** Ein hochgeladenes Logo hängt an
|
||||
`read:assets` → 403 auf der unauth. Login-Seite. Lösung: unter `/_assets/img/...` mounten (öffentlich).
|
||||
- **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.
|
||||
|
||||
## Navigation
|
||||
|
||||
- **Die Nav-Sidebar rendert `target` wortwörtlich als `href`** (Default-Theme: `href: item.target`,
|
||||
keine `targetType`- oder Slash-Behandlung). Page-Targets ohne führenden Slash lösen **relativ**
|
||||
auf → von `/betrieb/x` aus wird `betrieb/y` zu `/betrieb/betrieb/y` → 404 (von `/` aus geht es
|
||||
zufällig, daher lange unbemerkt); `home` mit leerem Target ist ebenfalls tot. Fix: Targets absolut
|
||||
speichern (`/<pfad>`; `home` → `/`).
|
||||
|
||||
## Locale & Zeitzone
|
||||
|
||||
- **Locale-Wechsel migriert nur `pages`.** Default umstellen via `localization.updateLocale`
|
||||
(lädt live, KEIN Neustart) + `pages.migrateToLocale` — letzteres patcht NUR die `pages`-Tabelle.
|
||||
`pageTree`/`pageLinks`/`pageHistory`/Suchindex bleiben auf der alten Locale → danach
|
||||
`pages.rebuildTree` + `search.rebuildIndex`, `pageLinks`/`pageHistory`-Restzeilen einmalig nachziehen.
|
||||
**Der Nav-Baum muss unter der NEUEN Locale liegen** (getTree nutzt die Seiten-Locale), sonst leere
|
||||
Sidebar. `namespacing:false` → saubere `/<pfad>`-URLs. **Inhalte gleich unter der Ziel-Locale anlegen**,
|
||||
spart die Migration.
|
||||
- **Die New-User-Zeitzone kommt aus dem DB-Spalten-Default** (`users.timezone` = `America/New_York`),
|
||||
NICHT aus Config: SSO-`processProfile` legt Nutzer ohne `timezone` an (`localeCode` dagegen aus
|
||||
`WIKI.config.lang.code`). Bestehende Konten per `users.update` korrigieren (patcht nur übergebene
|
||||
Felder). Neue Nutzer brauchen einen **Fork-Patch** — es gibt kein Custom-Image, daher als
|
||||
Startup-Overlay (Container-`command` sed-patcht `server/models/users.js`), idempotent + fail-open.
|
||||
⚠️ **Stehende Upstream-Abweichung**: hängt am Anker `localeCode: WIKI.config.lang.code,`, bei jedem
|
||||
Wiki.js-Upgrade gegenprüfen (dokumentiert im Manifest und auf `/betrieb/upgrades`).
|
||||
|
||||
## Zugriff & Abschottung
|
||||
|
||||
- **`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** (Testnutzer in
|
||||
`wiki-anwender`, HTTP-Status je Seite prüfen).
|
||||
|
||||
## Git-Storage & Editieren
|
||||
|
||||
- **Git-Storage braucht den Remote-Branch vorab.** „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.
|
||||
- **Der Cluster erreicht git.lab nicht (Absicht).** Wiki.js pusht nach Gitea, ein CI-Job kanonisiert
|
||||
Gitea→git.lab (Muster `canonize_rotation`, umgekehrte Richtung).
|
||||
- **Wiki-Inhalt nur über die Wiki.js-API editieren** — git-storage ist bidirektional, **nie** direkt
|
||||
nach Gitea schreiben (würde beim nächsten Sync kollidieren/überschrieben). Reproduzierbar via
|
||||
kurzlebigem In-Cluster-Job mit gemountetem Admin-Secret (Creds bleiben im Cluster; Pod-Label
|
||||
`app.kubernetes.io/name: wikijs-config` matcht die NetworkPolicy zu Wiki.js).
|
||||
Reference in New Issue
Block a user