History

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
..
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
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)