Use volumes

Estimated reading time: 17 minutes

Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. While bind mounts are dependent on the directory structure and OS of the host machine, volumes are completely managed by Docker. Volumes have several advantages over bind mounts:

• Volumes are easier to back up or migrate than bind mounts.
• You can manage volumes using Docker CLI commands or the Docker API.
• Volumes work on both Linux and Windows containers.
• Volumes can be more safely shared among multiple containers.
• Volume drivers let you store volumes on remote hosts or cloud providers, to encrypt the contents of volumes, or to add other functionality.
• New volumes can have their content pre-populated by a container.
• Volumes on Docker Desktop have much higher performance than bind mounts from Mac and Windows hosts.

In addition, volumes are often a better choice than persisting data in a container’s writable layer, because a volume does not increase the size of the containers using it, and the volume’s contents exist outside the lifecycle of a given container.

If your container generates non-persistent state data, consider using a tmpfs mount to avoid storing the data anywhere permanently, and to increase the container’s performance by avoiding writing into the container’s writable layer.

Volumes use rprivate bind propagation, and bind propagation is not configurable for volumes.

Choose the -v or —mount flag

In general, —mount is more explicit and verbose. The biggest difference is that the -v syntax combines all the options together in one field, while the —mount syntax separates them. Here is a comparison of the syntax for each flag.

If you need to specify volume driver options, you must use —mount .

• -v or —volume : Consists of three fields, separated by colon characters ( : ). The fields must be in the correct order, and the meaning of each field is not immediately obvious.
  • In the case of named volumes, the first field is the name of the volume, and is unique on a given host machine. For anonymous volumes, the first field is omitted.
  • The second field is the path where the file or directory are mounted in the container.
  • The third field is optional, and is a comma-separated list of options, such as ro . These options are discussed below.
• —mount : Consists of multiple key-value pairs, separated by commas and each consisting of a = tuple. The —mount syntax is more verbose than -v or —volume , but the order of the keys is not significant, and the value of the flag is easier to understand.
  • The type of the mount, which can be bind , volume , or tmpfs . This topic discusses volumes, so the type is always volume .
  • The source of the mount. For named volumes, this is the name of the volume. For anonymous volumes, this field is omitted. May be specified as source or src .
  • The destination takes as its value the path where the file or directory is mounted in the container. May be specified as destination , dst , or target .
  • The readonly option, if present, causes the bind mount to be mounted into the container as read-only.
  • The volume-opt option, which can be specified more than once, takes a key-value pair consisting of the option name and its value.

Escape values from outer CSV parser

If your volume driver accepts a comma-separated list as an option, you must escape the value from the outer CSV parser. To escape a volume-opt , surround it with double quotes ( » ) and surround the entire mount parameter with single quotes ( ‘ ).

For example, the local driver accepts mount options as a comma-separated list in the o parameter. This example shows the correct way to escape the list.

The examples below show both the —mount and -v syntax where possible, and —mount is presented first.

Differences between -v and —mount behavior

As opposed to bind mounts, all options for volumes are available for both —mount and -v flags.

When using volumes with services, only —mount is supported.

Create and manage volumes

Unlike a bind mount, you can create and manage volumes outside the scope of any container.

Docker Volumes on Windows — Introducing the `G` Drive

Update! From Windows 1809 onwards this is no longer an issue!

You use Docker volumes to store state outside of containers, so your data survives when you replace the container to update your app. Docker uses symbolic links to give the volume a friendly path inside the container, like C:\data . Some application runtimes try to follow the friendly path to the real location — which is actually outside the container — and get themselves into trouble.

This issue may not affect all application runtimes, but I have seen it with Windows Docker containers running Java, Node JS, Go, PHP and .NET Framework apps. So it’s pretty widespread.

You can avoid that issue by using a mapped drive (say G:\ ) inside the container. Your app writes to the G drive and the runtime happily lets the Windows filesystem take care of actually finding the location, which happens to be a symlink to a directory on the Docker host.

Filesystems in Docker Containers

