Benjamin Weinlich
6570e81850
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
26 lines
1.3 KiB
Markdown
26 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).
|