Richter-und-Zech/electric-horses-infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electric-horses-infra/docs/guides
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
..
authentik-oauth2-provider.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

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 — 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).