Benjamin Weinlich
88c541c9ed
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
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# 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
|
|
```yaml
|
|
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:**
|
|
1. Nach `docker compose up -d` sofort checken: `docker run --rm -v <volume_name>:/data:ro alpine ls -la /data/`
|
|
2. Wenn das Volume leer aussieht, aber der Container offenbar Daten schreibt → Mount-Pfad falsch
|
|
3. Das offizielle Image-Documentation konsultieren, NICHT aus Memory copy-pasten
|
|
|
|
## Related
|
|
- `Agent.md` — "Known Issues / Gotchas" Sektion erwähnt diesen Punkt als Warnung
|
|
- `runbook-backup-restore.md` — Restore-Prozedur nutzt den korrekten Pfad
|