fix(docker): bind-mount ownership, Compose override discovery, and the default runtime account

[opticon454]

Problem

Two independent bugs in the Docker deployment.

1. The container crash-loops whenever a bind source does not already exist

docker-compose.yaml binds CODEMAN_APPDATA_PATH and CODEMAN_CASES_PATH from the host. When either path does not exist yet - a first run, a cleared application-data directory, a restored backup - the Docker daemon creates it owned by root:root. The server runs unprivileged as CODEMAN_RUNTIME_USER, so it cannot create its own state directory, and the container restarts forever on:

Failed to start web server: EACCES: permission denied, mkdir '/home/<user>/.codeman'

Start-Codeman.sh works around this by preparing the directory on the host first, so the failure only appears when Compose is run directly - which docker/README.md documents as a supported path.

2. Start-Codeman.sh silently discards docker-compose.override.yml

The script passes -f "$compose_file", and naming a Compose file explicitly disables Compose's automatic discovery of the override file. Any customisation placed in the conventional override file is dropped without warning, and the only way to notice is to inspect the running container.

3. The default runtime account is named opencode

CODEMAN_RUNTIME_USER defaults to opencode, which no longer matches the project and is confusing in a deployment whose every other identifier is codeman. The example application-data path also carries a Coding/ component that means nothing outside the original author's host.

Changes

• docker/entrypoint.sh (new) - starts as root, corrects the ownership of both bind mounts, then drops to PUID:PGID with setpriv.
• docker/server.Dockerfile - the USER instruction is replaced by that entrypoint; CMD is unchanged. PUID/PGID are also exported as runtime ENV defaults so the image behaves correctly when run without Compose, rather than depending on build args alone.
• docker/docker-compose.yaml - adds back only the four capabilities the chown and the privilege drop require, so cap_drop: ALL continues to remove everything else.
• docker/Start-Codeman.sh - collects the -f arguments into an array, appends the override file when present, and reuses that array for the final launch so the two cannot drift apart again. Both .yml and .yaml are checked, in Compose's own precedence order, and the chosen file is reported on startup.
• docker/.env.example, docker/server.Dockerfile - rename the default runtime account to codeman, in both the example file and the ARG that mirrors it, and correct the comment that referred to /home/opencode/codeman-cases. Simplify the example paths to /mnt/user/appdata/codeman and its codeman-cases child. The npm package opencode-ai and the references to the OpenCode CLI are deliberately untouched, as those name a different tool.
• docker/README.md, .gitignore - document the override file, including the two things that are easy to get wrong (it is ignored when -f is passed without naming it, and it cannot remove a key such as ports, which Compose concatenates), and ignore it in Git.

4. CODEMAN_ALLOWED_HOSTS is documented nowhere in the Docker deployment docs

The variable is a real, working application setting (the Host-header allowlist in network-auth-policy.ts), but nothing in docker/README.md mentions it, and docker-compose.yaml does not forward it from .env into the container - Compose only passes through variables explicitly listed under environment:. A reverse-proxied deployment fails with 403 Forbidden: host not allowed with no pointer back to the fix.

5. Build-artefact volumes go stale after an externally-triggered rebuild

codeman-node-modules and codeman-dist (docker-compose.yaml) are seeded from the image only while empty. The in-app self-updater never hits this - it rebuilds INSIDE the running container, into the very volume already in use - but a docker compose build triggered from outside it (Start-Codeman.sh, after a manual git pull) does: the container comes back up looking unchanged, serving stale compiled routes against current source. This bit a real deployment during this work: a source fix landed, docker compose build && up ran cleanly, and the old behaviour persisted until the volume was cleared by hand.

Compatibility

Two guards keep existing deployments working:

• A container started with an explicit user: is left alone entirely. The entrypoint execs straight through, with no elevation and no chown.

• A chown that fails is a warning, not an error. Bind mounts backed by NFS, CIFS or a rootless daemon can refuse chown while remaining perfectly writable, and those deployments must keep starting.

• docker/README.md - documents CODEMAN_ALLOWED_HOSTS, why docker-compose.yaml does not forward it, and the override needed to do so, using the Local customisation mechanism already described earlier in the same file.

