Fix kiwix ZIM volume mount to work with a symlink
CI / check (push) Successful in 1m7s
CI / deploy (push) Successful in 14s

Bind-mounting data/kiwix/ (the directory) meant a symlink placed
inside it broke: the container has to resolve that symlink itself,
in its own filesystem, where the host path it points to doesn't
exist. Binding the exact data/kiwix/wikipedia.zim file path instead
resolves it on the host at mount time (plain mount(2) semantics), so
the real ZIM can live anywhere on the host without duplicating a
multi-GB file into this repo's data/ directory.
This commit is contained in:
randy committed 2026-09-09 14:01:39 +02:00
1 parent 24ac5931f8
commit c66ae8d2d0
2 files changed
+18 -2

No files matched your search

+10 -1
View File
@@ -60,9 +60,18 @@ services:
# service's own name), so maptool and kiwix stay independent containers. # service's own name), so maptool and kiwix stay independent containers.
# Keeps restarting (harmlessly) if data/kiwix/wikipedia.zim isn't there # Keeps restarting (harmlessly) if data/kiwix/wikipedia.zim isn't there
# yet — GET /api/kiwix just reports unavailable until it comes up. # yet — GET /api/kiwix just reports unavailable until it comes up.
#
# The volume binds the exact *file* path, not the data/kiwix/ directory —
# deliberately, so data/kiwix/wikipedia.zim can be a symlink to wherever
# the (large) real ZIM actually lives. A bind mount resolves a symlink at
# its *source* path once, at mount time (plain mount(2) semantics, same
# as Podman); a symlink sitting inside an already-mounted directory
# doesn't get that treatment — the container would have to resolve it
# itself, inside its own filesystem, where the host path it points to
# doesn't exist.
kiwix: kiwix:
image: ghcr.io/kiwix/kiwix-serve:latest image: ghcr.io/kiwix/kiwix-serve:latest
restart: unless-stopped restart: unless-stopped
command: ["--port=8080", "/data/wikipedia.zim"] command: ["--port=8080", "/data/wikipedia.zim"]
volumes: volumes:
- ./data/kiwix:/data - ./data/kiwix/wikipedia.zim:/data/wikipedia.zim
+8 -1
View File
@@ -89,7 +89,14 @@ self-contained archive, obtain one locally:
browsing images offline doesn't matter here. browsing images offline doesn't matter here.
* Download it to `data/kiwix/wikipedia.zim` (the exact filename * Download it to `data/kiwix/wikipedia.zim` (the exact filename
`docker-compose.yaml`'s `kiwix` service expects — rename after `docker-compose.yaml`'s `kiwix` service expects — rename after
downloading, Kiwix's own filenames are much more specific). downloading, Kiwix's own filenames are much more specific). A symlink
there works too (`ln -s /wherever/the-real-file.zim
data/kiwix/wikipedia.zim`), so the real file doesn't have to sit inside
this repo's checkout at all — the compose file's volume binds that exact
path, not the `data/kiwix/` directory, specifically so this resolves
correctly (a symlink *inside* an already-mounted directory wouldn't: the
container would have to resolve it itself, in its own filesystem, where
the host path it points to doesn't exist).
Once it's there, `docker compose up -d kiwix` (or a full restart) Once it's there, `docker compose up -d kiwix` (or a full restart)
picks it up — `GET /api/kiwix` reports `available: true` and the picks it up — `GET /api/kiwix` reports `available: true` and the