Docker Compose Notes

Imagine docker-compose.yml (or most of it) looking like below. Here we're mostly interested in postgres, but we've included other services too. What interests us is highlighted. Contemplate the section PGDATA at Docker postgres (Docker Official Images) which is an excellent container and place to start.

version: '3.5'
services:
  .
  .
  .
  postgres:
    image: "postgres"
    restart: always
    networks:
      acme:
    volumes:            ("volume-name:path", see below)
      - "postgres-data:/var/lib/postgresql/data"
    environment:
      POSTGRES_DB:       acme
      POSTGRES_USER:     postgres
      POSTGRES_PASSWORD: acme123
    deploy:
      mode: global

  elk:
    image: "sebp/elk:642"
    ports:
      - "5601:5601"
      - "9200:9200"
      - "9300:9300"
      - "5044:5044"
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    networks:
      acme:
    volumes:
      - "elastic-search-data:/var/lib/elasticsearch"
    deploy:
      mode: global
      placement:
        constraints:
          # Only deploy on Docker nodes labeled with acme.elk=true, to wit:
          # $ docker node update --label-add elk=true <nodename>
          - node.labels.acme.elk==true

  filebeat:
    image: "filebeat:6.4.2"
    networks:
      acme:
    volumes:
      - "logs:/opt/logs"
    # Deploy filebeat on _all_ nodes
    deploy:
      mode: global

  .
  .
  .
volumes:
  postgres-data:        (volume-name/what volume is called in this file)
    external: true      (means the volume is created outside of Compose)
    name: postgres-data (what volume name is called in host filesystem)
  logs:
    name: log-data
  elastic-search-data:
    name: elk-data

More notes (and better perhaps than the comments above)...

• postgres-data is the name of the mounted volume as far as docker-compose.yml knows and is used in service definitions (here, service postgres) to indicate that volume.
• In the service (postgres) specification, "volume-name:path", makes use of the Docker Compose-known volume name (here, "postgres-data") to which you instruct it to append whatever path is appropriate. Looking at the notes on the Docker postgres container, referenced earlier, you see that it suggests this path.
• external: true means that the mounted volume is created, on the host or elsewhere, but outside of Docker Compose. See Docker Compose file version 3 reference. This volume may not be magically created by the time you issue docker compose up and an error will result if it doesn't already exist. However, the command, docker stack deploy will create it. Thereafter, as it exists, docker compose up will work.
• Though the "volume is created outside of Docker Compose," in the host filesystem, this doesn't really mean that you need to create some subdirectory in your filesystem named, postgres-data. What really happens is this name is created by Docker on the host on the path, /var/lib/docker/volumes/sda-postgres-data/_data:

  root@moria:/var/lib/docker/volumes# ll
  total 300
  drwx------ 59 root root 12288 Feb 12 14:45 ./
  drwx--x--x 15 root root  4096 Feb 11 08:27 ../
  .
  .
  .
  -rw-------  1 root root 65536 Feb 12 14:45 metadata.db
  drwxr-xr-x  3 root root  4096 Feb 12 14:45 postgres-data/
  

  Similarly, we see PostgreSQL data where we suspect it should be in the Docker container:

  root@9ba1ab4cb82b:/# ll /var/lib/postgresql/data/
  total 128
  drwx------ 19 postgres  4096 Feb 12 23:06 .
  drwxr-xr-x  1 postgres  4096 Jan 30 21:25 ..
  drwx------  6 postgres  4096 Feb 12 21:45 base
  drwx------  2 postgres  4096 Feb 12 23:07 global
  drwx------  2 postgres  4096 Feb 12 21:45 pg_commit_ts
  drwx------  2 postgres  4096 Feb 12 21:45 pg_dynshmem
  -rw-------  1 postgres  4535 Feb 12 21:45 pg_hba.conf
  -rw-------  1 postgres  1636 Feb 12 21:45 pg_ident.conf
  drwx------  4 postgres  4096 Feb 12 23:06 pg_logical
  drwx------  4 postgres  4096 Feb 12 21:45 pg_multixact
  drwx------  2 postgres  4096 Feb 12 23:06 pg_notify
  drwx------  2 postgres  4096 Feb 12 21:45 pg_replslot
  drwx------  2 postgres  4096 Feb 12 21:45 pg_serial
  drwx------  2 postgres  4096 Feb 12 21:45 pg_snapshots
  drwx------  2 postgres  4096 Feb 12 23:06 pg_stat
  drwx------  2 postgres  4096 Feb 12 23:07 pg_stat_tmp
  drwx------  2 postgres  4096 Feb 12 21:45 pg_subtrans
  drwx------  2 postgres  4096 Feb 12 21:45 pg_tblspc
  drwx------  2 postgres  4096 Feb 12 21:45 pg_twophase
  -rw-------  1 postgres     3 Feb 12 21:45 PG_VERSION
  drwx------  3 postgres  4096 Feb 12 21:45 pg_wal
  drwx------  2 postgres  4096 Feb 12 21:45 pg_xact
  -rw-------  1 postgres    88 Feb 12 21:45 postgresql.auto.conf
  -rw-------  1 postgres 23750 Feb 12 21:45 postgresql.conf
  -rw-------  1 postgres    36 Feb 12 23:06 postmaster.opts
  -rw-------  1 postgres    94 Feb 12 23:06 postmaster.pid
  

The distinction and utility are a matter of scope. Docker Compose is limited to a single host while Docker Swarm (and Kubernetes) orchestrate Docker containers in a cluster of multiple hosts.