• docker/Start-Codeman.sh, scripts/self-update.sh, docs/docker-self-update.md - Start-Codeman.sh compares the checkout's HEAD commit and package-lock.json hash against a recorded marker (docker-build-source.json) and clears just the affected volume(s) before its own --build when either moved. The in-place self-update path writes that same marker after a successful build, so the two mechanisms agree on what the volumes currently reflect - without it, the next plain Start-Codeman.sh run would see the HEAD self-update just checked out, not recognise it as already accounted for, and wipe the volumes self-update just correctly rebuilt right back to the older baked image.

Testing

Verified against a full rebuild on Docker 29 / Compose v5.5, with PUID=99 and PGID=100:

Case	Result
Application-data directory deleted entirely	Self-heals, logs corrected ownership of ... to 99:100, container healthy
Directory forced to root:root	Self-heals, ownership restored
Already-correct tree	No chown performed, verified on a fresh container so no stale log could mask it
Server process identity	Uid 99/99/99/99, Gid 100/100/100/100, Groups: 281 - the socket group is kept and root's group is dropped
Docker socket as the app user	Usable, Docker cases work
Container started with -u 1000:1000	uid=1000, straight exec, no elevation attempted
Read-only, unchownable mount	Warns and continues, ends as uid=99 - does not abort
Start-Codeman.sh with an override present	Both -f flags passed
Start-Codeman.sh with no override	Only the base -f flag, no stray argument
Volume staleness (issue 5)	Ran Start-Codeman.sh for real against the live Unraid deployment: correctly detected the source change on first run with no prior marker, resolved the real prefixed volume names via docker volume ls --filter label=com.docker.compose.volume=..., cleared both volumes, rebuilt, and came back up healthy; marker file confirmed written with the real HEAD commit and lockfile hash afterward

The five commits are independent; happy to split them into separate PRs if you would prefer that.

🤖 Generated with Claude Code

---

Folded in from #384 (opened, then closed as superseded by this consolidation once it turned out this identity has only read access to this repo and cannot merge PRs here directly).

[opticon454]

GitHub's conflict flag traced down to two real conflicts, both caused by #373 (66eb01ba, merged after this PR's base) touching the same two files in overlapping places. The other two files this PR shares with #373 (docker/.env.example, docker/server.Dockerfile) and one more (docker/docker-compose.yaml) changed on both sides too but auto-merge cleanly — no markers there.

docker/README.md

Both PRs append a new ## section at the same spot, right after the ownership-fix paragraph:

