DevvynandClaude Opus 5
10876aa440
Compose 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. 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 already worked around this by preparing the directory on the host, so the failure only appears when Compose is run directly, which the README documents as a supported path. Add docker/entrypoint.sh, which starts as root, corrects the ownership of both bind mounts, then drops to PUID:PGID with setpriv. The Dockerfile's USER instruction is replaced by that entrypoint and CMD is unchanged. 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. Two guards keep existing deployments working: - A container started with an explicit `user:` is left alone. 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. PUID and PGID are also exported as runtime environment defaults so the image behaves correctly when run without Compose, rather than depending on build args alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Codeman Docker deployment
This folder contains the Compose configuration, server image Dockerfile, and environment template for a locally built Codeman server.
Start
From the repository root, create the runtime environment file and set the required values, especially CODEMAN_PASSWORD.
cp docker/.env.example docker/.env
bash docker/Start-Codeman.sh
On PowerShell, use the following command instead.
Copy-Item docker/.env.example docker/.env
docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -d
Every required value is defined and explained in .env.example. GEMINI_API_KEY is intentionally optional and may remain blank.
On Linux, Start-Codeman.sh stops with an error when required paths are missing. It creates the application-data directory when safe, detects its numeric owner as PUID:PGID, and detects DOCKER_SOCKET_GID from the configured Docker socket. It rejects a root-owned application-data directory because Codeman and its local CLI sessions must remain unprivileged.
Codeman, Claude, OpenCode, and other local sessions run as the unprivileged account named by CODEMAN_RUNTIME_USER, which defaults to opencode. When Compose is run directly, PUID and PGID default to 1000:1000; set them in .env when the application-data directory has a different owner. The Bash start script determines them automatically instead.
To retain Docker-case support without root when running Compose directly, set DOCKER_SOCKET_GID to the numeric group ID of the host socket. On a standard Linux Docker host, obtain it with stat -c '%g' /var/run/docker.sock. The Bash start script detects it automatically.
Updating
Use App Settings → Updates in the web UI. The checkout Compose builds from is
also mounted at /opt/codeman, so an update's git checkout and rebuild persist
on the host, and the server exiting is what restarts the container onto the new
build.
Releases that change server.Dockerfile, docker-compose.yaml, or add a key to
.env.example cannot be applied that way — the updater detects them, names what
changed, and asks you to run Start-Codeman.sh here on the host instead. Details:
../docs/docker-self-update.md.
Application data storage
The default configuration uses a host-folder bind mount:
volumes:
- type: bind
source: ${CODEMAN_APPDATA_PATH}
target: /home/${CODEMAN_RUNTIME_USER}
Set CODEMAN_APPDATA_PATH in .env to a directory that the Docker daemon can access. The example value is /mnt/user/appdata/Coding/codeman.
CODEMAN_CASES_PATH is the separate host directory for managed case workspaces. It is mounted into Codeman at the same absolute path, allowing the host Docker daemon to bind it into an isolated case container. Set it to a child directory of CODEMAN_APPDATA_PATH unless you deliberately store workspaces elsewhere.
Compose also exposes CODEMAN_APPDATA_PATH to Codeman as CODEMAN_DOCKER_HOST_HOME. This lets Docker case seed files, CLI credentials and the hook secret be mounted using paths that exist in the host daemon's filesystem. Direct host installations do not set this variable and retain their existing behaviour.
Set CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1 when docker info reports SwapLimit=false. Codeman continues to apply the configured case memory limit, omits Docker's unsupported --memory-swap option, and filters only the daemon's exact swap-capability warning. Every other Docker create error and its exit status remain visible.
For an existing installation created by a root-running image, change ownership of the application-data directory before upgrading so the configured PUID and PGID can read the saved credentials and state:
chown -R 99:100 /mnt/user/appdata/Coding/codeman
Replace 99:100 and the path with the values from your .env file.
Do not replace this bind mount with a Docker-managed named volume when Docker cases are enabled. Codeman passes seed, credential, transcript and hook-secret bind sources to the host Docker daemon, so their source files must have stable paths in the daemon's filesystem. A named volume does not provide the required host path mapping.
Static macvlan networking
The default configuration publishes a host port. It does not use network_mode: host. To attach Codeman directly to an existing external macvlan network with a static IP address and MAC address, remove the ports: section and add the following to the codeman service:
mac_address: ${CODEMAN_MAC_ADDRESS}
networks:
codeman_lan:
ipv4_address: ${CODEMAN_IPV4_ADDRESS}
Then add this top-level network declaration:
networks:
codeman_lan:
external: true
name: ${CODEMAN_MACVLAN_NETWORK}
Set CODEMAN_MACVLAN_NETWORK, CODEMAN_IPV4_ADDRESS, and CODEMAN_MAC_ADDRESS in .env. The values in .env.example match the supplied Unraid example network and should be changed for other hosts.
Create a managed macvlan network
If an external macvlan network does not already exist, use this top-level declaration instead. Do not use it together with the external-network declaration.
networks:
codeman_lan:
driver: macvlan
driver_opts:
parent: ${CODEMAN_MACVLAN_PARENT}
ipam:
config:
- subnet: ${CODEMAN_MACVLAN_SUBNET}
gateway: ${CODEMAN_MACVLAN_GATEWAY}
Macvlan containers are ordinarily not reachable from their Docker host without additional host-network routing. Confirm the selected address, MAC address, parent interface, and subnet are reserved and valid for the target network before starting the stack.