Docker.github.io: Improve docs for `nocopy` behavior for volumes

[joaofnfernandes]

When doing docker run -v <source>:<destination> you're mounting a directory in the container, and the original directory in the container won't be accessible. In 99% of cases this doesn't matter and things work as you expect.

If you're using named or anonymous volumes, before mounting the external filesystem in the container, Docker will copy the files to it. The end result is that you'll be able to see the (copy of) the files locally. There are a few exceptions to this, and you can also override this behavior with the volume-nocopy option.

But if you're sharing a host directory with the container, Docker won't copy the files, which means that you'll only see an empty directory and not the files that were in the container.

There are a few action items here:

• [ ] This article should talk about this, or link to this one
• [ ] [This article](https://docs.docker.com/engine/tutorials/dockervolumes/#mount-a-host-directory-as-a-data-volume) brushes on this, but we can improve it.

If the path /webapp already exists inside the container’s image, the /src/webapp mount overlays but does not remove the pre-existing content. Once the mount is removed, the content is accessible again. This is consistent with the expected behavior of the mount command.

We can give an example in this sentence. Something like "As an example, if the host directory is empty, and the container directory has files, after mounting the volume the container directory will also be empty. Once the mount is removed ..."

[potzkovge]

If i start a container with a named volume and with the :nocopy option i get
tmp-test-1 | 2017-05-05T08:57:25.724810626Z no such file or directory
But if i leave it blank (default to copy) it works and all files are copied from the container to the named-volume i created.

Can you elaborate on this?
the :nocopy option works on empty folders or new folders which are also empty (duh)

Here is an example docker-compose v2 file:

version: "2"

services:
test:
image: ubuntu
volumes:
- "named-test:/lib:nocopy"
stdin_open: true
tty: true

volumes:
named-test: {}

[joaofnfernandes]

@potzkovge this is a good example of what I was talking about. Here's what /lib contains on a Linux distribution

The /lib directory contains kernel modules and those shared library images (the C programming code library) needed to boot the system and run the commands in the root filesystem, ie. by binaries in /bin and /sbin.
Source

If you mount an empty directory into /lib that image won't have kernel modules, libraries, and executables that Ubuntu needs to boot.
If you don't use nocopy, Docker will copy those files to the volume before mounting it, so when Ubuntu boots it will be able to access the files. If you use nocopy, you're out of luck 😂

[potzkovge]

@joaofnfernandes thanks a lot for the quick response.

this means the nocopy option inverts the initial direction of the copy from container -> volume to volume -> container, after that they behave the same way? If true there has to be a better name than nocopy 😆.

[joaofnfernandes]

@potzkovge no. Maybe this illustrates better what nocopy does

Maybe now it's obvious that in scenario 2 and 3, your Ubuntu container won't be able to boot
EDIT: There's a typo in scenarios 2 and 3. It should say volume has data

[potzkovge]

@joaofnfernandes yes thanks a lot for this ilustration. I tried to find something similar in the docs or somewhere on the internet but couldn't.

+1 for this github issue 🤣

[milanchotai]

Really confused - I thought a bind wouldn't create a volume, let alone cause the host folder to have files from image copied into it, but I can't stop this behaviour.

I have a really simple use-case, but I can't find any information despite looking over Docker's documentation, Google, and GitHub images / related comments.

I have a docker Compose file with a service called "WordPress". I simply want to use my own wp-content folder, not the image. I added:

volumes:
       - ./wp-content:/var/www/html/wp-content

As this is a bind, I'm lost why a volume is created, but one is when I run docker-compose up -d ... I just want a mapping from the container's folder to mine. Worse, if there are files in the container's folder I don't have - say a plugin in the default WordPress image I don't want - it gets copied into my wp-content folder! I've tried :nocopy, but that throws errors:

Cannot create container for service wordpress: invalid bind mount spec
invalid volume specification
invalid mount config for type "bind": field VolumeOptions must not be specified

If a bind shouldn't by default copy files, why is this happening?

[mdlinville]

A bind mount is different from a volume. Please see https://docs.docker.com/engine/admin/volumes/ to understand the differences. To use a bind mount in Docker Compose, you need to specify type: bind. Look at the Docker Compose reference for an example which uses both a volume and a bind mount in the same docker-compose.yml file. Maybe that will clarify things.

[milanchotai]

@mstanleyjones : I did that originally - reviewed the Compose reference (v3) and tried both long-form and short-form - couldn't get it to work. Would you be able to provide a working example? (The error I posted also notes Docker considers it a bind mount.)

[mdlinville]

version: "3.2"
services:
  wordpress:
    image: wordpress:latest
    volumes:
      - type: bind
        source: ./wp-content
        target: /var/www/html/wp-content

Bind mounts are not specified in the top-level volumes: key in the docker-compose.yml.

[milanchotai]

Unfortunately, that's what I have - my full docker-compose.yml:

version: '3.3'

services:
   db:
     container_name: db
     image: mysql:5.7
     volumes:
       - db_data:/var/lib/mysql
     restart: always
     environment:
       MYSQL_ROOT_PASSWORD: somewordpress
       MYSQL_DATABASE: wordpress
       MYSQL_USER: wordpress
       MYSQL_PASSWORD: wordpress

   wordpress:
     container_name: wordpress
     depends_on:
       - db
     image: wordpress:4.8.1-php7.1-apache
     volumes:
       - type: bind
         source: ./wp-content
         target: /var/www/html/wp-content
     ports:
       - "8000:80"
     restart: always
     environment:
       WORDPRESS_DB_HOST: db:3306
       WORDPRESS_DB_USER: wordpress
       WORDPRESS_DB_PASSWORD: wordpress

volumes:
    db_data:

Update: Mistake on my part - confirmed no volume is being created by the bind - must be WordPress doing it. (I'm a Docker noob.) Unfortunately, the copy behaviour persists - my empty wp-content directory is populated by folders and files from the image, and it overwrote if I had a file (i.e.: index.php) with the same name.

[thaJeztah]

Unfortunately, the copy behaviour persists - my empty wp-content directory is populated by folders and files from the image, and it overwrote if I had a file (i.e.: index.php) with the same name.

Yes, the WordPress image has an entrypoint script that copies files to the wp-content directory if it is empty, that's not docker itself doing so (see the entrypoint script here; https://github.com/docker-library/wordpress/blob/1caade96b306d0ed12f5637196e8f0b1883330f5/php5.6/apache/docker-entrypoint.sh#L43-L72)

[thaJeztah]

One use for the nocopy option is when using a volume to share information between containers. The "source" container (container writing to the volume) would not have the nocopy option set (so files from the container are written to the volume the first time it's used), and other container(s) _reading_ the information would have the :nocopy (and possibly ro) option set to prevent them from writing to the volume.

There is _some_ documentation on this option (https://github.com/docker/cli/search?l=Markdown&q=nocopy&type=), but it's very limited, so we could indeed use some additional documentation (and examples). Also see https://github.com/moby/moby/issues/26333

[ghost]

Closing this ticket due to its age, and the impending refactor. If you think this is in error, feel free to reopen. Thanks!