electric-horses-infra/stacks/forgejo/Agent.md

# 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:
   ```sql
   UPDATE "user" SET avatar = '', use_custom_avatar = false
   WHERE lower_name = '<new-user>';
   ```

## Ops-Kommandos
```bash
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`](../../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/`](../../docs/adr/) (gespiegelt in M7.3)