Dockerfile: understanding VOLUME instruction

Question

Let's take an example.

The following is the VOLUME instruction for the nginx image:

VOLUME ["/etc/nginx/sites-enabled", "/etc/nginx/certs", "/etc/nginx/conf.d", "/var/log/nginx", "/var/www/html"]

Here are my questions:

1. When you start the container, will these directories show up on my host? And when I stop my container, the directories will stay?

2. If some (or all) of these directories already exist in my host, what will happen? For example, let's say the image comes with a default config file within the /etc/nginx directory of the container, and I also have a config file within /etc/nginx on my host. When the container starts, which of these files will get priority?

3. What's the key difference between -v /host/dir:container/dir and VOLUME?

References:

• https://github.com/dockerfile/nginx/blob/master/Dockerfile
• http://www.tech-d.net/2014/11/03/docker-indepth-volumes/
• How to mount host volumes into docker containers in Dockerfile during build
• http://jpetazzo.github.io/2015/01/19/dockerfile-and-data-in-volumes/

Answer 1

A container's volumes are just directories on the host regardless of what method they are created by. If you don't specify a directory on the host, Docker will create a new directory for the volume, normally under /var/lib/docker/vfs.

However the volume was created, it's easy to find where it is on the host by using the docker inspect command e.g:

$ ID=$(docker run -d -v /data debian echo "Data container")
$ docker inspect -f {{.Mounts}} $ID
[{0d7adb21591798357ac1e140735150192903daf3de775105c18149552a26f951 /var/lib/docker/volumes/0d7adb21591798357ac1e140735150192903daf3de775105c18149552a26f951/_data /data local  true }]

We can see that Docker has created a directory for the volume at /var/lib/docker/volumes/0d7adb21591798357ac1e140735150192903daf3de775105c18149552a26f951/_data.

You are free to modify/add/delete files in this directory from the host, but note that you may need to use sudo for permissions.

Docker will only delete volume directories in two circumstances:

• If the --rm option is given to docker run, any volumes will be deleted when the container exits
• If a container is deleted with docker rm -v CONTAINER, any volumes will be removed.

In both cases, volumes will only be deleted if no other containers refer to them. Volumes mapped to specific host directories (the -v HOST_DIR:CON_DIR syntax) are never deleted by Docker. However, if you remove the container for a volume, the naming scheme means you will have a hard time figuring out which directory contains the volume.

So, specific questions:

1. Yes and yes, with above caveats.
2. Each Docker managed volume gets a new directory on the host
3. The VOLUME instruction is identical to -v without specifying the host dir. When the host dir is specified, Docker does not create any directories for the volume, will not copy in files from the image and will never delete the volume (docker rm -v CONTAINER will not delete volumes mapped to user-specified host directories).

More information here:

http://container-solutions.com/2014/12/understanding-volumes-docker/