sorb/management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Thore Cimbal
2026-08-12 12:00:00 +00:00
parent 5b0714a33a
commit 0845af9c44
8 changed files with 202 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
STATUS.md
+8 -5
View File
@@ -2,9 +2,9 @@
<!-- Generated by scripts/gen_status.py — do not edit. -->
## Issues (39 open, 2 closed)
## Issues (41 open, 3 closed)
Verteilung: M1 10 · M2 24 · M4 3 · M5 2
Verteilung: M1 10 · M2 23 · M4 6 · M5 2
| Issue | Status | Meilenstein | Priorität | Title |
|---|---|---|---|---|
@@ -46,13 +46,15 @@ Verteilung: M1 10 · M2 24 · M4 3 · M5 2
| [0044](docs/issues/0044-sops-secret-aenderung-startet-dienst-nicht-neu.md) | open | M5 | low | SOPS-Values-Secret-Änderung startet den konsumierenden Dienst nicht neu |
| [0045](docs/issues/0045-report-event-kein-kontaktweg-fuer-melder.md) | open | M1 | low | Inhalts-Meldung führt ins Leere: kein Kontaktweg für Melder |
| [0046](docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md) | open | M4 | medium | Wiki in die ThreadNet Server Suite umziehen |
| [0047](docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md) | open | M2 | low | Wiki-Oberfläche über BookStack hinaus prüfen |
| [0048](docs/issues/0048-wikijs-in-der-suite-deployen.md) | open | M4 | medium | Wiki.js in der ThreadNet Server Suite deployen (k8s + Postgres + Git-Storage) |
| [0049](docs/issues/0049-wikijs-oidc-rollen-abschottung.md) | open | M4 | medium | Wiki.js: Authentik-OIDC + Rollen und Abschottung |
| [0050](docs/issues/0050-wikijs-theming-farben-logo.md) | open | M4 | low | Wiki.js: Theming — Docusaurus-Farben und Logo übernehmen |
## Active design docs (0)
_none active_
## ADRs (13)
## ADRs (14)
| ADR | Status | Title |
|---|---|---|
@@ -62,13 +64,14 @@ _none active_
| [0004](docs/adr/0004-site-to-site-vpn-hetzner-lab.md) | accepted | 0004 — Site-to-Site-VPN Hetzner-Projektnetz ↔ Lab, schaltbar über die UDM |
| [0005](docs/adr/0005-pm-framework-kanban.md) | accepted | 0005 — Projektmanagement: Kanban-Rückgrat mit leichten Scrum-Elementen |
| [0006](docs/adr/0006-wikis-konsolidieren-docusaurus.md) | accepted | 0006 — Wikis ins Lab konsolidieren, Docusaurus als gemeinsame Lesefläche |
| [0007](docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md) | proposed | 0007 — Wiki-Oberfläche: Docusaurus läuft, BookStack als Gegenentwurf |
| [0007](docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md) | superseded | 0007 — Wiki-Oberfläche: Docusaurus läuft, BookStack als Gegenentwurf |
| [0008](docs/adr/0008-agenten-sessions-root-aequivalent.md) | accepted | 0008 — Agenten-Sessions auf CFGMON laufen root-äquivalent über die docker-Gruppe |
| [0009](docs/adr/0009-commit-konventionen-und-historien-anonymisierung.md) | accepted | 0009 — Commit-Konventionen und rückwirkende Anonymisierung der Historie |
| [0010](docs/adr/0010-haertung-eigener-meilenstein.md) | accepted | 0010 — Härtung ist ein eigener Meilenstein (M5); M1 misst nur Kaputtes |
| [0011](docs/adr/0011-enrollment-localpart-kollision-verweigern.md) | accepted | 0011 — Provisionierung verweigert Localpart-Kollisionen, statt an bestehende Konten zu verknüpfen |
| [0012](docs/adr/0012-issues-im-repo-gitlab-als-spiegel.md) | accepted | ADR-0012: Issues leben im Repo; GitLab wird deterministisch bespiegelt |
| [0013](docs/adr/0013-gruppenregeln-kanonisch-mit-pruefung.md) | accepted | ADR-0013: Gruppenregeln kanonisch im management-Repo, Komponenten zeigen und werden geprüft |
| [0014](docs/adr/0014-wikijs-loest-docusaurus-ab.md) | accepted | 0014 — Wiki.js löst Docusaurus ab: abgeschottete Betriebs-/Anwenderdoku, docs-as-code |
## Open AARs (2)
docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md
+2 -2
View File
@@ -1,10 +1,10 @@
---
type: adr
id: "0007"
status: proposed
status: superseded
date: 2026-08-02
supersedes: null
superseded_by: null
superseded_by: docs/adr/0014-wikijs-loest-docusaurus-ab.md
related: []
---
docs/adr/0014-wikijs-loest-docusaurus-ab.md
+72
View File
@@ -0,0 +1,72 @@
---
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.
docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md
+7
View File
@@ -33,3 +33,10 @@ der ThreadNet Server Suite ausrollen können.
Beim Umzug ändert sich der Host erneut — der `axionwiki.lab`-Stand aus #0024 gilt
nur bis dahin. Erst nach diesem Umzug greift #0047 (breitere Oberflächen-Evaluation).
## Realisierung (2026-08-12)
Der Umzug wird zugleich der Oberflächen-Wechsel: **Wiki.js statt Docusaurus**
(ADR-0014, #0047 entschieden). Dieses Issue ist die Klammer; die konkrete Arbeit
liegt in #0048 (Deployment + Git-Storage), #0049 (OIDC + Rollen/Abschottung) und
#0050 (Theming). `homelab/docs` bleibt draußen.
docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md
+8 -1
View File
@@ -1,7 +1,7 @@
---
type: issue
id: "0047"
status: open
status: done
created: 2026-08-12
milestone: M2
priority: low
@@ -31,3 +31,10 @@ tatsächlich braucht (Bereichs-Rechte? Browser-Editing? Git-Quelle?).
Bewusst `low` und ohne Termin: erst nach #0046 sinnvoll, vorher fehlt der Kontext
(die Anforderungen der Suite). Hängt inhaltlich an #0046.
## Entscheidung (2026-08-12, sorb)
**Wiki.js.** Es erfüllt als einziges beide harten Kriterien — Abschottung nach
Gruppe **und** docs-as-code (git-Storage). BookStack scheidet aus (Inhalt nur in
DB, kein git). Festgehalten in ADR-0014 (löst ADR-0007 ab). Umsetzung über #0046
und die daraus abgeleiteten Bau-Issues.
docs/issues/0048-wikijs-in-der-suite-deployen.md
+34
View File
@@ -0,0 +1,34 @@
---
type: issue
id: "0048"
status: open
created: 2026-08-12
milestone: M4
priority: medium
area: infrastructure
related: [docs/adr/0014-wikijs-loest-docusaurus-ab.md, docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md]
---
# Wiki.js in der ThreadNet Server Suite deployen (k8s + Postgres + Git-Storage)
## Problem / Motivation
ADR-0014: Wiki.js löst Docusaurus ab und wird Teil der ThreadNet Server Suite
(k8s), nicht mehr ein Overmind-Einzelstack. Braucht das Deployment plus den
Inhalts-Speicher.
## Acceptance
- Wiki.js läuft in der Suite (k8s): Deployment, **Postgres** (Rendern/Auth/Suche),
Ingress/TLS, in die GitOps-Definition aufgenommen (Flux).
- **Neues `wiki`-Repo** auf git.lab angelegt (gespiegelt wie die übrigen), als
Wiki.js **Git-Storage** eingebunden (bidirektionaler Sync) — Inhalt liegt in git
(hartes Kriterium, ADR-0014).
- Grundstruktur für **Betrieb** und **Anwender** angelegt (zwei Bereiche);
`homelab/docs` ausdrücklich **nicht** eingebunden.
- Postgres ist gesichert (Backup), da git nur Inhalt, nicht den Laufzeit-Zustand
hält.
## Notes
Ersetzt den Forward-Auth-Zwischenstand auf Overmind (Guide 09, #0024). OIDC +
Rollen kommen in #0049, Theming in #0050. Umbrella: #0046.
docs/issues/0049-wikijs-oidc-rollen-abschottung.md
+36
View File
@@ -0,0 +1,36 @@
---
type: issue
id: "0049"
status: open
created: 2026-08-12
milestone: M4
priority: medium
area: security
related: [docs/adr/0014-wikijs-loest-docusaurus-ab.md, docs/issues/0048-wikijs-in-der-suite-deployen.md]
---
# Wiki.js: Authentik-OIDC + Rollen und Abschottung
## Problem / Motivation
Der Kern der Wiki.js-Entscheidung (ADR-0014): Zugang und Sichtbarkeit nach
Authentik-Gruppe, was Docusaurus nicht konnte.
## Acceptance
- **Authentik-OIDC** als Login-Provider in Wiki.js (Gruppen-Claim gemappt).
- **Rollen** über Gruppen:
- **Admins**: schreiben (read+write) Betriebs- **und** Anwenderhandbücher.
- **Normale Nutzer**: nur lesen — kein Schreiben.
- **Abschottung**: Anwender sehen die **Betriebsdoku nicht** (Pfad-/Seiten-Regeln
pro Gruppe, `/betrieb/*` nur für die Betriebs-Gruppe). Betrieb darf Anwenderdoku
lesen.
- Verifiziert: Anwender-Konto sieht `/betrieb` nicht (nicht 403 mit sichtbarem
Link, sondern gar nicht in Navigation/Suche); Nicht-Admin kann nichts editieren;
Admin kann beides bearbeiten.
## Notes
⚠️ Braucht die **konkreten Authentik-Gruppen** von sorb: welche Gruppe = Betrieb,
welche = Anwender, welche = Admin (Vorschlag: `authentik Admins` schreibt,
`wiki-betrieb` liest Betrieb+Anwender, `wiki-anwender` liest nur Anwender). Zugangs-
/Gruppenvergabe macht sorb selbst.
docs/issues/0050-wikijs-theming-farben-logo.md
+35
View File
@@ -0,0 +1,35 @@
---
type: issue
id: "0050"
status: open
created: 2026-08-12
milestone: M4
priority: low
area: infrastructure
related: [docs/adr/0014-wikijs-loest-docusaurus-ab.md, docs/issues/0048-wikijs-in-der-suite-deployen.md]
---
# Wiki.js: Theming — Docusaurus-Farben und Logo übernehmen
## Problem / Motivation
Das neue Wiki soll aussehen wie das aktuelle Docusaurus (Wiedererkennung). Werte
aus `git.lab/homelab/wiki` extrahiert (2026-08-12):
- **Akzent/primary**: hell `#2b6cb0`, dunkel `#63b3ed` (blau)
- **Farbmodus**: dark als Default, `respectPrefersColorScheme`
- **Hintergrund/Rest**: `custom.css` überschreibt nichts → Docusaurus-Dark-Defaults
- **Logo**: `homelab/wiki:static/img/logo.png` (183×128, rotes Icon), alt „ThreadNet";
Wortmarke `threadnet-logo-wortmarke.png` (512×512)
- **Favicon**: `favicon.ico` + `favicon-32/96.png`
## Acceptance
- Wiki.js-Theme: dunkler Default, blauer Akzent (`#2b6cb0`/`#63b3ed`), Logo und
Favicon aus den obigen Assets übernommen (in das `wiki`-Repo kopiert, nicht aus
`homelab/wiki` referenziert).
- Optischer Abgleich gegen den Docusaurus-Stand (Screenshot 2026-08-12).
## Notes
Nice-to-have (`low`), nach #0048/#0049. Assets liegen in `homelab/wiki`; beim Bau
in das neue `wiki`-Repo kopieren.