A team ships a container image that runs its process as a non-root user and bind-mounts the source tree from each developer's machine. Describe the available strategies for making the container user's numeric ID line up with the host user's, and the tradeoffs of each.

## The problem being solved When a host directory is bind-mounted into a container, the kernel enforces ordinary file permissions using the container process's numeric UID and GID against the host inode's numeric owner. If the two numbers do not agree, one of two failures follows: the container cannot write (permission denied on a developer-owned tree), or the container writes files the developer cannot subsequently modify. "Alignment" means making the number the container runs as either equal to, or group-compatible with, the number that owns the host files. ## Strategy 1 — runtime --user ``` docker run --user "$(id -u):$(id -g)" -v "$PWD:/src" myimage ``` This is the most portable option because a single published image serves every host. The kernel accepts any integer, existing user account or not. What breaks: the container's `/etc/passwd` has no matching row, so `getpwuid()` fails. Symptoms include `whoami: cannot find name`, an unset or `/`-valued `HOME` (npm, pip, gradle, and ssh then try to write caches into `/`), and prompt or tooling errors. Mitigations are setting `HOME` and cache directories explicitly via environment variables, or adding a passwd row at startup. Additionally, any path the Dockerfile created for the image's intended user (`/app/.cache`, `/home/appuser`) is now owned by the wrong UID, so those must be made group-writable or moved to a writable location. A common pattern is to give the image user group 0 and `chmod g+rwX` writable paths, since arbitrary UIDs typically still get GID 0 in some runtimes. ## Strategy 2 — build-time UID injection ``` ARG UID=1000 ARG GID=1000 RUN groupadd -g $GID app && useradd -u $UID -g $GID -m app USER app ``` Inside the image everything is coherent: the user has a name, a home directory, and owns its own caches. Nothing needs an entrypoint hack. The cost is that the image is now per-developer. Every host with a different UID needs its own build, so you cannot ship one artifact from CI to everyone, and the image you test is not byte-identical to the image a colleague runs. It also silently degrades: someone on macOS with UID 501 builds with the default 1000 and rediscovers the original bug. It works best when the whole team is standardised (all Linux, all UID 1000) or when the compose file passes `args: UID: ${UID:-1000}` and everyone exports it. ## Strategy 3 — chown in the entrypoint, then drop privileges ``` #!/bin/sh chown -R app:app /data exec gosu app "$@" ``` The container starts as root, fixes ownership of whatever it was handed, and then permanently drops to the unprivileged user with `gosu` or `su-exec` — both of which `exec` into the target process so PID 1 stays the app and signals still work (`su` and `sudo` fork, leaving an extra process that swallows SIGTERM). Costs and caveats: a recursive chown of a large tree (a `node_modules` with 300k inodes) can add many seconds to every start; you can narrow it to the specific directories that need writing. The container must begin with the ability to chown, which conflicts with policies that forbid starting as root. And on read-only or externally-managed mounts, chown may simply fail. A refinement is `fixuid`, which rewrites the container user's UID to match the mount's owner instead of rewriting the files. ## Escape hatch A — do not bind-mount writable state Much of the pain comes from putting *container-owned* output on a *human-owned* filesystem. Source code needs to be a bind mount because humans edit it. Build caches, dependency directories, and databases do not. Mounting a named volume over `/app/node_modules` or `/app/target` keeps ownership entirely inside Docker's control, removes the mismatch for those paths, and usually improves I/O performance on Docker Desktop as a bonus. ## Escape hatch B — rootless Docker and userns-remap Under rootless Docker, the daemon runs as the developer and container UID 0 is mapped to the developer's host UID via `/etc/subuid`. A container running as root therefore produces developer-owned files, which is exactly what people naively expect. Non-zero container UIDs map into the subordinate range and appear on the host as large unmapped numbers, so the technique is not free — but for the very common "container runs as root, writes to my tree" case it is the cleanest fix available. Rootful daemons can approximate this with `userns-remap` in `daemon.json`. ## Choosing For an image published to many machines, prefer `--user` plus group-writable paths, or an entrypoint chown. For a tightly controlled internal dev environment, build-time UID is simplest to reason about. In all cases, keep container-written state off bind mounts wherever a human does not need to read it directly.