fix: track volume directories via .gitkeep for fresh git-based deploys #5

Merged

csaeum merged 1 commit from fix/volume-dirs-fresh-deploy into main

2026-08-05 20:08:07 +00:00

csaeum commented

2026-08-05 20:04:38 +00:00

Owner

Zusammenfassung

Root Cause: ein frischer git clone/pull (z. B. via DockHand) bringt nur getrackte Dateien mit; volumes/ war komplett .gitignoret, die von driver_opts.device referenzierten Zielverzeichnisse existierten also nach einem frischen Deploy gar nicht. Der local-Volume-Treiber (o: bind, type: none) legt fehlende Zielverzeichnisse nicht selbst an (getestet: docker compose up bricht mit no such file or directory ab) — das führte zum wiederholten Abbruch beim Deployen.
Fix: volumes/*/.gitkeep getrackt (Standard-Trick für leere Verzeichnisse in Git), .gitignore entsprechend angepasst — echte Laufzeitdaten bleiben weiterhin ignoriert.
Verifiziert: mariadb:11.4 initialisiert sauber, auch wenn nur eine .gitkeep-Datei im Datenverzeichnis liegt (der Entrypoint prüft auf das fehlende mysql-Systemdatenbank-Unterverzeichnis, nicht auf absolute Leere).
Zusätzlich: driver_opts.device von ${PWD} auf relative Pfade (.) umgestellt — Compose v2 löst das nachweislich relativ zur Compose-Datei auf, nicht zum Shell-cwd. ${PWD} löste bei einem Test mit -f <pfad> aus einem anderen Verzeichnis still den falschen Pfad auf; robuster für Deploy-Tools, die nicht zwingend ins Stack-Verzeichnis wechseln.
README.md korrigiert (behauptete bisher fälschlich automatisches Anlegen der Ordner).

Testplan

docker compose config -q fehlerfrei
docker run mariadb:11.4 mit .gitkeep im Datenverzeichnis initialisiert sauber
docker compose -f <fremder-pfad> config aus anderem cwd: . löst korrekt auf, ${PWD} nicht

## Zusammenfassung - **Root Cause:** ein frischer `git clone`/`pull` (z. B. via DockHand) bringt nur getrackte Dateien mit; `volumes/` war komplett `.gitignore`t, die von `driver_opts.device` referenzierten Zielverzeichnisse existierten also nach einem frischen Deploy gar nicht. Der `local`-Volume-Treiber (`o: bind, type: none`) legt fehlende Zielverzeichnisse **nicht** selbst an (getestet: `docker compose up` bricht mit `no such file or directory` ab) — das führte zum wiederholten Abbruch beim Deployen. - **Fix:** `volumes/*/.gitkeep` getrackt (Standard-Trick für leere Verzeichnisse in Git), `.gitignore` entsprechend angepasst — echte Laufzeitdaten bleiben weiterhin ignoriert. - **Verifiziert:** `mariadb:11.4` initialisiert sauber, auch wenn nur eine `.gitkeep`-Datei im Datenverzeichnis liegt (der Entrypoint prüft auf das fehlende `mysql`-Systemdatenbank-Unterverzeichnis, nicht auf absolute Leere). - **Zusätzlich:** `driver_opts.device` von `${PWD}` auf relative Pfade (`.`) umgestellt — Compose v2 löst das nachweislich relativ zur Compose-Datei auf, nicht zum Shell-`cwd`. `${PWD}` löste bei einem Test mit `-f <pfad>` aus einem anderen Verzeichnis still den falschen Pfad auf; robuster für Deploy-Tools, die nicht zwingend ins Stack-Verzeichnis wechseln. - `README.md` korrigiert (behauptete bisher fälschlich automatisches Anlegen der Ordner). ## Testplan - [x] `docker compose config -q` fehlerfrei - [x] `docker run mariadb:11.4` mit `.gitkeep` im Datenverzeichnis initialisiert sauber - [x] `docker compose -f <fremder-pfad> config` aus anderem `cwd`: `.` löst korrekt auf, `${PWD}` nicht

csaeum added 1 commit

2026-08-05 20:04:38 +00:00

fix: track volume directories via .gitkeep for fresh git-based deploys

CI – Validate & Release / validate (pull_request) Failing after 1s

Details

CI – Validate & Release / release (pull_request) Has been skipped

Details

67928bf508

A fresh git clone/pull (e.g. via DockHand) only brings tracked files;
volumes/ was fully gitignored, so the ./volumes/* target directories
referenced by driver_opts.device never existed on a fresh deploy. The
"local" volume driver (o:bind, type:none) does NOT create missing
device directories itself - verified: "docker compose up" fails with
"no such file or directory" for a non-existent absolute device path.
Fix: track volumes/*/.gitkeep (standard empty-dir-in-git trick),
.gitignore updated to un-ignore just the directories + .gitkeep while
keeping actual runtime data ignored.

Verified mariadb:11.4 initializes cleanly with only a .gitkeep file
present in the data directory (its entrypoint checks for the missing
"mysql" system database subdir, not literal directory emptiness).

Also switched driver_opts.device from ${PWD} to relative paths (.).
Verified Docker Compose v2 resolves relative device paths against the
compose file's own directory, not the invoking shell's cwd - tested
"docker compose -f <path> config" from a different cwd: ${PWD}
silently resolved to the wrong path, the relative form resolved
correctly regardless of where compose was invoked from. More robust
for deploy tools that may not cd into the stack directory first.

README.md corrected: it previously (incorrectly) claimed the volume
folders get created automatically at start.

csaeum merged commit 6b517df57a into main

2026-08-05 20:08:07 +00:00

csaeum deleted branch fix/volume-dirs-fresh-deploy

2026-08-05 20:08:07 +00:00

csaeum referenced this pull request from a commit

2026-08-05 20:08:09 +00:00

Merge pull request 'fix: track volume directories via .gitkeep for fresh git-based deploys' (#5) from fix/volume-dirs-fresh-deploy into main