History

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
..
adr	docs(adr): add ADR-0007 on OIDC avatar data-URL gotcha	2026-04-12 04:47:25 +02:00
architecture	docs(architecture): add ai-apps stack inventory snapshot	2026-04-11 22:19:25 +02:00
guides	docs(runbooks,guides): mirror runbooks and Authentik OIDC guide	2026-04-11 22:26:24 +02:00
runbooks	docs(adr): add ADR-0007 on OIDC avatar data-URL gotcha	2026-04-12 04:47:25 +02:00
README.md	docs(adr): mirror 6 ADRs from M7.1 into repo	2026-04-11 22:26:05 +02:00

README.md

docs/

Alle Dokumentation zur Electric-Horses-Infrastruktur. Jeder Unterordner hat seine eigene README.md mit Konventionen und Index.

Struktur

docs/
├── README.md                  # diese Datei
│
├── architecture/              # Topologie, Stack-Inventories, Diagramme
│   └── ai-apps-stacks.md      #   Stack-Snapshot auf ai-apps
│
├── adr/                       # Architecture Decision Records
│   ├── README.md              #   Format-Guide + Index
│   └── 0001-0006-*.md         #   6 ADRs aus M7.1
│
├── runbooks/                  # Schritt-für-Schritt Anleitungen für Ops
│   ├── README.md              #   Format + Index
│   ├── forgejo-admin-recovery.md
│   └── forgejo-backup-restore.md
│
└── guides/                    # Wiederverwendbare Setup-Anleitungen
    ├── README.md              #   Format + Index
    └── authentik-oauth2-provider.md

Philosophie

Docs-as-Code: Dokumentation lebt neben dem Code, im selben Git-Repo, mit derselben Change-History. Keine separaten Wikis (driften), keine Confluence (teuer, closed), keine Notion (lock-in).

Mermaid für Diagramme: Forgejo rendert Mermaid-Blöcke im Web-UI direkt. Beispiel:

graph LR
  Browser --> Nginx
  Nginx --> Directus
  Nginx --> Astro

Markdown für alles andere: Keine Word-Docs, keine PDFs (außer Anhänge). Alles in Plain-Text lesbar + commitbar + diffbar.

Was hierher gehört

Architektur-Beschreibungen, Topologie-Diagramme
ADRs (warum haben wir X gebaut wie wir es gebaut haben)
Runbooks (wie debuggt / repariert man konkret)
Guides (wie richtet man etwas Wiederkehrendes ein)
How-Tos für Team-Onboarding (später, wenn das Team wächst)

Was NICHT hierher gehört

Secrets / Credentials (niemals, Repo ist public!)
Kundendaten / personenbezogene Daten (DSGVO)
Marketing-Texte (gehört auf die Website)
Lange Design-Specs in Rohform (lieber als ADR destillieren)