An application running in a container sees a complete filesystem, and the process can read and write any files it has access to. In a Windows Docker container the filesystem consists of a single C drive, and you’ll see all the usual file paths in there — like C:\Program Files and C:\inetpub . In reality the C drive is composed of many parts, which Docker assembles into a virtual filesystem.

It’s important to understand this. It’s the basis for how images are shared between multiple containers, and it’s the reason why data stored in a container is lost when the container is removed. The virtual filesystem the container sees is built up of many image layers which are read-only and shared, and a final writeable layer which is unique to the container:

When processes inside the container modify files from read-only layers, they’re actually copied into the writeable layer. That layer stores the modified version and hides the original. The underlying file in the read-only layer is unchanged, so images don’t get modified when containers make changes.

Removing a container removes its writeable layer and all the data in it, so that’s not the place to store data if you run a stateful application in a container. You can store state in a volume, which is a separate storage location that one or more containers can access, and has a separate lifecycle to the container:

Storing State in Docker Volumes

Using volumes is how you store data in a Dockerized application, so it survives beyond the life of a container. You run your database container with a volume for the data files. When you replace your container from a new image (to deploy a Windows update or a schema change), you use the same volume, and the new container has all the data from the original container.

The SQL Server Docker lab on GitHub walks you through an example of this.

You define volumes in the Dockerfile, specifying the destination path where the volume is presented to the container. Here’s a simple example which stores IIS logs in a volume:

You can build an image from that Dockerfile and run it in a container. When you run docker container inspect you will see that there is a mount point listed for the volume:

The source location of the mount shows the physical path on the Docker host where the files for the volume are written — in C:\ProgramData\docker\volumes . When IIS writes logs from the container in C:\Inetpub\logs , they’re actually written to the directory in C:\ProgramData\docker\volumes on the host.

The destination path for a volume must be a new folder, or an existing empty folder. Docker on Windows is different from linux in that respect, you can’t use a destination folder which already contains data from the image, and you can’t use a single file as a destination.

Docker surfaces the destination directory for the volume as a symbolic link (symlink) inside the container, and that’s where the trouble begins.

Symlink Directories

Symbolic links have been a part of the Windows filesystem for a long time, but they’re nowhere near as popluar as they are in Linux. A symlink is just like an alias, which abstracts the physical location of a file or directory. Like all abstractions, it lets you work at a higher level and ignore the implementation details.

In Linux it’s common to install software to a folder which contains the version name — like /opt/hbase-1.2.3 and then create a sylmink to that directory, with a name that removes the version number — /opt/hbase . In all your scripts and shortcuts you use the symlink. When you upgrade the software, you change the symlink to point to the new version and you don’t need to change anything else. You can also leave the old version in place and rollback by changing the symlink.

You can do the same in Windows, but it’s much less common. The symlink mechanism is how Docker volumes work in Windows. If you docker container exec into a running container and look at the volume directory, you’ll it listed as a symlink directory ( SYMLINKD ) with a strange path:

The logs directory is actually a symlink directory, and it points to the path \\?\ContainerMappedDirectories\8305589A-2E5D.. . The Windows filesystem understands that symlink, so if apps write directly to the logs folder, Windows writes to the symlink directory, which is actually the Docker volume on the host.

The trouble really begins when you configure your app to use a volume, and the application runtime tries to follow the symlink. Runtimes like Go, Java, PHP, NodeJS and even .NET will do this — they resolve the symlink to get the real directory and try to write to the real path. When the «real» path starts with \\?\ContainerMappedDirectories\ , the runtime can’t work with it and the write fails. It might raise an exception, or it might just silently fail to write data. Neither of which is much good for your stateful app.

DOS Devices to the Rescue

The solution — as always — is to introduce another layer of abstraction, so the app runtime doesn’t directly use the symlink directory. In the Dockerfile you can create a drive mapping to the volume directory, and configure the app to write to the drive. The runtime just sees a drive as the target and doesn’t try to do anything special — it writes the data, and Windows takes care of putting it in the right place.

I use the G drive in my Dockerfiles, just to distance it from the C drive. Ordinarily you use the subst utility to create a mapped drive, but that doesn’t create a map which persists between sessions. Instead you need to write a registry entry in your Dockerfile to permanently set up the mapped drive:

