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.
84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
---
|
|
type: adr
|
|
id: "0007"
|
|
status: superseded
|
|
date: 2026-08-02
|
|
supersedes: null
|
|
superseded_by: docs/adr/0014-wikijs-loest-docusaurus-ab.md
|
|
related: []
|
|
---
|
|
|
|
# 0007 — Wiki-Oberfläche: Docusaurus läuft, BookStack als Gegenentwurf
|
|
|
|
**Status:** vorgeschlagen (Entscheidung offen → [Issue #20](https://git.lab/axion1337.chat/management/-/issues/20)) · **Datum:** 2026-08-02 · **Entscheider:** sorb
|
|
|
|
## Kontext
|
|
|
|
[ADR-0006](0006-wikis-konsolidieren-docusaurus.md) hat die Wikis ins Lab geholt und
|
|
Docusaurus als Lesefläche gebaut — läuft seit 2026-08-02 unter `axionwiki.lab`.
|
|
Danach kam der Wunsch nach einer BookStack-Variante, angeregt von der
|
|
[ESS-Dokumentation von Element](https://ems-docs.element.io/), die selbst auf
|
|
BookStack läuft und sehr aufgeräumt wirkt.
|
|
|
|
Beide Werkzeuge lösen dieselbe Aufgabe grundverschieden — deshalb ist das keine
|
|
Werkzeugwahl, sondern eine Weichenstellung.
|
|
|
|
## Entscheidung
|
|
|
|
**Beide Varianten existieren parallel, bis an echten Inhalten entschieden wird —
|
|
und beide bleiben dabei ausschließlich im Homelab** (bestätigt von sorb am
|
|
2026-08-02: keine Exponierung, solange nicht entschieden ist, ob überhaupt eine
|
|
der beiden dauerhaft eingebaut wird).
|
|
Docusaurus bleibt vorerst der produktive Weg (`axionwiki.lab`, läuft), BookStack
|
|
kommt als Vergleichsentwurf daneben (`bookstack.lab`, Repo
|
|
[homelab/wiki-bookstack](https://git.lab/homelab/wiki-bookstack)).
|
|
|
|
Die eigentliche Entscheidung wird **vertagt** — bewusst, weil sie an einer Frage
|
|
hängt, die sich am Reißbrett nicht beantworten lässt: Soll Dokumentation künftig
|
|
**im Repo** entstehen oder **im Browser**?
|
|
|
|
## Der Unterschied, auf den es ankommt
|
|
|
|
| | Docusaurus | BookStack |
|
|
|---|---|---|
|
|
| Wo der Text lebt | in den Quell-Repos, beim Bau eingesammelt | **in einer Datenbank** |
|
|
| Wie geändert wird | Commit, Review, Git-Historie | WYSIWYG im Browser |
|
|
| Betrieb | statisches Image, zustandslos | Anwendung + MariaDB, **backup-pflichtig** |
|
|
| Suche | fehlt (Plugin nötig) | eingebaut |
|
|
| Rechte | alles oder nichts | je Buch/Regal |
|
|
| Quelle der Wahrheit | eindeutig das Repo | **die Datenbank — neben den Repos** |
|
|
|
|
Die letzte Zeile ist der Kern. Mit BookStack entsteht eine zweite Quelle der
|
|
Wahrheit neben git.lab — genau das, was [ADR-0002](0002-issues-und-management-ins-lab.md)
|
|
für Issues gerade aufgelöst hat. Das kann richtig sein (Dokumentation hat andere
|
|
Autoren und Lebenszyklen als Code), muss aber bewusst entschieden werden.
|
|
|
|
## Konsequenzen
|
|
|
|
- **Doppelter Betrieb auf Zeit.** Zwei Stacks, zwei Domains. Vertretbar, solange es
|
|
ein Vergleich ist; auf Dauer ist es Ballast — deshalb gehört zu dieser Entscheidung
|
|
ein Verfallsdatum.
|
|
- **BookStack braucht ein Backup, sobald es mehr als ein Versuch ist.** Eine
|
|
Datenbank ohne Sicherung ist eine Zeitbombe (vgl. CFGMON-09, wo genau das seit
|
|
2026-07-30 offen ist).
|
|
- **Ein Einweg-Import zum Befüllen, aber keine Synchronisation** (`import/` im
|
|
BookStack-Repo). Nachtrag 2026-08-02: Ohne Inhalte lässt sich nichts
|
|
vergleichen, deshalb legt `provision.py` dieselben drei Bereiche an wie das
|
|
Docusaurus-Wiki. Ein *wiederholter* Sync bleibt bewusst aus — BookStack führt
|
|
Inhalte in seiner Datenbank, ein zweiter Lauf würde dort Bearbeitetes
|
|
überschreiben und Synchronität vortäuschen, die es nicht gibt.
|
|
- Die **Themes sind farbgleich** zu den Element-Themes (Gruvbox Dark und Sunset
|
|
Boulevard), damit der Vergleich nicht an der Optik hängt, sondern am Arbeitsmodell.
|
|
- Die Verliererseite wird **abgeräumt**, nicht „für später" behalten.
|
|
|
|
## Verworfene Alternativen
|
|
|
|
- **Direkt auf BookStack wechseln:** Docusaurus läuft bereits und kostet nichts im
|
|
Betrieb; ein Wechsel ohne belastbaren Vergleich wäre Geschmacksentscheidung.
|
|
- **BookStack gar nicht ausprobieren:** Die Frage „im Repo oder im Browser
|
|
schreiben?" ist real und betrifft künftig jede Doku — sie lässt sich nur an
|
|
echten Inhalten beantworten.
|
|
- **Beides dauerhaft parallel:** zwei Quellen der Wahrheit für dieselben Inhalte,
|
|
garantierte Drift. Genau der Zustand, den der Wiki-Audit vom 2026-08-02 aufgedeckt
|
|
hat (drei auseinandergelaufene Stände).
|