27 lines
1.3 KiB
Markdown
27 lines
1.3 KiB
Markdown
|
# Guides
|
||
|
|
|
||
|
|
**Guides** sind Anleitungen für Setup- und Konfigurations-Aufgaben die wiederholt vorkommen — aber nicht notfall-getrieben wie Runbooks. Sie sind das **"How do we do X here"** der Firma.
|
||
|
|
|
||
|
|
## Unterschied zu Runbooks
|
||
|
|
- **Runbook:** "Der Loco-Sync ist kaputt — was jetzt?" → reagiert auf Probleme
|
||
|
|
- **Guide:** "Wie integriere ich eine neue App mit Authentik OIDC?" → proaktive Einrichtung
|
||
|
|
|
||
|
|
## Unterschied zu ADRs
|
||
|
|
- **ADR:** "Warum haben wir diese Entscheidung getroffen?"
|
||
|
|
- **Guide:** "Wie setze ich diese Entscheidung für einen neuen Service um?"
|
||
|
|
|
||
|
|
Typisch: Eine ADR legt das Pattern fest, der Guide zeigt wie man es anwendet.
|
||
|
|
|
||
|
|
## Aktuelle Guides
|
||
|
|
|
||
|
|
### Authentik
|
||
|
|
- **[authentik-oauth2-provider.md](authentik-oauth2-provider.md)** — Wie richtet man einen nativen OIDC-Provider in Authentik für eine neue App ein? Template-based, wurde zum ersten Mal für Forgejo genutzt, ist jetzt wiederverwendbar für OpenProject, Nextcloud, Grafana, etc.
|
||
|
|
|
||
|
|
## Wann neue Guides schreiben
|
||
|
|
- Wenn eine Setup-Sequenz mehr als einmal vorkommen wird
|
||
|
|
- Wenn sie mehr als 5 Schritte hat
|
||
|
|
- Wenn die korrekte Reihenfolge nicht offensichtlich ist
|
||
|
|
- Wenn es Gotchas gibt die man schnell vergessen würde
|
||
|
|
|
||
|
|
Wenn es nur einmalig ist und nie wieder vorkommt: Kein Guide, sondern direkt als ADR dokumentieren (falls eine Entscheidung drinsteckt).
|