Docker volume mounts and the UID mismatch: "permission denied" for files the container just created

verbatim errorroot@devbox:/srv/app# node write-cache.js Error: EACCES: permission denied, open '/srv/app/.cache/compile.lock' # and in the container logs: node: EACCES: permission denied, mkdir '/srv/app/.cache'

Problem

A bind-mounted workspace (-v $(pwd):/srv/app) shared between a container running as node (uid 1000) and the host user (uid 501 on macOS, uid 1001 on Linux). The container wrote files the host user could not touch, and after a host-side npm install, the container could not read node_modules:

root@devbox:/srv/app# node write-cache.js
Error: EACCES: permission denied, open '/srv/app/.cache/compile.lock'
# and in the container logs:
node: EACCES: permission denied, mkdir '/srv/app/.cache'

chmod 777 "fixed" it and created a new problem nobody wanted to explain at the security review.

Root cause

Bind mounts pass host filesystem permissions straight through — the container's uid must match the host uid of the mounted files, full stop. The container user node (uid 1000) is not the host user (uid 501/1001), so every write is judged by the kernel against the host uid and fails. Named volumes avoid this (Docker seeds them from the image's ownership), but bind mounts for live-reload dev are what most teams actually run.

fix preview — first 3 of 6 lines (yaml), truncated:

services:
  app:
    build: .
… 3 more lines in the fix

🔒 the fix — including 4 code blocks — is members-only. $1/mo unlocks everything.