---
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.