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
31 lines
1.6 KiB
Markdown
31 lines
1.6 KiB
Markdown
# Runbooks
|
|
|
|
**Runbooks** sind Schritt-für-Schritt-Anleitungen für wiederkehrende operative Situationen — meist Notfälle oder seltene Wartungs-Aufgaben.
|
|
|
|
## Warum Runbooks?
|
|
- **Für dich selbst in 3 Monaten:** Wenn der Loco-Sync wieder kaputt ist und du dich nicht mehr an die Debug-Schritte erinnerst.
|
|
- **Für die AI:** Eine AI-Session kann ein Runbook **lesen und ausführen**, ohne dass du jede Zeile diktieren musst.
|
|
- **Für den Vertretungsfall:** Wenn du im Urlaub bist und jemand anderes dringend muss.
|
|
|
|
## Format
|
|
Jedes Runbook beschreibt:
|
|
1. **Wann anwenden** — Symptome, Trigger
|
|
2. **Voraussetzungen** — Zugänge, Tools, Secrets
|
|
3. **Schritte** — nummeriert, kopierbar (Bash-Blöcke)
|
|
4. **Verification** — wie man erkennt dass der Fix greift
|
|
5. **Was NIE machen** — typische Fallen
|
|
|
|
## Aktuelle Runbooks
|
|
|
|
### Forgejo
|
|
- **[forgejo-admin-recovery.md](forgejo-admin-recovery.md)** — Was tun wenn Authentik down ist und niemand mehr ins Forgejo kommt. Nutzt den lokalen `admin-local` Fallback-User.
|
|
- **[forgejo-backup-restore.md](forgejo-backup-restore.md)** — Backup-Format, Restore-Szenarien (komplett / nur DB / einzelne Datei), Disaster-Recovery auf neuem Server.
|
|
|
|
## Convention
|
|
- **Dateiname:** `<stack>-<action>.md`, z.B. `forgejo-backup-restore.md`, `loco-sync-debug.md`
|
|
- **Immer Bash-Blöcke** mit echten Kommandos, nicht Pseudo-Code
|
|
- **Erwartete Outputs** hinschreiben, damit man weiß wann's geklappt hat
|
|
- **Destruktive Aktionen fett markieren** ("⚠️ löscht ALLE Daten!")
|
|
|
|
## Neue Runbooks hinzufügen
|
|
Wenn du ein Problem zum zweiten Mal hast, wird es ein Runbook. Die AI kann dir das im Moment des Fixes schreiben — du reviewst im Commit.
|