Benjamin Weinlich
88c541c9ed
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
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
# 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:
|
|
~~~mermaid
|
|
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)
|
|
|
|
## Navigation-Tipp
|
|
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.
|