Benjamin Weinlich
09925f7eda
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 |
||
|---|---|---|
| .. | ||
| 0001-forgejo-vs-gitea.md | ||
| 0002-ai-apps-placement.md | ||
| 0003-native-oidc-not-forwardauth.md | ||
| 0004-subdomain-code-sdda-eu.md | ||
| 0005-volume-mount-data-not-var-lib.md | ||
| 0006-silent-sso-launch-url.md | ||
| 0007-oidc-avatar-data-url-gotcha.md | ||
| README.md | ||
Architecture Decision Records
Dieses Verzeichnis enthält ADRs — kurze Markdown-Dokumente die einzelne Architektur-Entscheidungen festhalten. Das Pattern kommt von Michael Nygard und ist gemeinsamer Standard in vielen Open-Source-Projekten.
Warum ADRs?
- Warum, nicht Wie: Der Code ändert sich. Die Intention soll bleiben. Eine ADR erklärt warum etwas so gebaut wurde — in einem halben Jahr weiß niemand mehr sonst.
- Referenz für AI-Sessions: Wenn die AI morgen eine Änderung vorschlägt, die eine bestehende Entscheidung umkehrt, soll sie das bewusst tun und neue ADR schreiben, nicht versehentlich.
- Audit-Trail: Jede ADR hat Status, Datum und Entscheider. Das ist Compliance-ready.
Format
Jede ADR folgt grob diesem Schema:
# ADR-NNNN: <Titel>
Status: Proposed | Accepted | Superseded by ADR-NNNN | Deprecated
Datum: YYYY-MM-DD
Entscheider: <Name>
Phase: <OpenProject Phase oder Sprint>
## Kontext
Was war das Problem? Welche Optionen standen zur Wahl?
## Entscheidung
Was wurde gewählt?
## Begründung
Warum genau diese Option? Welche Prinzipien waren leitend?
## Konsequenzen
- **Positiv:** Was gewinnen wir?
- **Negativ/Trade-off:** Was geben wir auf?
## Alternativen
Was wurde verworfen und warum?
Nummerierung
Fortlaufend NNNN beginnend bei 0001. Niemals alte ADRs ändern — superseden via neue ADR mit Verweis. Die Historie ist die Wahrheit.
Aktuelle ADRs (alle aus M7.1 — Forgejo Deployment)
| # | Titel | Status |
|---|---|---|
| 0001 | Forgejo statt Gitea | Accepted |
| 0002 | Forgejo auf ai-apps, nicht separate VM | Accepted |
| 0003 | Natives OIDC statt ForwardAuth | Accepted |
| 0004 | Subdomain code.sdda.eu | Accepted |
| 0005 | Volume-Mount auf /data | Accepted (Lesson Learned) |
| 0006 | Silent SSO via OAuth2-Initiate-Launch-URL | Accepted (Lesson Learned) |
| 0007 | OIDC-Avatar als data-URL bricht Canvas-Renderer | Accepted (Lesson Learned) |
Vorlage für neue ADRs
Copy-and-paste Startpunkt:
# ADR-NNNN: <Titel>
**Status:** Proposed
**Datum:** YYYY-MM-DD
**Entscheider:** <Name>
**Phase:** <OpenProject>
## Kontext
## Entscheidung
## Begründung
## Konsequenzen
### Positiv
### Negativ / Trade-off
## Alternativen
## Referenzen