Lesson 5 of 8 in Containers with Docker
Volumes and bind mounts
A volume is storage managed by Docker that outlives any single container, and a bind mount maps a folder from your host into the container. Both place files outside the container's disposable writable layer.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Images, layers and tags, Users, groups, permissions and sudo
The problem this solves
A container's own filesystem is temporary. Remove the container and everything it wrote is gone, which is a problem for a database, uploaded files or anything you need to keep.
You also often want the opposite direction: your editor on the host changing files that a container reads, without rebuilding the image each time.
Docker offers two ways to attach outside storage. They solve different problems, and both can trip you up with file ownership.
How it works
- Runs code
- Data
A container writes to its own layer by default, which is lost, or to a named volume managed by Docker, or to a host folder through a bind mount.
- Container to Writable layer: default
- Container to Named volume: -v name:/path
- Container to Host folder: -v /host:/path
- Runs code
- Data
- Security
The kernel checks file ownership by number, so a container process with one user ID is refused on a host folder owned by a different user ID.
- App process to Mount /data: 1 write a file
- Mount /data to Host folder: 2 kernel checks owner
- Host folder to Permission denied: 3 UID 1000 is not 0
A named volume is a folder Docker creates and looks after, in a location you normally do not touch. You refer to it by name, it survives docker rm, and many containers can mount it. Use it for data the container owns, such as a database's files.
A bind mount points at an exact path on your host. The container and the host see the same files immediately. Use it for development, such as source code you edit, or for handing a config file to a container. Add :ro to make it read-only.
Linux decides file access by numeric user ID and group ID, not by names. A user called app inside the container and a user called you on the host are just numbers to the kernel. When those numbers do not line up with the mounted folder's owner, access fails, or files appear owned by root on the host.
Try it yourself
Use a Linux, macOS or WSL shell. The only host folder touched is a throwaway one you create and delete.
- 1Write to a named volume from one container
docker volume create notes docker run --rm -v notes:/data alpine sh -c 'echo saved > /data/a.txt'
The container is removed with
--rm, but the volume stays. - 2Read it from a brand new container
docker run --rm -v notes:/data alpine cat /data/a.txt
You should see
saved
A different container sees the file, so the data outlived the first one.
- 3Share a host folder with a bind mount
mkdir -p ~/learn-bind && echo 'from the host' > ~/learn-bind/f.txt docker run --rm -v ~/learn-bind:/host:ro alpine cat /host/f.txt
You should see
from the host
:romounts it read-only. Trytouch /host/xin that container and you will get a read-only file system error. - 4See who owns files a container creates
docker run --rm -v ~/learn-bind:/host alpine touch /host/made-by-container ls -ln ~/learn-bind
On Linux the new file is owned by user 0, which is root, because the container process ran as root. Docker Desktop on macOS and Windows maps ownership differently, so you may not see this.
- 5Clean up
docker volume rm notes rm -rf ~/learn-bind
On Linux the root-owned file may need
sudo rm -rf ~/learn-bindinstead. Check the path before you run it.
What breaks, and where to look
touch: cannot touch '/data/x': Permission denied (or EACCES: permission denied, open '/data/...' from the app) on a mounted folder.
- WHY IT HAPPENS
- The process in the container runs as a user ID that does not own the host folder or have write access. Docker does not translate IDs for you on Linux.
- CHECK FIRST
- Compare
docker exec <name> idwithls -ln <host-folder>. Fix by running the container as your own IDs with--user "$(id -u):$(id -g)", or by changing the folder's owner or mode, or by using a named volume instead.
You mount a folder over a path in the image, such as
/app, and the files that were in the image there disappear.- WHY IT HAPPENS
- A mount covers whatever was at that path in the image. An empty host folder mounted over
/apphides everything the image put in/app. - CHECK FIRST
- Run
docker exec <name> ls /appto see what the container sees. Mount to a different path, or populate the host folder first.
Your database or app data is gone after
docker compose down -v, or after switching to a different folder or project name.- WHY IT HAPPENS
-vondowndeletes the volumes. Also, a volume name is prefixed with the project name, which defaults to the folder name, so a renamed folder creates a fresh empty volume.- CHECK FIRST
- Run
docker volume lsand look for the older volume. Avoid-vunless you mean to wipe the data.
When not to use this
- Bind mounts tie a container to one host's folder layout, so they are poor for production deployments. Prefer named volumes, or a managed database or storage service.
- A volume is not a backup. If the disk or the Docker host is lost, the data goes with it. Copy important data elsewhere on a schedule.
Check yourself
When would you choose a named volume over a bind mount?
For data the container owns and must keep, like a database's files. A bind mount suits sharing a specific host folder, such as source code during development.
Why can a container get permission denied on a folder you own?
Permissions use numeric user IDs. The container's process runs with a different number than the folder's owner.
What does mounting an empty folder over /app do to the image's files at /app?
It hides them. The container sees the empty folder, not the image's content at that path.
Keep going
Lesson 43 of 92 in the DevOps path