DevvynandClaude Sonnet 5
ae32daf135
Two real bugs the review caught, both verified live against a real build on the Unraid host: 1. entrypoint.sh's chown fired on ANY ownership mismatch, not just a directory the daemon itself created root-owned. A host tree legitimately owned by some other account - an existing CODEMAN_CASES_PATH the README already allows pointing at a normal projects directory, or appdata under a different PUID/PGID convention than the one in use - got silently recursively re-owned with one log line to explain it. Now gated on the target actually being root-owned; anything else is a clean refusal naming the directory, its owner, and PUID/PGID. Start-Codeman.sh also now pre-creates CODEMAN_CASES_PATH the same way it already did CODEMAN_APPDATA_PATH, so Compose never has to materialise a missing bind source as root in the first place - the in-container chown becomes a safety net, not the primary mechanism. 2. The CLI-update chown (chown -R .../node_modules /usr/local/bin) handed the runtime account write access to entrypoint.sh itself (root-owned, executed as root on every container start with CHOWN/DAC_OVERRIDE/SETUID/SETGID) and the node binary - owning the DIRECTORY is enough to rename it aside and drop a replacement, which would let a compromised session arrange for its own script to run as root at the next restart. The four CLIs now install into a dedicated /opt/codeman-cli prefix (NPM_CONFIG_PREFIX); only that directory is chowned, /usr/local stays root-owned throughout. Smaller fixes from the same review: - Start-Codeman.sh's volume-refresh label filter wasn't project-scoped: a second Compose stack on the same host sharing the `codeman-dist` volume KEY could have had ITS volume deleted. Added a com.docker.compose.project filter, resolved from this stack's own `compose config --format json`. - Override-file precedence was backwards (checked .yaml before .yml; Compose actually prefers .yml) - swapped, plus a warning when both exist. - entrypoint.sh's setpriv now also passes --bounding-set -all, so CapBnd actually clears post-drop rather than just CapPrm/CapEff. - A comment on git_head_commit() noting it returns nothing for a worktree checkout (.git as a file), consistent with the script's existing -d .git convention elsewhere. - Doc drift: CLAUDE.md's Docker Compose section still described the old pre-created-and-chowned-by-hand model and didn't mention the root-then-drop entrypoint; the state-files list was missing docker-build-source.json; docs/docker-compose.md and docker/.env.example still had the pre-rename `Coding/codeman` path in one place each. Verified end to end against a real build on the Unraid host: a root-owned bind source is corrected as before; a directory owned by neither root nor PUID:PGID is refused rather than silently rewritten; a correctly-owned directory is left alone entirely; the four CLIs resolve via PATH from /opt/codeman-cli while /usr/local/bin, /usr/local/lib/node_modules and entrypoint.sh itself stay root-owned; CapBnd is fully cleared post-drop. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R9ZSTEenc8soSu9bTi8Xru
5.4 KiB
Docker Compose deployment
This configuration builds the Codeman application image locally from this checkout. It does not download or depend on a pre-built Codeman image.
For the Compose configuration, environment settings, storage migration, and macvlan networking examples, see the Docker deployment guide.
The image includes Claude Code, Codex, Gemini CLI, and OpenCode. Authenticate a CLI from its Codeman session; credentials are never baked into the image.
Prerequisites
- Docker Engine or Docker Desktop with Docker Compose v2
- A reachable Docker daemon
The application container mounts the Docker daemon socket so Codeman can create and manage its isolated Docker cases. Treat anyone who can administer this Compose project as having Docker-host-equivalent access.
Start
Copy the environment template, set a strong password, and confirm CODEMAN_APPDATA_PATH. The example maps /mnt/user/appdata/codeman on the host to /home/${CODEMAN_RUNTIME_USER} in the container, preserving Codeman state and CLI credentials outside Docker-managed volumes.
cp docker/.env.example docker/.env
On PowerShell, use the following command instead.
Copy-Item docker/.env.example docker/.env
On Linux, run the stack with the start script. It determines PUID and PGID from the owner of CODEMAN_APPDATA_PATH, and DOCKER_SOCKET_GID from the configured Docker socket, before invoking Compose. A root-owned application-data directory is rejected so the runtime account cannot become UID 0.
bash docker/Start-Codeman.sh
On other platforms, run Compose directly. PUID and PGID default to 1000:1000; set them in docker/.env when the application-data directory has a different owner.
docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -d
Open http://localhost:3000 and sign in with the username and password from docker/.env.
Operations
The local image is tagged codeman:local by default. Change CODEMAN_IMAGE in docker/.env if a different local tag suits your environment.
docker compose --env-file docker/.env -f docker/docker-compose.yaml logs -f codeman
bash docker/Start-Codeman.sh
docker compose --env-file docker/.env -f docker/docker-compose.yaml down
CODEMAN_APPDATA_PATH holds Codeman state and survives container recreation. Remove that host directory only when deliberately resetting the installation.
CODEMAN_CASES_PATH must be an absolute path on the Docker host. Compose mounts it at the same path inside Codeman, so the host daemon can bind the managed workspace into isolated Docker cases. Do not set it to /home/${CODEMAN_RUNTIME_USER}/codeman-cases.
Compose passes CODEMAN_APPDATA_PATH into Codeman as CODEMAN_DOCKER_HOST_HOME. Codeman uses that value to translate generated Docker seed, credential and hook-secret bind sources from the container's home path into paths visible to the host Docker daemon.
If docker info reports SwapLimit=false, set CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1. Isolated cases retain their configured memory limit. Codeman omits the unsupported swap-limit option and filters only the daemon's exact swap-capability warning while retaining every other Docker create error.
If that directory was created by an earlier root-running image, change its ownership to the configured PUID:PGID before starting this version. This preserves existing CLI credentials and session state while allowing the unprivileged runtime account to use them.
Updating
Codeman updates itself from App Settings → Updates, as it does on a bare host. The checkout mounted at /opt/codeman is the same directory Compose builds from, so the update's git checkout and rebuild land on the host and survive container recreation; the restart is the server exiting, which restart: unless-stopped turns into a relaunch on the new build.
That applies application code only. A release that changes docker/server.Dockerfile, docker/docker-compose.yaml, or adds a key to docker/.env.example needs the image rebuilt or the container recreated, which a container cannot do to itself. The updater detects each case and refuses with a message naming what changed; run docker/Start-Codeman.sh on the host to apply those.
CODEMAN_REPO_PATH overrides which checkout is mounted. It defaults to the compose project's parent directory, so it normally needs no setting. Point it at a directory that is not a git checkout and in-app updates are reported as unavailable.
Full detail, including the fingerprint baseline and the troubleshooting table: docker-self-update.md.
Docker cases
The default socket path is /var/run/docker.sock, which works with a standard Linux Docker Engine. The Bash start script detects its numeric group ID. When running Compose directly, set DOCKER_SOCKET_GID, for example using stat -c '%g' /var/run/docker.sock, so the unprivileged CODEMAN_RUNTIME_USER account can create Docker cases. Docker Desktop users should set DOCKER_SOCKET in docker/.env only when their Docker installation exposes a different compatible socket path.
Codeman Docker cases are sibling containers on the host daemon, not children of the application container. The Compose configuration handles their workspace bind mount through CODEMAN_CASES_PATH; the /home/${CODEMAN_RUNTIME_USER} application-data mapping is for Codeman state and ordinary in-container sessions, not sibling-case workspaces.