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
Exact
Benjamin Weinlich 09925f7eda docs(adr): add ADR-0007 on OIDC avatar data-URL gotcha 
When a new user logs in via Authentik OIDC for the first time,
Forgejo tries to fetch the 'picture' claim as an avatar — but
Authentik delivers a 'data:image/svg+xml;base64,...' URL that
Forgejo can't store. Result: DB has an avatar hash but no file,
so /avatars/<hash> returns 404, the <img> is in broken state,
and the activity page's canvas renderer crashes with
'drawImage on broken state'.

Fix (per user, after first login):
  UPDATE "user" SET avatar = '', use_custom_avatar = false
  WHERE lower_name = '<name>';

Triggers Forgejo's default identicon generation, which works.

This commit:
- Adds ADR-0007 with full root cause + three rejected alternatives
- Updates docs/adr/README.md index
- Extends stacks/forgejo/Agent.md 'Known Gotchas' with the fix
- Appends the fix to docs/runbooks/forgejo-admin-recovery.md

Applied for user 'bw' already on 2026-04-12.

Refs OP#1119
2026-04-12 04:47:25 +02:00
..
forgejo-admin-recovery.md docs(adr): add ADR-0007 on OIDC avatar data-URL gotcha 2026-04-12 04:47:25 +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.