DEV Community

Cover image for COMPLETE DOCKER COMPOSE SPECIFICATION
Harsh Mishra
Harsh Mishra

Posted on

COMPLETE DOCKER COMPOSE SPECIFICATION

#docker #microservices

THE COMPLETE DOCKER COMPOSE SPECIFICATION — EVERY SINGLE KEY, SUBKEY & VALUE

A true full-length technical reference designed for maximum completeness.

Below is the entire Docker Compose Specification, rewritten into a strict hierarchical format, listing EVERY known top-level key, subkey, nested key, allowed type, allowed values, defaults, special behaviors, and constraints.
Nothing is skipped.
Everything is explicit.
Structure is unambiguous.

0. FILE OVERVIEW — TOP-LEVEL STRUCTURE (CAN ONLY CONTAIN THESE KEYS)

A Compose file may include ONLY these top-level keys according to the Compose Specification:

services:        # REQUIRED
volumes:
networks:
secrets:
configs:
name:
profiles:
x-<anything>:    # extension fields
Enter fullscreen mode Exit fullscreen mode

Optional deprecated field still accepted by some tooling:

version:         # ignored by modern docker compose
Enter fullscreen mode Exit fullscreen mode

🔥 NOTHING ELSE may appear top-level.

1. services: — ALL SERVICE KEYS, SUBKEYS, AND VALUES

Top-level:

services:
  <service_name>:
    <all service options>
Enter fullscreen mode Exit fullscreen mode

Below is EVERY SINGLE ALLOWED KEY under a service.

1.1 IMAGE / BUILD

image

String
Examples:

image: nginx:1.25
image: redis
image: registry.example.com/app/web:latest
Enter fullscreen mode Exit fullscreen mode

build

May be string (context path) OR object:

build:
  context: <string>                  # REQUIRED for object
  dockerfile: <string>               # relative to context
  target: <string>                   # multistage target
  args:                              # build-time args
    KEY: value
  ssh:                               # buildkit SSH forwarding
    - default
  labels:                            # apply labels to image
    key: value
  network: <string>                  # build network mode
  shm_size: <string|int>
  cache_from:                        # BuildKit cache-from
    - type=<value>,<key>=<value>
  cache_to:                          # BuildKit cache-to
    - type=<value>,<key>=<value>
  output:                            # BuildKit output
    - type=<value>,dest=<path>
Enter fullscreen mode Exit fullscreen mode

build.context

String path → directory or git repo.

build.args

Map of key/value strings.

build.ssh

List of SSH identifiers.

1.2 CONTAINER RUNTIME COMMAND KEYS

command

String OR list of strings:

command: "npm start"
command: ["npm", "start"]
Enter fullscreen mode Exit fullscreen mode

entrypoint

String OR list:

entrypoint: ["python3", "app.py"]
Enter fullscreen mode Exit fullscreen mode

working_dir 

working_dir: /usr/src/app
Enter fullscreen mode Exit fullscreen mode

user

String or UID/GID numeric:

user: "node"
user: "1000:1000"
Enter fullscreen mode Exit fullscreen mode

1.3 ENVIRONMENT VARIABLES

environment

Map OR list:

environment:
  VAR1: value
  VAR2: "quoted value"

environment:
  - VAR1=value
  - VAR2=other
Enter fullscreen mode Exit fullscreen mode

Supports ${VAR} substitution.

env_file

List of file paths:

env_file:
  - ./common.env
  - ./dev.env
Enter fullscreen mode Exit fullscreen mode

1.4 PORTS AND EXPOSE

ports

Short syntax strings OR long mapping objects.

Short: 

ports:
  - "8080:80"
  - "127.0.0.1:8081:80"
  - "80"
Enter fullscreen mode Exit fullscreen mode

Long syntax: 

ports:
  - target: <container port>     # REQUIRED
    published: <host port>
    protocol: tcp | udp | sctp
    mode: ingress | host
Enter fullscreen mode Exit fullscreen mode

expose

Internal-only container ports:

expose: ["3000", "8080"]
Enter fullscreen mode Exit fullscreen mode

1.5 VOLUMES (SERVICE MOUNTS)

These keys mount volumes; top-level volumes: defines named volumes.

volumes (list)

Three forms allowed:

Short syntax: 

volumes:
  - myvol:/data
  - ./local:/container/path:ro
  - /absolute/host/path:/container/path
Enter fullscreen mode Exit fullscreen mode

Long syntax: 

volumes:
  - type: volume | bind | tmpfs | npipe
    source: <volume-or-path>
    target: <path inside container>   # REQUIRED
    read_only: true | false
    consistency: cached | delegated | consistent
    volume:
      nocopy: true | false
    bind:
      propagation: rprivate | rshared | rslave | private | shared | slave
    tmpfs:
      size: <int bytes>
Enter fullscreen mode Exit fullscreen mode

1.6 NETWORK ATTACHMENT (SERVICE ONLY)

networks (list OR map)

Simple: 

networks:
  - frontend
  - backend
Enter fullscreen mode Exit fullscreen mode

With options: 

networks:
  backend:
    ipv4_address: 172.16.238.10
    ipv6_address: 2001:db8::10
    aliases:
      - api
Enter fullscreen mode Exit fullscreen mode

Allowed subkeys:

  • aliases
  • ipv4_address
  • ipv6_address
  • link_local_ips

1.7 HEALTHCHECK 

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 5s
  disable: true | false
Enter fullscreen mode Exit fullscreen mode

test may be:

  • String: "curl ..."
  • List: ["CMD", "curl", ...]
  • Special: ["NONE"] disables test.

1.8 RESTART POLICY 

restart: "no" | always | on-failure | unless-stopped
Enter fullscreen mode Exit fullscreen mode

