Docker compose. The volume inside another volume on the same container. How does it work?

Question

I'm trying to create a relatively simple setup to develop and test npm packages. A problem was in the fact, that after you mounted a code volume to the container it replaces node_modules.

I tried a lot of generally logical stuff, mostly aimed to move node_modules to another location and then reference it within configuration files. It works, but the solution is ugly. Also, it's not good practice to install webpack globally, but my solution requires it.

However, after some time I found this solution, which looks elegant, just what I needed, but it also has one problem. I don't understand completely, how it works.

That my version of how everything operates.

1. Docker reorders volume mounting based on container paths

2. Docker mounts sub dir volume at first

3. Docker mounts parent dir volume but due to an unexplained mechanism, it does not override the sub dir volume...

4. ???

5. PROFIT. node_modules dir is in place and webpack runs perfectly.

So, I really want to understand how it actually does all of this black magic. Because without this knowledge I feel like I'm missing something important.
So, guys, how it works? Thanks in advance.

services:
  react-generic-form:
    image: react-generic-form:package
    container_name: react-generic-form-package
    build:
      dockerfile: dev.Dockerfile
      context: ./package
    volumes:
      - "./package:/package"
      - "/package/node_modules"

Answer 1

The Docker daemon, when it creates the container, sorts all of the mount points to avoid shadowing. (On non-Windows, this happens in (*github.com/docker/docker/daemon.Daemon).setupMounts.) So, in your example:

1. The Docker daemon sees that both /package and /package/node_modules contain data that's stored outside the container filespace.
2. It sorts these shortest to longest.
3. It mounts /package, as a bind-mount to the named host directory. (First, because it's a shorter path name.)
4. It mounts /package/node_modules, shadowing the equivalent directory in the previous mount, probably as a bind-mount to a directory with long hex identifier name somewhere in /var/lib/docker/volumes.

You can experiment more with this with a docker-compose.yml file like

version: '3'
services:
  touch:
    image: busybox
    volumes:
      - ./b:/a/b
      - ./a:/a
    command: touch /a/b/c

Notice that whichever order you put the volumes: in, you will get an empty directory ./a/b (which becomes the mount point inside the container), plus an empty file ./b/c (the result of the touch command).

Also note the statement here that the node_modules directory contains data, that should be persisted across container invocations, and has a lifecycle separately from either the container or its base image. Changing the image and re-running docker-compose up will have no effect on this volume's content.