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
Root Agent.md and stacks/forgejo/Agent.md had stale references to
"docs live in iCloud, will be mirrored in M7.3". Now M7.3 is done,
so the briefings point to docs/adr/ and docs/runbooks/ directly
with relative links that render as clickable in the Forgejo web UI.
The iCloud folder stays around for loose notes and credentials
that cannot go into a public repo, but the primary source of truth
for ADRs / runbooks / guides is now this repo.
Refs OP#1118
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
Adds the Architecture Decision Records that were written during the
Forgejo deployment (M7.1) as part of moving docs from the iCloud folder
into this versioned repository.
Includes:
- ADR-0001: Forgejo vs Gitea (non-profit stewardship)
- ADR-0002: ai-apps placement (no separate VM)
- ADR-0003: Native OIDC, not ForwardAuth
- ADR-0004: Subdomain code.sdda.eu
- ADR-0005: Volume mount on /data (lesson learned)
- ADR-0006: Silent SSO via OAuth2 launch URL (lesson learned)
Plus a docs/adr/README.md that explains the ADR format, lists the
current ADRs, and provides a template for future entries.
Refs OP#1118
Mirrors /opt/ai-apps/eh-search/ on the server, including the full
FastAPI app (intent routing, FTS+fuzzy+substring hybrid, multi-source
federation across vehicles + blog + brands + pages + static + tag
bridge), SQL schema (Postgres materialized view with german_unaccent
text search, pg_trgm for fuzzy), Dockerfile and compose.
Sanitized the hardcoded password in sql/01_init.sql — replaced with
REPLACE_ME_BEFORE_APPLYING placeholder since this repo is public.
The eh-search service binds only on the private network (10.0.0.8:8200)
and is reachable only via Pegasus nginx proxy at /api/search.
Refs OP#1094 OP#1105 OP#1112 OP#1116 OP#1117
First stack mirrored 1:1 from /opt/ai-apps/forgejo/ on the server.
Includes docker-compose.yml (forgejo + postgres 16), .env.example
template (NO real secrets), backup.sh (nightly pg_dump + tar), plus
Agent.md and README.md.
Known gotchas documented in Agent.md:
- Volume mount on /data not /var/lib/gitea
- SSH port 2222 in container (system sshd occupies 22)
- OIDC config lives in DB table login_source, not app.ini
Refs OP#1119
Captures the current state of all Docker stacks running on ai-apps
(Hetzner cx22, 10.0.0.8) as of 2026-04-11. Includes resource budget,
DNS records, Traefik integration pattern, and backup situation.
This is a point-in-time snapshot; update when new stacks are added.
Refs OP#1118
- README.md explains scope, conventions, what does / does not belong here
- Agent.md is the AI session briefing with workflow rules
- .gitignore blocks secrets, runtime data, and build artifacts
Refs OP#1119
