History

Benjamin Weinlich 6570e81850 docs(runbooks,guides): mirror runbooks and Authentik OIDC guide Two Forgejo runbooks plus the Authentik OAuth2 provider guide, mirrored from the iCloud folder into the versioned repo. Runbooks: - forgejo-admin-recovery.md — fallback login when Authentik is down using the local admin-local user (prohibit_login reset via SQL). - forgejo-backup-restore.md — backup format, restore scenarios (full / DB-only / single file), disaster recovery on new host. Guides: - authentik-oauth2-provider.md — reusable template for adding native OIDC integrations in Authentik. First applied for Forgejo, ready to reuse for OpenProject, Nextcloud, Grafana. Includes the important launch-URL gotcha from ADR-0006. Each category folder has a README.md with format conventions and an index of the current documents. Refs OP#1118		2026-04-11 22:26:24 +02:00
..
adr	docs(adr): mirror 6 ADRs from M7.1 into repo	2026-04-11 22:26:05 +02:00
architecture	docs(architecture): add ai-apps stack inventory snapshot	2026-04-11 22:19:25 +02:00
guides	docs(runbooks,guides): mirror runbooks and Authentik OIDC guide	2026-04-11 22:26:24 +02:00
runbooks	docs(runbooks,guides): mirror runbooks and Authentik OIDC guide	2026-04-11 22:26:24 +02:00
README.md	docs(adr): mirror 6 ADRs from M7.1 into repo	2026-04-11 22:26:05 +02:00

README.md

docs/

Alle Dokumentation zur Electric-Horses-Infrastruktur. Jeder Unterordner hat seine eigene README.md mit Konventionen und Index.

Struktur

docs/
├── README.md                  # diese Datei
│
├── architecture/              # Topologie, Stack-Inventories, Diagramme
│   └── ai-apps-stacks.md      #   Stack-Snapshot auf ai-apps
│
├── adr/                       # Architecture Decision Records
│   ├── README.md              #   Format-Guide + Index
│   └── 0001-0006-*.md         #   6 ADRs aus M7.1
│
├── runbooks/                  # Schritt-für-Schritt Anleitungen für Ops
│   ├── README.md              #   Format + Index
│   ├── forgejo-admin-recovery.md
│   └── forgejo-backup-restore.md
│
└── guides/                    # Wiederverwendbare Setup-Anleitungen
    ├── README.md              #   Format + Index
    └── authentik-oauth2-provider.md

Philosophie

Docs-as-Code: Dokumentation lebt neben dem Code, im selben Git-Repo, mit derselben Change-History. Keine separaten Wikis (driften), keine Confluence (teuer, closed), keine Notion (lock-in).

Mermaid für Diagramme: Forgejo rendert Mermaid-Blöcke im Web-UI direkt. Beispiel:

graph LR
  Browser --> Nginx
  Nginx --> Directus
  Nginx --> Astro

Markdown für alles andere: Keine Word-Docs, keine PDFs (außer Anhänge). Alles in Plain-Text lesbar + commitbar + diffbar.

Was hierher gehört

Architektur-Beschreibungen, Topologie-Diagramme
ADRs (warum haben wir X gebaut wie wir es gebaut haben)
Runbooks (wie debuggt / repariert man konkret)
Guides (wie richtet man etwas Wiederkehrendes ein)
How-Tos für Team-Onboarding (später, wenn das Team wächst)

Was NICHT hierher gehört

Secrets / Credentials (niemals, Repo ist public!)
Kundendaten / personenbezogene Daten (DSGVO)
Marketing-Texte (gehört auf die Website)
Lange Design-Specs in Rohform (lieber als ADR destillieren)