Bind Mounts in Development

A bind mount maps a host directory straight into the container, so a file you save on the host is instantly the file the container runs — no rebuild, no copy. This is what makes containerized development bearable: edit Driftwood's Python source in your editor, and the gunicorn reloader inside the container picks it up. The same directness that makes it good in development is what makes it a footgun — most infamously when the mount clobbers a directory the image already populated.

This page is about using bind mounts where they belong — the inner development loop — and about the three ways they bite: hidden dependencies, accidental writes, and UID mismatches. Each is a predictable consequence of what a bind mount actually does, which is replace the container's view of a path with the host's.

Live-Editing Source on the Host

Bind-mount the project directory over the app's working directory — -v /home/dev/driftwood:/app — and host edits appear in the container immediately. Pair that with a hot-reloader (gunicorn's --reload, a framework's dev server) and you get an edit-save-refresh loop with no image rebuild between changes. The container holds the runtime and the installed dependencies from the image; the bind mount supplies the source you're actively editing. That split is the whole appeal — you iterate on code at host speed while the container provides the environment.

The Clobber Footgun

A bind mount does not merge with what the image put at that path — it replaces the container's view of it entirely. Mount your host source over /app and the container now sees your host directory there, and only your host directory. If the image had installed something into /app at build time, it's gone from view. The classic break: a Python image ran pip install into a site-packages or .venv under the working directory, or a Node image baked node_modules into /app/node_modules — bind-mount your host source over /app and those installed dependencies vanish, because your host tree doesn't contain them. The container starts and then dies with "module not found."

Working Around the Clobber

There are two standard fixes. The clean one is to keep dependencies out of the path the bind mount covers — install a Python virtualenv at /opt/venv instead of inside /app, so mounting source over /app never touches the packages. The other is to shadow the dependency subdirectory with an anonymous volume layered on top of the bind mount — -v /home/dev/driftwood:/app -v /app/node_modules — so the image's node_modules survives under the host mount because the anonymous volume re-covers that one subpath.

# Python — venv lives outside the mounted path, so it's never clobbered
docker run -d --name driftwood-web \
  -v /home/dev/driftwood:/app \
  -e PATH=/opt/venv/bin:$PATH \
  driftwood:dev   # image installed deps into /opt/venv, not /app

# Node — anonymous volume re-covers node_modules under the host mount
docker run -d --name driftwood-web \
  -v /home/dev/driftwood:/app \
  -v /app/node_modules \
  driftwood:dev

In the Python case the host source at /app and the dependencies at /opt/venv never overlap, so there's nothing to clobber. In the Node case the second mount tells Docker to put an anonymous volume at /app/node_modules, which sits on top of the bind mount and preserves the image's installed modules at that one subpath while the rest of /app reflects your host edits.

Read-Only Mounts

Append :ro when the container should read a file but never write it. Driftwood's proxy takes its nginx config exactly this way — -v /home/dev/driftwood/nginx.conf:/etc/nginx/conf.d/default.conf:ro — so the container reads the config at startup and cannot corrupt the host's source-of-truth copy. Read-only is both a safety rail and a statement of intent: it documents that this mount is input to the container, not a place it writes back to. For any config or static asset the container only consumes, :ro should be the default.

Ownership and UID Mismatch

A bind-mounted file carries its host UID, not a username — the kernel only stores the numeric owner. If the container's process runs as a different UID than the host file's owner, it hits permission-denied on files it appears to "own" by name. The sharpest version is the reverse: the container runs as root (UID 0), writes files into the bind-mounted directory, and now the host directory is littered with root-owned files the developer's own account can't edit or delete without sudo. The fix is to align UIDs — run the container as a user matching the host owner, or set ownership deliberately — so the host directory stays manageable from both sides.