• master (feat(docker): restore in-app self-update in the Compose dep #373) added "## Updating", documenting the in-app self-updater
• this PR adds "## Local customisation", documenting docker-compose.override.yml

They're unrelated sections that happen to land at the same insertion point — additive, not competing. Either order works; keep both.

docker/Start-Codeman.sh

Both touch the final docker compose ... up --build -d line:

• master (feat(docker): restore in-app self-update in the Compose dep #373) resolves repo_path/CODEMAN_REPO_PATH beforehand and runs:

  exec docker compose --env-file "$env_file" -f "$compose_file" up --build -d

• this PR builds compose_command earlier (bare -f "$compose_file" plus any discovered override file) and runs:

  exec "${compose_command[@]}" up --build -d

This one needs an actual merge of intent, not just picking a side: keep the repo_path resolution from master, but launch via "${compose_command[@]}" so the override file(s) this PR discovers still get threaded through — losing that would silently make the override support this PR adds dead on the self-update path.

Happy to help if useful, but since I don't have push access to bugfix-docker-user-perms a rebase onto current master is the actual fix here.

[opticon454]

Rebased this branch onto current master and resolved both conflicts:

• docker/README.md — kept both new sections (master's "Updating", this branch's "Local customisation") one after the other.
• docker/Start-Codeman.sh — kept master's repo_path resolution and self-update fingerprint block, but changed the final line to exec "${compose_command[@]}" up --build -d so the override-file discovery this branch adds still applies on that path.

CI is green on the rebased head and GitHub now reports this as cleanly mergeable.

🤖 Generated with Claude Code

[Ark0N]

Thanks for this, and for rebasing it yourself when #373 landed underneath you. The entrypoint measurement is right: a Compose long-form bind creates a missing host source root-owned, and asking every user to pre-create and chown it by hand is a bad first-run experience. Six commits is a lot to land at once though, and two of them need to change before I can take any of it.

1. The entrypoint chown fires on any owner mismatch, not just the root-owned directory the daemon created (docker/entrypoint.sh:28). The gate is stat -c '%u:%g' == PUID:PGID, so a directory owned by any other account gets recursively re-owned. I reproduced it with the compose caps: a host tree owned by 1000:1000 mounted as CODEMAN_CASES_PATH with PUID=1234 came back 1234:4321 down to the leaf files, with a single log line to say so. Two ordinary deployments hit this on their first start:

• docker compose up run directly with the default PUID=1000 against a 99:100 Unraid appdata dir. The README tells people to set PUID in that case, and before this PR forgetting it failed loudly with EACCES. Now it silently rewrites the credentials tree to 1000:1000.
• CODEMAN_CASES_PATH pointed at an existing projects directory owned by the host account, which the README explicitly allows ("unless you deliberately store workspaces elsewhere"), while appdata follows the 99:100 convention.

The case your PR describes (first run, cleared dir, restored backup) is a directory the daemon created as root:root. Please gate the chown on uid == 0 and turn any other mismatch into a clear error naming PUID, PGID and the path, which is exactly how Start-Codeman.sh already treats a root-owned appdata dir. Worth noting separately: Start-Codeman.sh never pre-creates or checks CODEMAN_CASES_PATH the way it does appdata. Adding that host-side would mirror the existing design and mean the script path never needs the in-container chown at all.

2. chown -R of /usr/local/bin hands the root-executed entrypoint and the node binary to the unprivileged runtime account (docker/server.Dockerfile:133). That directory holds node (a 124 MB binary, now writable by that user), npm/npx as symlinks into the also-chowned node_modules, the docker CLI copied at line 66, and after line 158 entrypoint.sh itself. The script stays root-owned, but owning the directory is enough to rename it away and drop a replacement, and line 161 runs that path as root with CHOWN/DAC_OVERRIDE/SETUID/SETGID on every container start. The writable layer survives exactly the restart the self-updater performs, so a session running as the runtime user could arrange for its own script to run as root at the next restart, which undoes the "the server itself never runs privileged" guarantee this PR is adding. In practice that user already holds the Docker socket, which is host-root-equivalent by design, so the marginal escalation is bounded, but chowning the system bin dir is the wrong shape for "let sessions update their CLIs". Install the four global CLIs into a dedicated prefix instead:

ENV NPM_CONFIG_PREFIX=/opt/codeman-cli
ENV PATH=/opt/codeman-cli/bin:$PATH
# npm install -g ... then:
RUN chown -R "${PUID}:${PGID}" /opt/codeman-cli

and leave /usr/local/bin and /usr/local/lib/node_modules root-owned. Commit 49c6353a is also unrelated to the PR title and is the cleanest one to split out.

Smaller, and I can apply these at merge time if you would rather not:

• docker/Start-Codeman.sh:196: docker volume ls -q --filter label=com.docker.compose.volume=codeman-dist | head -n1 matches every Compose project on the host that declares a volume with that key, because the label is the key and not the project-qualified name. A beta stack started with -p alongside prod shares it and head -n1 picks whichever the daemon lists first, so the refresh can delete the other project's volume. Add --filter label=com.docker.compose.project=<name>, or drop the lookup and run down --volumes when either input moved. Both volumes re-seed from the image by a plain copy, and docs/docker-self-update.md already calls down -v the supported reset.
• docker/Start-Codeman.sh:21: the override-file order is the reverse of Compose's, and the comment says it matches. Measured on Compose v5.5.0 with both files present: Compose warns and uses docker-compose.override.yml, the script picks .yaml first and says nothing. Swap the candidates, and consider warning when both exist.
• docker/entrypoint.sh:48: after the drop the process shows CapPrm/CapEff 0 but CapBnd 0xc3. With no-new-privileges that is moot, but setpriv --bounding-set -all is free and makes the dropped state match the intent.
• Docs that need to move with the code: CLAUDE.md:214 still says a missing bind source "has to be pre-created and chowned", which the entrypoint now handles, and that paragraph does not mention the container starting as root with four capabilities and dropping via setpriv. CLAUDE.md:379 lists docker-env-applied.json but not the new docker-build-source.json. The rename missed docs/docker-compose.md:18 and docker/.env.example:28, so the two example paths now disagree with each other.
• git_head_commit() is a pure function and three fixtures would pin it (detached HEAD, symbolic ref, packed-refs after gc). I ran those by hand and they resolve correctly. A worktree checkout, where .git is a file containing gitdir:, returns nothing and silently disables the dist refresh, which is consistent with the script's existing -d .git convention but worth a comment.

You offered to split this up, and I think that is the fastest path: the ownership fix, override discovery, the volume refresh and the rename as one PR, with the CLI-chown commit either dropped or reworked to the dedicated prefix. The release note will need a line telling Compose users to run Start-Codeman.sh for this release, which I will write.

[opticon454]

Thanks for the thorough review — pushed a fix addressing all of it (63563def).

1. entrypoint.sh's chown gate. Now gated on uid == 0; anything else refuses with a clear error naming the directory, its actual owner, and PUID/PGID, rather than silently re-owning it. Also added CODEMAN_CASES_PATH pre-creation to Start-Codeman.sh mirroring the existing CODEMAN_APPDATA_PATH handling, per your suggestion — Compose should now never have to materialise either bind source as root in the first place.

2. The CLI-update chown. Reworked to the dedicated-prefix approach exactly as you sketched it: NPM_CONFIG_PREFIX=/opt/codeman-cli, only that directory gets chowned, /usr/local/bin//usr/local/lib/node_modules (and entrypoint.sh itself) stay root-owned throughout.

Smaller ones: volume-refresh lookup is now project-scoped (com.docker.compose.project filter), override-file precedence swapped to .yml-first with a warning when both exist, setpriv --bounding-set -all added, a comment on git_head_commit()'s worktree limitation, and the four doc-drift spots (CLAUDE.md x2, docs/docker-compose.md, docker/.env.example).

Verified all of it against a real build on my own deployment's Docker host rather than just by inspection:

Case	Result
Root-owned bind source	Auto-corrected as before, entrypoint: corrected ownership of /home/codeman to 99:100
Directory owned by neither root nor PUID:PGID (simulated 5000:5000)	Refused cleanly, exit 1, ownership left untouched — this is the exact case you reproduced
Correctly-owned directory	No chown attempted, straight through
CLI resolution	which claude/codex/gemini/opencode all resolve to /opt/codeman-cli/bin/* via PATH
Ownership boundary	/opt/codeman-cli is codeman:users (99:100); /usr/local/bin, /usr/local/lib/node_modules, and entrypoint.sh itself are all still root:root
Capabilities post-drop	CapBnd is now 0000000000000000

🤖 Generated with Claude Code

[opticon454]

One gap in 63563def's fix, caught by a user on my own deployment who runs the compose file directly (Unraid's Compose Manager) rather than through Start-Codeman.sh: /opt/codeman-cli was only ever chowned to PUID:PGID at image build time (from the build args), never re-verified at container start the way HOME/CODEMAN_CASES_PATH are. Anyone changing PUID/PGID in .env and restarting without a rebuild — which Start-Codeman.sh always does via --build, but a plain docker compose up/restart does not — would end up running as the new UID while the CLI directory stayed owned by the old, baked-in one, silently breaking the self-update-a-CLI-in-place fix that directory exists for.

Fixed in d7f6b843: entrypoint.sh now re-asserts /opt/codeman-cli's ownership on every start, unconditionally (unlike the host bind mounts, this is pure image content with no "someone else's directory" ambiguity to be careful about). Verified live: built with PUID=99/PGID=100, ran with PUID=1234/PGID=4321 and no rebuild, confirmed the directory ends up 1234:4321-owned and genuinely writable.

🤖 Generated with Claude Code