Richter-und-Zech/electric-horses-infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electric-horses-infra/stacks/forgejo/Agent.md
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

3 KiB
Raw Permalink Blame History

Agent Briefing — Forgejo Stack

Du arbeitest am Forgejo-Git-Hosting. Lies erst ../../Agent.md am Repo-Root für globale Konventionen.

Live auf

  • URL: https://code.sdda.eu
  • SSH: ssh://git@code.sdda.eu:222/<user>/<repo>.git
  • Server: ai-apps (Hetzner cx22, 10.0.0.8)
  • Pfad auf Server: /opt/ai-apps/forgejo/
  • Live seit: 2026-04-11
  • Version: Forgejo 10 (codeberg.org/forgejo/forgejo:10)

Authentifizierung

  • Primär: Nativer OIDC via Authentik (nicht ForwardAuth)
  • Application in Authentik: forgejo auf welcome.sdda.eu
  • Zugangskontrolle: Gruppen-Policy forgejo-users erforderlich
  • Launch-URL: https://code.sdda.eu/user/oauth2/authentik (für Silent SSO aus Authentik-Dashboard)
  • Fallback: lokaler admin-local User mit prohibit_login=true (Emergency)
  • Siehe ADR-0003 (OIDC statt ForwardAuth), ADR-0006 (Silent-SSO-Launch-URL)

Kritische Gotchas

  1. Volume-Mount auf /data, NICHT /var/lib/gitea. Forgejo schreibt alles nach /data. Siehe ADR-0005.
  2. SSH-Port-Kollision: Forgejo-Image hat system-sshd auf 22, deshalb Forgejos eigener Server auf Container-Port 2222 → Host-Port 222.
  3. OIDC-Config lebt in der Postgres-DB (Tabelle login_source), NICHT in app.ini. Zum Ändern: docker exec -u git forgejo sh -c 'cd / && forgejo admin auth update-oauth --id 1 ...'
  4. forgejo admin CLI braucht -u git und cd /: docker exec -u git forgejo sh -c 'cd / && forgejo admin user list'
  5. User-Promotion zum Admin via SQL am saubersten: UPDATE "user" SET is_admin = true WHERE lower_name = 'NAME';
  6. Neuer OIDC-User → broken Avatar: Authentik liefert das Avatar als data:image/svg+xml;base64,... Claim, Forgejo kann das nicht speichern → drawImage crasht auf Activity-Seite. Siehe ADR-0007. Fix nach jedem neuen First-Login: 
    UPDATE "user" SET avatar = '', use_custom_avatar = false
WHERE lower_name = '<new-user>';

Ops-Kommandos

ssh ai-apps
cd /opt/ai-apps/forgejo

# Status
docker compose ps
docker logs forgejo --tail 50

# Restart
docker compose restart forgejo

# Update (Major-Version manuell, Tag auf :10 gepinnt)
docker compose pull
docker compose up -d

# Backup manuell
bash backup.sh

# User-Verwaltung
docker exec -u git forgejo sh -c 'cd / && forgejo admin user list'
docker exec forgejo-db psql -U forgejo -d forgejo \
  -c "UPDATE \"user\" SET is_admin = true WHERE lower_name = 'NAME';"

Backup

  • Script: backup.sh in diesem Ordner (spiegelt /opt/ai-apps/forgejo/backup.sh)
  • Cron: 0 3 * * * auf ai-apps → /opt/backups/forgejo/
  • Retention: 14 Tage
  • Format: forgejo-db-<ts>.sql.gz + forgejo-data-<ts>.tar.gz
  • Offsite: noch nicht (Tier 2 via rclone → Nextcloud geplant M7.5)
  • Restore-Prozedur: siehe ../../docs/runbooks/forgejo-backup-restore.md

Related

  • ../../Agent.md — Repo-weites Briefing
  • ../../docs/architecture/ai-apps-stacks.md — Server-Kontext
  • ADRs 0001-0006 in ../../docs/adr/ (gespiegelt in M7.3)