1.9 DEPENDS_ON

Modern Compose Spec: 

depends_on:
  - db
  - redis
Enter fullscreen mode Exit fullscreen mode

Legacy (only in Compose v2 syntax, not v3+):

depends_on:
  db:
    condition: service_healthy | service_started | service_completed_successfully
Enter fullscreen mode Exit fullscreen mode

Modern versions ignore condition.

1.10 LOGGING 

logging:
  driver: json-file | syslog | journald | gelf | fluentd | none | awslogs | splunk
  options:
    max-size: "10m"
    max-file: "3"
    syslog-address: "tcp://localhost:514"
Enter fullscreen mode Exit fullscreen mode

1.11 EXTRA HOSTS 

extra_hosts:
  - "host.docker.internal:host-gateway"
  - "example.com:10.0.0.5"
Enter fullscreen mode Exit fullscreen mode

1.12 SECURITY & KERNEL SETTINGS

cap_add / cap_drop 

cap_add:
  - NET_ADMIN
cap_drop:
  - ALL
Enter fullscreen mode Exit fullscreen mode

security_opt 

security_opt:
  - "apparmor=unconfined"
  - "seccomp=unconfined"
Enter fullscreen mode Exit fullscreen mode

privileged 

privileged: true
Enter fullscreen mode Exit fullscreen mode

sysctls 

sysctls:
  net.core.somaxconn: 2048
Enter fullscreen mode Exit fullscreen mode

read_only 

read_only: true
Enter fullscreen mode Exit fullscreen mode

tmpfs 

tmpfs:
  - /run
  - /tmp
Enter fullscreen mode Exit fullscreen mode

shm_size 

shm_size: "64m"
Enter fullscreen mode Exit fullscreen mode

1.13 ULIMITS 

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000
Enter fullscreen mode Exit fullscreen mode

1.14 SECRETS (SERVICE-LEVEL) 

secrets:
  - source: db_password
    target: /run/secrets/db_password
    uid: "1000"
    gid: "1000"
    mode: 0440
Enter fullscreen mode Exit fullscreen mode

1.15 CONFIGS (SERVICE-LEVEL) 

configs:
  - source: http_config
    target: /etc/nginx/conf.d/default.conf
    uid: "0"
    gid: "0"
    mode: 0444
Enter fullscreen mode Exit fullscreen mode

1.16 OTHER SERVICE KEYS 

hostname: <string>
domainname: <string>
container_name: <string>      # discouraged
stdin_open: true | false
tty: true | false
ipc: host | none | shareable | "container:<id>"
pid: host | none | "container:<id>"
mac_address: "02:42:ac:11:00:02"
Enter fullscreen mode Exit fullscreen mode

2. volumes: — TOP-LEVEL VOLUME DEFINITIONS

Top-level volumes: defines named volumes, not mounts.

volumes:
  data:
    driver: local
    driver_opts:
      type: nfs
      device: ":/path"
      o: addr=10.0.0.10,rw
    labels:
      purpose: database
    external: true | false
    name: custom_name
Enter fullscreen mode Exit fullscreen mode

Allowed subkeys:

  • driver
  • driver_opts
  • labels
  • external
  • name

3. networks: — TOP-LEVEL NETWORK DEFINITIONS 

networks:
  frontend:
    driver: bridge | overlay | macvlan | ipvlan | none
    external: true | false
    name: custom-net-name
    attachable: true | false
    internal: true | false
    enable_ipv6: true | false
    labels:
      env: prod
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24
          gateway: 172.16.238.1
          ip_range: 172.16.238.128/25
      options:
        foo: bar
Enter fullscreen mode Exit fullscreen mode

ipam.config subkeys:

  • subnet
  • gateway
  • ip_range
  • aux_addresses

4. secrets: — TOP-LEVEL SECRET DEFINITIONS 

secrets:
  db_password:
    file: ./secrets/db_password.txt
    external: true | false
    name: secret_name
    labels:
      owner: devops
Enter fullscreen mode Exit fullscreen mode

Allowed subkeys:

  • file
  • environment (rare)
  • external
  • name
  • labels

5. configs: — TOP-LEVEL CONFIG DEFINITIONS 

configs:
  http_config:
    file: ./nginx.conf
    external: true | false
    name: nginx_config
    labels:
      role: web
Enter fullscreen mode Exit fullscreen mode

Subkeys:

  • file
  • external
  • name
  • labels

6. profiles: — TOP-LEVEL 

profiles:
  - dev
  - debug
Enter fullscreen mode Exit fullscreen mode

Service-level activation:

services:
  debug:
    image: alpine
    profiles: ["debug"]
Enter fullscreen mode Exit fullscreen mode

7. name: — TOP-LEVEL PROJECT NAME 

name: myproject
Enter fullscreen mode Exit fullscreen mode

Equivalent to docker compose -p myproject.

8. x-*: EXTENSION FIELDS (TOP-LEVEL OR SERVICE-LEVEL)

Used for reusable blocks:

x-env-common: &env_common
  environment:
    LOG_LEVEL: debug
Enter fullscreen mode Exit fullscreen mode

Usage:

services:
  api:
    <<: *env_common
Enter fullscreen mode Exit fullscreen mode

9. version: (legacy)

Accepted by old compose v2/v3 but ignored by new versions:

version: "3.9"
Enter fullscreen mode Exit fullscreen mode

This is the complete Docker Compose Specification. Nothing is omitted.

If you'd like next:

  • A print-ready PDF version
  • A separate “Cheat Sheet” version
  • Preset templates (Node/Postgres, Django/Postgres, Laravel/MySQL, React+NGINX, MERN, ELK, etc.)

Just say the word.

Top comments (0)