How do named volumes work in docker?

Question

I'm struggling to understand how exactly does the named volume work in the following example from docker docs:

version: "3"

services:
  db:
    image: db
    volumes:
      #1
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      #2
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:

My guess is, that the first occurrence of the named volume (#1) defines what is contained inside the volume, while subsequent occurrences (#2) simply share the volume's content with whatever containers they are referenced from.

Is this guess correct?

Answer 1

Listing data-volume: under the top-level volumes: key creates a named volume on the host if it doesn't exist yet. This behaves the following way according to this source

1. If you create a named volume by running a new container from image by docker run -v my-precious-data:/data imageName, the data within the image/container under /data will be copied into the named volume.

2. If you create another container binds to an existing named volume, no files from the new image/container will be copied/overwritten, it will use the existing data inside the named volume.

3. They don’t have a docker command to backup / export a named volume. However you can find out the actual location of the file by “docker volume inspect [volume-name]”.

In case the volume is empty and both containers have data in the target directory the first container to be run will mount its data into the volume and the other container will see that data (and not its own). I don't know which container will run first (although I expect it executes from top to bottom) however you can force an order with depends_on as shown here

------------------- Update

The depends_on option is ignored when deploying a stack in swarm mode with a version 3 Compose file.

Answer 2

The way that I understand your guess, you are not completely correct.

Declaring and referencing a named volume in a docker-compose file will create an empty volume which may then be accessed and shared by the services saying so in their volumes section.

If you want to share a named volume, you have to declare this volume in the top-level volume section of your docker-compose file. Example (as in the docker docs already linked by yourself):

version: "3"

services:
  db:
    image: db
    volumes:
      #1 uses the named and shared volume 'data-volume' created with #3
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      #2 uses the named and shared volume 'data-volume' created with #3
      - data-volume:/var/lib/backup/data

volumes:
  #3 creates the named volume 'data-volume' 
  data-volume:

The volume will be empty on start (and therefore the folders in the containers where that volume is mounted to). Its content will be a result of the services acions on runtime.

Hope that made it a bit more clear.