From 0845af9c440c1ee3cad15e65ac43aae20f714281 Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Wed, 12 Aug 2026 12:00:00 +0000 Subject: [PATCH] docs: decide Wiki.js (ADR-0014, supersedes 0007) + wiki build issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- STATUS.md | 13 ++-- ...iki-oberflaeche-docusaurus-vs-bookstack.md | 4 +- docs/adr/0014-wikijs-loest-docusaurus-ab.md | 72 +++++++++++++++++++ ...wiki-in-threadnet-server-suite-umziehen.md | 7 ++ ...rflaeche-ueber-bookstack-hinaus-pruefen.md | 9 ++- .../0048-wikijs-in-der-suite-deployen.md | 34 +++++++++ .../0049-wikijs-oidc-rollen-abschottung.md | 36 ++++++++++ .../issues/0050-wikijs-theming-farben-logo.md | 35 +++++++++ 8 files changed, 202 insertions(+), 8 deletions(-) create mode 100644 docs/adr/0014-wikijs-loest-docusaurus-ab.md create mode 100644 docs/issues/0048-wikijs-in-der-suite-deployen.md create mode 100644 docs/issues/0049-wikijs-oidc-rollen-abschottung.md create mode 100644 docs/issues/0050-wikijs-theming-farben-logo.md diff --git a/STATUS.md b/STATUS.md index 76896c0..9c941d6 100644 --- a/STATUS.md +++ b/STATUS.md @@ -2,9 +2,9 @@ -## 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) diff --git a/docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md b/docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md index 243730f..5a02db2 100644 --- a/docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md +++ b/docs/adr/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md @@ -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: [] --- diff --git a/docs/adr/0014-wikijs-loest-docusaurus-ab.md b/docs/adr/0014-wikijs-loest-docusaurus-ab.md new file mode 100644 index 0000000..3dcf4c5 --- /dev/null +++ b/docs/adr/0014-wikijs-loest-docusaurus-ab.md @@ -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. diff --git a/docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md b/docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md index 224676f..bb6cd53 100644 --- a/docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md +++ b/docs/issues/0046-wiki-in-threadnet-server-suite-umziehen.md @@ -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. diff --git a/docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md b/docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md index ae3559d..f9ffff2 100644 --- a/docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md +++ b/docs/issues/0047-wiki-oberflaeche-ueber-bookstack-hinaus-pruefen.md @@ -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. diff --git a/docs/issues/0048-wikijs-in-der-suite-deployen.md b/docs/issues/0048-wikijs-in-der-suite-deployen.md new file mode 100644 index 0000000..043032f --- /dev/null +++ b/docs/issues/0048-wikijs-in-der-suite-deployen.md @@ -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. diff --git a/docs/issues/0049-wikijs-oidc-rollen-abschottung.md b/docs/issues/0049-wikijs-oidc-rollen-abschottung.md new file mode 100644 index 0000000..d91a2e9 --- /dev/null +++ b/docs/issues/0049-wikijs-oidc-rollen-abschottung.md @@ -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. diff --git a/docs/issues/0050-wikijs-theming-farben-logo.md b/docs/issues/0050-wikijs-theming-farben-logo.md new file mode 100644 index 0000000..39c04ab --- /dev/null +++ b/docs/issues/0050-wikijs-theming-farben-logo.md @@ -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.