Benjamin Weinlich 88c541c9ed docs(adr): mirror 6 ADRs from M7.1 into repo

Adds the Architecture Decision Records that were written during the
Forgejo deployment (M7.1) as part of moving docs from the iCloud folder
into this versioned repository.

Includes:
- ADR-0001: Forgejo vs Gitea (non-profit stewardship)
- ADR-0002: ai-apps placement (no separate VM)
- ADR-0003: Native OIDC, not ForwardAuth
- ADR-0004: Subdomain code.sdda.eu
- ADR-0005: Volume mount on /data (lesson learned)
- ADR-0006: Silent SSO via OAuth2 launch URL (lesson learned)

Plus a docs/adr/README.md that explains the ADR format, lists the
current ADRs, and provides a template for future entries.

Refs OP#1118

2026-04-11 22:26:05 +02:00

2.2 KiB

Raw Blame History

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)

Im Forgejo-Web-UI kannst du die README.md-Dateien durchklicken — jede erklärt ihren Unterordner und verlinkt die einzelnen Inhalte. Das ersetzt ein Wiki-Interface.

2.2 KiB Raw Blame History