Richter-und-Zech/electric-horses-infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electric-horses-infra/docs/runbooks
History
Benjamin Weinlich 6570e81850 docs(runbooks,guides): mirror runbooks and Authentik OIDC guide 
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
2026-04-11 22:26:24 +02:00
..
forgejo-admin-recovery.md docs(runbooks,guides): mirror runbooks and Authentik OIDC guide 2026-04-11 22:26:24 +02:00
forgejo-backup-restore.md docs(runbooks,guides): mirror runbooks and Authentik OIDC guide 2026-04-11 22:26:24 +02:00
README.md docs(runbooks,guides): mirror runbooks and Authentik OIDC guide 2026-04-11 22:26:24 +02:00

README.md

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 — Was tun wenn Authentik down ist und niemand mehr ins Forgejo kommt. Nutzt den lokalen admin-local Fallback-User.
  • 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.