This creates a fake G drive which maps to the volume directory C:\data . Then you can configure your app to write to the G drive and it won’t realise the target is a symlink, so it won’t try to resolve the path and it will write correctly.

I use this technique in these Jenkins and Bonobo Dockerfiles, where I also set up the G drive as the target in the app configuration.

How you configure the storage target depends on the app. Jenkins uses an environment variable, which is very easy. Bonobo uses Web.config , which means running some XML updates with PowerShell in the Dockerfile. This technique means you need to mentally map the fake G drive to a real Docker volume, but it works with all the apps I’ve tried, and it also works with volume mounts.

Mounting Volumes

Docker volumes on Windows are always created in the path of the graph driver, which is where Docker stores all image layers, writeable container layers and volumes. By default the root of the graph driver in Windows is C:\ProgramData\docker , but you can mount a volume to a specific directory when you run a container.

I have a server with a single SSD for the C drive, which is where my Docker graph is stored. I get fast access to image layers at the cost of zero redundancy, but that’s fine because I can always pull images again if the disk fails. For my application data, I want to use the E drive which is a RAID array of larger but slower spinning disks.

When I run my local Git server and Jenkins server in Docker containers I use a volume mount, pointing the Docker volume in the container to a location on my RAID array:

Actually I use a compose file for my services, but that’s for a different post.

So now there are multiple mappings from the G drive the app uses to the Docker volume, and the underlying storage location:

Book Plug

I cover volumes — and everything else to do with Docker on Windows — in my book Docker on Windows, which is out now.

If you’re not into technical books, all the code samples are on GitHub: sixeyed/docker-on-windows and every sample has a Docker image on the Hub: dockeronwindows.

Use the G Drive For Now

I’ve hit this problem with lots of different app runtimes, so I’ve started to do this as the norm with stateful applications. It saves a lot of time to configure the G drive first, and ensure the app is writing state to the G drive, instead of chasing down issues later.

The root of the problem actually seems to be a change in the file descriptor for symlink directories in Windows Server 2016. Issues have been logged with some of the application runtimes to work correctly with the symlink (like in Go and in Java), but until they’re fixed the G drive solution is the most robust that I’ve found.

It would be nice if the image format supported this, so you could write VOLUME G: in the Dockerfile and hide all this away. But this is a Windows-specific issue and Docker is a platform that works in the same way across multiple operating systems. Drive letters don’t mean anything in Linux so I suspect we’ll need to use this workaround for a while.

How to mount network Volume in Docker for Windows (Windows 10)

We’re working to create a standard «data science» image in Docker in order to help our team maintain a consistent environment. In order for this to be useful for us, we need the containers to have read/write access to our company’s network. How can I mount a network drive to a docker container?

Here’s what I’ve tried using the rocker/rstudio image from Docker Hub:

docker run -d -p 8787:8787 -v //c/users/:/home/rstudio/foobar rocker/rstudio

This does not work (where P is the mapped location of the network drive): docker run -d -p 8787:8787 -v //p:/home/rstudio/foobar rocker/rstudio

This also does not work: docker run -d -p 8787:8787 -v //10.1.11.###/projects:/home/rstudio/foobar rocker/rstudio

I’m relatively new to Docker, so please let me know if I’m not being totally clear.

4 Answers 4

I know this is relatively old — but for the sake of others — here is what usually works for me. for use — we use a windows file-server so we use cifs-utils in order to map the drive. I assume that below instructions can be applied to nfs or anything else as well.

first — need to run the container in privileged mode so that you can mount remote folders inside of the container ( —dns flag might not be required)
docker run —dns -p 8000:80 —privileged -it

now, (assuming centos with cifs and being root in the container) — hop into the container and run:

install cifs-utils if not installed yet
yum -y install cifs-utils

create the local dir to be mapped
mkdir /mnt/my-mounted-folder

prepare a file with username and credentials
echo «username= » >

/.smbcredentials
echo «password=

map the remote folder
mount -t cifs -o iocharset=utf8,credentials=/root/.smbcredentials,file_mode=0777,dir_mode=0777,uid=1000,gid=1000,cache=strict