A container that runs as a non-root user gets "permission denied" writing to a freshly created Docker named volume mounted at /data, but the same image works fine when the volume is mounted over a path the image already contains. Explain the ownership rules Docker applies when a volume is first mounted, and how to fix it.

## Three different mount behaviours Docker's ownership behaviour at mount time depends on which kind of mount you asked for, and the difference surprises people because the CLI syntax is nearly identical. 1. **Bind mount** (`-v /host/path:/data`). The host directory is exposed as-is. Its existing owner and mode apply. Docker copies nothing and changes nothing. Whatever the image had at `/data` is hidden, not merged. 2. **Named volume, already populated** (`-v mydata:/data` where `mydata` has content). Mounted as-is; existing ownership inside the volume applies. No copy. 3. **Named volume, empty and new** (`-v mydata:/data` on first use). This is the special case: Docker copies the image's content at `/data` into the volume, **preserving ownership and permission bits**, then mounts it. This is how a database image can ship default config or an initialised directory and still let you keep the data outside the container. ## Why the reported failure happens Case 3 only helps if the path exists in the image. If the Dockerfile never created `/data`, there is nothing to copy; the daemon just materialises the mount point. Directories created that way are owned by `root:root` with mode 0755 — writable only by root. A container whose `USER` is `app` (say UID 10001) then fails on its first write with `EACCES`, while the very same image works when the volume targets a path the image *did* create with correct ownership. That asymmetry is exactly what the question describes. ## The fix, in the image Create the directory during build with the ownership the runtime user needs. The seeding copy then carries that ownership into the volume: ```dockerfile RUN useradd -u 10001 -m app \ && mkdir -p /data \ && chown -R app:app /data USER app VOLUME /data ``` Two details matter. First, an empty directory is still "content" for seeding purposes, so this works even though `/data` holds no files. Second, `COPY --chown=app:app` is the cheap way to set ownership on copied content without an extra `chown -R` layer that duplicates every file. The `VOLUME` instruction is documentation and a default; it does not change ownership rules, and it has the side effect of making later `RUN` steps that write to that path silently discard their changes, so declare it after everything is set up — or omit it and let the operator decide. ## The fix, at runtime If you cannot rebuild the image, start as root, chown the mount point, then drop privileges: ```sh #!/bin/sh chown app:app /data exec gosu app "$@" ``` This is what most official database images do internally. It is robust because it fixes whatever ownership the volume happens to have, at the cost of starting with enough privilege to chown. ## The fix, for arbitrary UIDs When the platform assigns an unpredictable UID at run time, you cannot chown to a known user. The portable pattern is to make the path group-writable for GID 0, because arbitrary-UID runtimes typically still assign the primary group 0: ```dockerfile RUN mkdir -p /data && chgrp -R 0 /data && chmod -R g+rwX /data ``` ## Seeding is one-shot, and that bites The copy happens only when the volume is empty. Once the volume has content, a new image version's updated defaults are *not* copied in — the stale volume content wins. Teams hit this when an image ships new config defaults and the change appears to have no effect; the resolution is to treat volume content as data that must be migrated, not as something the image can refresh. Likewise, changing the ownership in a new image version does not repair an existing volume; only an explicit chown does. Also note that seeding applies to Docker's local volume driver semantics. Plugin drivers and remote filesystems (NFS, CIFS, cloud file shares) may ignore or override ownership entirely — NFS with `root_squash` maps container root to `nobody`, and CIFS mounts usually pin ownership through mount options such as `uid=` and `gid=` rather than honouring on-disk metadata. ## Diagnosing ``` docker volume inspect mydata # find the Mountpoint sudo ls -ln <Mountpoint> # numeric owner of the volume root docker run --rm -v mydata:/x alpine ls -ln /x docker exec <container> id ``` Compare the numeric owner of the volume root against the container's numeric UID. If they differ and the mode grants nothing to "other", you have your answer without guessing.