From fa2fbec06c963f32a342ed667f19bf4ff3e23717 Mon Sep 17 00:00:00 2001 From: Kyle Galloway Date: Sat, 1 Aug 2026 21:09:45 -0300 Subject: [PATCH] deploy: make the build context overridable for Compose Manager MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit deploy/README.md documents an Unraid deployment, but the stack cannot actually be deployed that way. Compose Manager does not run a stack from a checkout — it requires the compose file to live in its own projects//docker-compose.yml. The relative `context: ..` then resolves to the projects directory rather than the repo root, so `docker compose up -d` fails to build, and the failure gives no clue that the build context is the problem. Found the hard way on a box where refrain was already running: the image existed from an earlier build, so nothing looked wrong until the image cache was about to be wiped, at which point the stack would simply not have come back. `context: ${REFRAIN_SRC:-..}` keeps the documented `docker compose up -d --build` from deploy/ working exactly as before — verified with `docker compose config`, which still resolves the context to the repo root when REFRAIN_SRC is unset — while letting a copied compose file point at the real checkout. Same pattern the subkb stack already uses. Also promotes the Unraid note in deploy/README.md to its own section with the caveat spelled out, and documents REFRAIN_SRC in .env.example as the opt-in it is. Co-Authored-By: Claude Opus 5 --- deploy/.env.example | 5 +++++ deploy/README.md | 19 ++++++++++++++++++- deploy/docker-compose.yaml | 7 ++++++- 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/deploy/.env.example b/deploy/.env.example index c72d9fa..ac19f9d 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -6,3 +6,8 @@ REFRAIN_IPV4=REPLACE-with-a-free-lan-ip # Host path for the memory root — a git repo of markdown, the only # irreplaceable data in this stack. Back it up. REFRAIN_DATA=REPLACE-with-a-host-path + +# Only needed when this compose file has been copied away from the repo, +# so the default `context: ..` no longer points at the repo root — see +# "Unraid / Compose Manager" in README.md. Leave unset otherwise. +#REFRAIN_SRC=/path/to/refrain/checkout diff --git a/deploy/README.md b/deploy/README.md index 436318d..ff4cfa0 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -21,7 +21,24 @@ The reference compose file assumes a pre-existing macvlan network named IP. If that isn't your pattern, replace the `networks` block with a bridge network and publish port 8092. -On Unraid, add these labels to the service for a WebUI link and shell: +## Unraid / Compose Manager + +Compose Manager does not run the stack from a checkout — it requires the +compose file to live in its own `projects//docker-compose.yml`. The +default `context: ..` then resolves to the projects directory instead of +the repo root, and `docker compose up -d` fails to build with no obvious +clue why. Point `REFRAIN_SRC` at the checkout so the build context stays +correct wherever the compose file was pasted: + +``` +REFRAIN_SRC=/mnt/user/appdata/refrain/src +``` + +The checkout has to be reachable from the Docker host, so keep it on a +share rather than inside the compose project directory (Unraid's flash +device is FAT-formatted and a poor place for source). + +Add these labels to the service for a WebUI link and shell: ```yaml labels: diff --git a/deploy/docker-compose.yaml b/deploy/docker-compose.yaml index 042e2a3..1e53def 100644 --- a/deploy/docker-compose.yaml +++ b/deploy/docker-compose.yaml @@ -19,7 +19,12 @@ services: refrain: build: - context: .. + # Defaults to the repo root, so `docker compose up -d --build` from + # this directory just works. Override REFRAIN_SRC when the compose + # file is copied somewhere else and `..` no longer means the repo — + # notably Unraid's Compose Manager, which requires the file to live + # in its own projects// directory (see README). + context: ${REFRAIN_SRC:-..} dockerfile: deploy/Dockerfile container_name: refrain restart: unless-stopped