Thore Cimbal
0845af9c44
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.
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
---
|
|
type: adr
|
|
id: "0014"
|
|
status: accepted
|
|
date: 2026-08-12
|
|
supersedes: docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md
|
|
superseded_by: null
|
|
related: [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:
|
|
|
|
1. **Abschottung nach Gruppe** — Anwender dürfen die Betriebsdoku nicht sehen.
|
|
2. **docs-as-code in git** — hartes, nicht verhandelbares Kriterium.
|
|
3. **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.
|