60 lines
2.7 KiB
Markdown
60 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
|