diff --git a/CLAUDE.md b/CLAUDE.md index 03b504a..e399ed7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,10 +28,17 @@ Widerspruch gilt für Arbeitsweise und Prozess **diese** Datei. (Gitea zählte PRs mit; z. B. Gitea#48 → GitLab#46) — alte „gitops#N"-Verweise meinen die Gitea-Nummer; verbindlich ist der Migrations-Fußtext im Issue. - **Ausnahmen** (beide bewusst entschieden): Deploy-Übergabe-Issues laufen auf - dem Gitea-Tracker `sorb/management`, bis das Site-to-Site-VPN steht - ([ADR-0004](decisions/0004-site-to-site-vpn-hetzner-lab.md)); der + dem Gitea-Tracker `sorb/management`, bis [LABNET-03](https://git.lab/axion1337.chat/management/-/issues/13) + sie umzieht (das VPN dafür steht seit 2026-08-01, + [ADR-0004](decisions/0004-site-to-site-vpn-hetzner-lab.md)); der TURN-Rotations-CronJob öffnet seine PR weiter auf Gitea (nie dort mergen — Kanonisierung wie oben). +- **Dokumentation** ([ADR-0006](decisions/0006-wikis-konsolidieren-docusaurus.md)): + Das gitops-Wiki liegt seit 2026-08-02 auf git.lab (*Wiki*-Reiter im Projekt); + ⚠️ der `wiki`-**Branch** im gitops-Repo ist ein überholter Mai-Abzug von `docs/` + und nicht die gepflegte Fassung. Alle Quellen zusammen erscheinen unter + **wiki.lab** ([`homelab/wiki`](https://git.lab/homelab/wiki), Docusaurus) — + Inhalte werden beim Bau geholt, **Änderungen gehören ins Quell-Repo**. ## Arbeitsframework ([ADR-0005](decisions/0005-pm-framework-kanban.md)) diff --git a/README.md b/README.md index 3f7c7a9..bea9f86 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,11 @@ dieser Ausnahme sind Folgearbeit. | `verfahren/` | Wie wir arbeiten: [Deploy-Übergabe/DoD](verfahren/deploy-uebergabe.md), [Refinement & Retro](verfahren/refinement.md), [AARs](verfahren/aar/), Werkzeuge | | `hosts/`, `shared/` | **Bestand + Historie** je Host/Thema — offene Punkte sind Issues | +Gelesen wird das alles auch gebündelt unter **[wiki.lab](https://wiki.lab)** — +dort stehen Plattform-Wiki, Homelab-Doku und dieses Repo nebeneinander +([ADR-0006](decisions/0006-wikis-konsolidieren-docusaurus.md), Konfiguration in +[`homelab/wiki`](https://git.lab/homelab/wiki)). **Geändert wird immer hier, nie dort.** + ## Das Backlog: Issues + Board Alle offenen Punkte sind **Issues in diesem Projekt** (host-/infra-Scope, mit diff --git a/decisions/0006-wikis-konsolidieren-docusaurus.md b/decisions/0006-wikis-konsolidieren-docusaurus.md new file mode 100644 index 0000000..b5d1e7e --- /dev/null +++ b/decisions/0006-wikis-konsolidieren-docusaurus.md @@ -0,0 +1,60 @@ +# 0006 — Wikis ins Lab konsolidieren, Docusaurus als gemeinsame Lesefläche + +**Status:** akzeptiert · **Datum:** 2026-08-02 · **Entscheider:** sorb + +## Kontext + +Die Dokumentation lag an **drei Orten mit drei Ständen**, was beim Audit auffiel: + +1. **Gitea-Wiki-Repo** `…gitops.wiki.git` — 15 Seiten, gepflegt bis 2026-07-31. + Vom Push-Mirror **nicht** erfasst: ein Wiki ist ein eigenes Repo, kein Branch. +2. **`wiki`-Branch im gitops-Repo** — Stand 2026-05-14, mitgezogen, weil der Mirror + alle Branches trägt. Inhalt: ein damaliger Abzug von `docs/`, kein gepflegtes Wiki. +3. **`docs/` im main-Branch** — die eigentliche, laufend gepflegte Repo-Doku. + +Dazu waren die GitLab-Wikis aller Projekte **leer**, und die Wiki-Inhalte enthielten +sachlich falsche Aussagen (node-exporter-DaemonSet als aktive Komponente, obwohl am +2026-08-01 entfernt; Issues „in Gitea", obwohl migriert). + +## Entscheidung + +**Das Wiki zieht ins Lab** und wird Teil der git.lab-Wahrheit: Die 15 Seiten liegen +im GitLab-Wiki des gitops-Projekts (*Wiki*-Reiter). Damit entfällt die letzte +„direkt-zu-Gitea"-Ausnahme aus [ADR-0001](0001-gitlab-kanonisch-push-mirror.md). + +**Eine gemeinsame Lesefläche statt einer gemeinsamen Struktur:** Das Repo +[`homelab/wiki`](https://git.lab/homelab/wiki) baut mit Docusaurus eine Seite unter +`wiki.lab`, die drei Quellen **nebeneinander** zeigt — Plattform (gitops-Wiki), +Homelab (`homelab/docs`), Arbeitsweise (`management`). Die Inhalte werden beim Bau +eingesammelt; das Wiki-Repo enthält selbst keinen Text. + +## Konsequenzen + +- **Änderungen gehören ins Quell-Repo**, nie ins Wiki-Repo — was dort in `content/` + landet, wird beim nächsten Bau überschrieben. +- Der Bau läuft in der **Lab-CI** (nur dort gibt es Lesezugriff auf die Quellen) und + legt ein statisches Image in der Lab-Registry ab; Dokploy deployt es. Ein + **Pipeline-Zeitplan** ist der eigentliche Aktualisierungsmechanismus: Das Wiki folgt + den Quellen, ohne dass jemand im Wiki-Repo committen muss. +- Voraussetzung: Jedes Quell-Repo muss das Wiki-Projekt in seinen + *Job token permissions* freigeben. +- Jede Quelle bleibt **ohne dieses Tool lesbar** (direkt im Repo oder in der + GitLab-Oberfläche). Deshalb bringen die Quellen keine Docusaurus-Metadaten mit und + `.md` wird als CommonMark statt MDX geparst. +- **Der `wiki`-Branch im gitops-Repo ist überholt.** Er bleibt vorerst als Historie + stehen, ist aber in README und CLAUDE.md ausdrücklich als „nicht die gepflegte + Fassung" markiert. Löschen wäre sauberer — Entscheidung dazu steht aus + ([Issue #19](https://git.lab/axion1337.chat/management/-/issues/19)). + +## Verworfene Alternativen + +- **Alles in ein Repo verschmelzen:** Die Quellen haben unterschiedliche Leser und + Halbwertszeiten; eine gemeinsame Struktur hätte alle drei schlechter gemacht. +- **Wiki auf Gitea belassen:** widerspricht ADR-0002 und hielt eine Ausnahme am + Leben, die niemand mehr begründen konnte. +- **Inhalte per Submodule einbinden statt beim Bau klonen:** Submodules hätten die + Quellen an feste Commits gebunden — genau das Gegenteil von „das Wiki folgt den + Quellen". +- **MkDocs/Wiki.js:** Docusaurus gewählt wegen Multi-Instanz-Docs (die Bereiche + nebeneinander) und weil es rein statisch ausliefert — kein Server, keine Datenbank, + kein Betriebsaufwand.