When exactly and what for should VOLUME in a Dockerfile be used?

When writing a Dockerfile, I do have the option of specifying volumes, such as:

VOLUME /var/www

But even without this declaration I am able to mount volumes to this directory and other places, e.g. by using -v /foo:/var/www or -v ./httpd/conf.d:/usr/local/apache2/conf/conf.d for bind mounts when running docker.

So:

• Is the specification purely informational?

• What are the (dis)advantages of (not) specifying volumes?

• Why and in which cases should I use VOLUME and when shouldn't I?

• What about files that may optionally be mounted? Do they count as volumes in that case, too?

Short version

VOLUME instruction and -v dest are used to create unnamed/anonymous volumes, -v scr:dest option is for mapped volume.

Long Version

Dockerfile's VOLUME does not allow you to specify a host path.

On the host-side, the volumes are created with a very long ID-like name, these volumes are often referred to as unnamed/anonymous volumes.

Given this Dockerfile:

FROM php7:latest
VOLUME /var/www

Build it:

docker build -t myTest

Run it :

docker run --rm -it myTest

Inside the container, run ls and you'll notice the directory exists; /var/www

Running the container also creates a directory on the host-side.

While having the container running, execute docker volume ls on the host machine and you'll see something like this

DRIVER    VOLUME NAME
local     c984..e4fc

Back in the container, execute touch /var/www/myFile

This file is now available on the host machine, in one of the unnamed volumes.

ls /var/lib/docker/volumes/c984..e4fc/_data

Similarly, you can try to delete this file on the host and it will be deleted in the container as well.

Now run a new container, but specify a volume using -v:

docker run --rm -it -v /myVolume myTest

This adds a second volume and the whole system ends up having two unnamed volumes.
On the host-side, the new second volume is anonymous and resides together with the other volume in /var/lib/docker/volumes/.

It was stated earlier that the Dockerfile can not map to a host path which sort of pose a problem for us when trying to bring files in from the host to the container during runtime. A different -v syntax solves this problem.

Imagine I have a subfolder in my project directory ./src that I wish to sync to /src inside the container. This command does the trick:

docker run -it -v $(pwd)/src:/src myTest

Both sides of the : character expects an absolute path. Left side being an absolute path on the host machine, right side being an absolute path inside the container.

We run this command:

docker run -v $(pwd)/src:/src myTest

Is the specification purely informational?

No, it does mount a volume, it's similar to -v /var/www you just don't specify a mount point in the host machine, so docker will take care of it.

What are the (dis)advantages of (not) specifying volumes?

Why and in which cases should I use VOLUME and when shouldn't I?

It's probably a best practice to never use VOLUME.

The first reason we have already identified: We can not specify the host path.

The second reason is people might forget to use the --rm option when running the container, you will end up with a couple of unused volumes and it might be a daunting task to figure out which of all anonymous volumes are safe to remove

What about files that may optionally be mounted? Do they count as volumes in that case, too?

In this case you don't need volumes; mapping a single file does not make sense, I would use ADD or COPY inside the dockerfile.

StackExchange DevOps Q#5095, answer score: 3