From c66ae8d2d0ceabea2c2c0682a64aa52d2e1c8b59 Mon Sep 17 00:00:00 2001 From: Roman Priesol Date: Wed, 9 Sep 2026 14:01:39 +0200 Subject: [PATCH] Fix kiwix ZIM volume mount to work with a symlink 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. --- docker-compose.yaml | 11 ++++++++++- docs/development.adoc | 9 ++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docker-compose.yaml b/docker-compose.yaml index a1ede78..a1d0ee6 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -60,9 +60,18 @@ services: # service's own name), so maptool and kiwix stay independent containers. # Keeps restarting (harmlessly) if data/kiwix/wikipedia.zim isn't there # 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: image: ghcr.io/kiwix/kiwix-serve:latest restart: unless-stopped command: ["--port=8080", "/data/wikipedia.zim"] volumes: - - ./data/kiwix:/data + - ./data/kiwix/wikipedia.zim:/data/wikipedia.zim diff --git a/docs/development.adoc b/docs/development.adoc index 7dce4ac..72337f2 100644 --- a/docs/development.adoc +++ b/docs/development.adoc @@ -89,7 +89,14 @@ self-contained archive, obtain one locally: browsing images offline doesn't matter here. * Download it to `data/kiwix/wikipedia.zim` (the exact filename `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) picks it up — `GET /api/kiwix` reports `available: true` and the