Files

T

Thore Cimbal 0845af9c44 docs: decide Wiki.js (ADR-0014, supersedes 0007) + wiki build issues

ADR-0014 records the decision: Wiki.js replaces Docusaurus for the platform wiki
— the only option meeting both hard requirements (per-group abschotten AND
docs-as-code in git). BookStack ruled out (DB-only, no git). Scope excludes
homelab/docs; neckbeard docs stay in management; content in a dedicated wiki repo
(not a branch, not a monorepo). ADR-0007 set to superseded. #0047 resolved
(decided: Wiki.js). Build issues 0048 (deploy + git storage), 0049 (OIDC + roles/
abschottung: admins write, users read-only), 0050 (theming, colours+logo extracted
from homelab/wiki). #0046 becomes the umbrella. STATUS regenerated; all gates green.

2026-08-12 12:00:00 +00:00

3.3 KiB

Raw Blame History

type, id, status, date, supersedes, superseded_by, related

type

status

date

supersedes

superseded_by

adr

0014

accepted

2026-08-12

docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md

null

docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md

docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md

0014 — Wiki.js löst Docusaurus ab: abgeschottete Betriebs-/Anwenderdoku, docs-as-code

Kontext

ADR-0007 hielt „Docusaurus läuft, BookStack als Gegenentwurf" fest (Status proposed). Docusaurus ist statisch — kein Nutzermodell, Zugang nur als Alles-oder-nichts-Tor (Authentik-Forward-Auth, gitops-Guide 09). Drei harte Anforderungen von sorb (2026-08-12) sprengen das:

Abschottung nach Gruppe — Anwender dürfen die Betriebsdoku nicht sehen.
docs-as-code in git — hartes, nicht verhandelbares Kriterium.
Rollen — Admins editieren Betriebs- und Anwenderhandbücher, normale Nutzer nur lesen.

Statisches Docusaurus kann (1) und (3) strukturell nicht: es weiß zur Bauzeit nicht, wer guckt.

Betrachtete Optionen

Mehrere Docusaurus-Instanzen + Routing — Silos, geteilte Suche/Navigation, brechende Querverweise. Verworfen.
Docusaurus + Pfad-ACL im Proxy (Gruppen-Header) — gibt 403 statt Verstecken, Sidebar und Suche zeigen Verbotenes weiter. Verworfen.
BookStack — native Gruppen-Rechte + OIDC, aber Inhalt nur in der DB, kein git. Scheitert am harten docs-as-code-Kriterium. Verworfen.
Wiki.js — native Pfad-/Seiten-Regeln pro Gruppe und Git-Storage-Modul (Inhalt in einem git-Repo). Erfüllt als einziges beide harten Kriterien.

Entscheidung

Wiki.js löst Docusaurus als Plattform-Wiki ab.

Deployment in die ThreadNet Server Suite (k8s), nicht mehr als Overmind-Einzelstack — löst den Forward-Auth-Zwischenstand (Guide 09, axionwiki.lab/#0024) ab.
Inhalt in einem dedizierten wiki-Repo (Git-Storage). Kein Branch eines bestehenden Repos, kein Voll-Monorepo (Forkbarkeit der Produkte, Flux/Mirror pro Repo — Monorepo-Vorhaben liegt auf Eis, sorb).
Rollen über Authentik-Gruppen: Admins schreiben Betriebs- + Anwenderhandbücher; normale Nutzer nur lesen; Anwender sehen die Betriebsdoku nicht (Abschottung).
Scope: nur Betriebs- und Anwenderdoku. homelab/docs bleibt draußen — sorbs Homelab-Doku ist nicht Teil der Plattform.
Die Neckbeard-Framework-Artefakte (ADRs/AARs/Issues/Vision, von validate.py geprüft) bleiben in management; Wiki.js übernimmt sie nicht.

Konsequenzen

docs-as-code bleibt gewahrt — Wiki.js hält den Inhalt in git; harte Anforderung erfüllt.
Postgres nötig fürs Rendern/Auth/Suche. Kein Widerspruch zum git-Kriterium: git ist die Inhalts-Quelle, die DB ist Laufzeit-Cache/Index — braucht aber ein Backup.
Autorenmodell dreht sich: editiert wird in Wiki.js, nicht mehr in den Quell-Repos read-only aggregiert (das alte Docusaurus-Prinzip entfällt für die Betriebs-/Anwenderdoku).
Neues wiki-Repo auf git.lab (gespiegelt wie die übrigen).
Docusaurus + Guide 09 werden abgelöst; Guide 09 bleibt als Historie bis zur Umstellung.
ADR-0007 wird superseded.
Offen (Folge-Issues): Deployment in der Suite, Git-Storage, OIDC + Rollen/ Abschottung, Theming — siehe #0046 und die daraus abgeleiteten Bau-Issues.

3.3 KiB Raw Blame History