Benjamin Weinlich 88c541c9ed docs(adr): mirror 6 ADRs from M7.1 into repo

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

2026-04-11 22:26:05 +02:00

2.7 KiB

Raw Blame History

ADR-0005: Volume-Mount auf `/data`, nicht `/var/lib/gitea`

Status: Accepted (Lesson Learned) Datum: 2026-04-11 Entscheider: Benjamin Weinlich Phase: M7.1 — Forgejo Deployment

Kontext

Beim initialen Deployment wurde das Docker-Volume forgejo-data fälschlich auf /var/lib/gitea im Container gemountet. Grund: ältere Gitea/Forgejo Docs nennen teilweise /var/lib/gitea als APP_INI-Directory, und das wirkte als "Datenverzeichnis".

Der Bug fiel auf, als das erste Backup nur 87 Bytes hatte (leeres tar) — weil das gemountete Volume leer war, während Forgejo seine Daten tatsächlich in /data im Container-Layer schrieb.

Entscheidung

Volume-Mount forgejo-data:/data, nicht /var/lib/gitea.

Was Forgejo tatsächlich wo speichert

Aus Forgejo Docker Image:

/data — Haupt-Datenverzeichnis für ALLES:
- /data/git/ — Git-Repositories
- /data/gitea/conf/app.ini — Config
- /data/gitea/avatars/ — User-Avatars
- /data/gitea/repo-avatars/ — Repo-Avatars
- /data/gitea/lfs/ — LFS-Objekte
- /data/gitea/attachments/ — Issue/PR-Anhänge
- /data/gitea/packages/ — Package Registry
- /data/gitea/actions_log/ — CI-Logs
- /data/gitea/actions_artifacts/ — CI-Artefakte
- /data/gitea/ssh/ — Forgejo SSH Host Keys (gitea.rsa etc.)
/var/lib/gitea — existiert nicht im Forgejo-Image

Die FORGEJO__storage__* ENV-Variablen erwarten relative Pfade unter /data/gitea/.

Konsequenzen

Mount korrigiert

volumes:
  - forgejo-data:/data          # KORREKT
  # - forgejo-data:/var/lib/gitea  # FALSCH, Anfänger-Fehler

Runtime-Impact

Beim Fix musste der Forgejo-Container mit --force-recreate neu erzeugt werden. Die initial im Container-Layer gespeicherten Daten (SSH Host Keys, leere Storage-Ordner) gingen verloren und wurden beim neuen Start frisch initialisiert. Das war akzeptabel weil:

Postgres (eh_vehicles → forgejo-db) hatte alle User/OIDC-Daten → blieb erhalten
SSH Host Keys werden automatisch neu generiert
Keine Commits oder Repos existierten noch

Backup-Implikation

Das Backup-Script backup.sh tart jetzt korrekt das volle /data, nicht ein leeres Verzeichnis. Verifiziert: 12 KB statt 87 Bytes beim Test-Run.

Lesson Learned

Beim Setup eines neuen Docker-Stacks:

Nach docker compose up -d sofort checken: docker run --rm -v <volume_name>:/data:ro alpine ls -la /data/
Wenn das Volume leer aussieht, aber der Container offenbar Daten schreibt → Mount-Pfad falsch
Das offizielle Image-Documentation konsultieren, NICHT aus Memory copy-pasten

Agent.md — "Known Issues / Gotchas" Sektion erwähnt diesen Punkt als Warnung
runbook-backup-restore.md — Restore-Prozedur nutzt den korrekten Pfad

2.7 KiB Raw Blame History

ADR-0005: Volume-Mount auf /data, nicht /var/lib/gitea