| |

Docker 41 🐳 Docker Compose Specification: services, networks, volumes, and environment

⏱️ Estimated read: 18 min | |

The Compose specification is the schema that defines what a compose.yaml file can contain. It is not a Docker-specific format; it is an open specification that Docker Compose, Docker Swarm (partially), and other tools implement. The specification defines the top-level elements — services, networks, volumes, configs, secrets, and the project-level settings — and the sub-elements that each one accepts. Understanding the specification is what allows a developer to write a Compose file that is portable, maintainable, and predictable across environments.

The four elements in this chapter’s title are the ones that appear in almost every Compose file. services defines the containers: the images, the build contexts, the ports, the volumes, the environment variables, and the dependencies. networks defines the communication channels between services: the default bridge network, the custom networks, and the drivers that implement them. volumes defines the persistent storage: the named volumes that Docker manages and the bind mounts that map host directories. environment defines the variables that are passed to the containers: the literal values, the values from the host environment, and the values from an .env file.

The specification has evolved from the original docker-compose.yml format in v1 and v2 to the current compose.yaml format in v3 and later. The v3 format was designed for Swarm, and the current specification merges the v2 and v3 features into a single schema. The top-level version key is now deprecated, and the specification recommends omitting it. The name key sets the project name, which prefixes all created resources. The services key is the only required top-level element, and the others are optional.

This chapter covers three areas. First, the specification and its structure — the top-level elements, the project name, and the relationship to the legacy formats. Second, the four core elements — services with its sub-elements, networks with its drivers, volumes with the named and bind types, and environment with the three forms of variable interpolation. Third, the patterns and the best practices — the service configuration, the network isolation, the volume persistence, and the environment management. The chapter ends with a complete example session, a quick reference, best practices, common pitfalls, real-world examples, and diagrams showing the specification structure.

Key point: The Compose specification defines the top-level elements services, networks, volumes, configs, secrets, and the project settings. The services element is the only required one. The specification recommends omitting the version key and using the name key to set the project name. The environment element accepts literal values, host environment variables, and .env file variables.


Why the Compose specification exists

The portability problem. A Compose file is a declaration of an application’s stack. If the format is not standardized, every tool that consumes it must guess at the semantics. The Compose specification is the standard: it defines the keys, the types, the defaults, and the interpolation rules. A file that conforms to the specification can be used by Docker Compose, by a CI system, and by a development environment without modification.

The versioning problem. The original docker-compose.yml format had a version key that selected the schema. The v1 format had no top-level services key, the v2 format added it, and the v3 format added Swarm-specific keys. The versioning created confusion: a file with version: '3.8' could not use a v2 feature, and the semantics of a key could change between versions. The Compose specification removes the versioning from the file. The specification is a single schema, and the version key is deprecated. The tooling determines the schema, and the file does not need to declare it.

The feature-merge problem. The v2 and v3 formats had overlapping features with different semantics. The depends_on key had a short form in v2 and a long form with conditions in v3. The deploy key was Swarm-specific in v3, and the resources sub-key was not available in v2. The Compose specification merges the features: the depends_on long form with condition: service_healthy is available, and the deploy key is available for the tools that support it. The file describes the application, and the tool decides which features it can honor.

The project-name problem. Every Compose project has a name, and the name prefixes the created resources: the containers, the networks, and the volumes. The project name is determined by the -p flag, the COMPOSE_PROJECT_NAME environment variable, the top-level name key, or the directory name. The name key in the file is the recommended way to set it, because it is committed with the file and does not depend on the directory where the file is run.

The environment problem. An application needs configuration: database credentials, API keys, feature flags. The values differ between environments: development, staging, production. The environment element is the way to pass the values to the containers. The element accepts literal values, references to the host environment, and values from an .env file. The interpolation rules determine the precedence, and the specification defines them.

The trade-off. The Compose specification is a large schema, and not every key is supported by every tool. A file that uses a Swarm-specific key will not work with plain Docker Compose, and a file that uses a Compose-specific key will not work with a Swarm deployment. The trade-off is between the portability of the common subset and the power of the full specification. The recommendation is to use the common subset for the portable files and the specific keys only when the target tool supports them.


a. The services element

The services element is the only required top-level element. Each service is a container definition, and the service name is the DNS hostname on the Compose network.

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    environment:
      - NGINX_HOST=example.com
    depends_on:
      api:
        condition: service_healthy
    networks:
      - frontend

The service keys fall into several categories. The image and build keys define where the container comes from. The ports key maps host ports to container ports. The volumes key mounts storage. The environment key sets variables. The depends_on key controls the startup order. The networks key attaches the service to networks. The restart key sets the restart policy. The healthcheck key defines the health check.

The build key has its own sub-keys:

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production
      target: production
    image: myapp/api:latest

The context is the build directory, the dockerfile is the file name, the args are the build arguments, and the target is the build stage. The image key names the built image, which is useful when the same image is used by multiple services.

The depends_on key controls the startup order. The short form (depends_on: [db]) waits for the container to start. The long form with condition: service_healthy waits for the healthcheck to pass:

services:
  api:
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

The condition accepts service_started, service_healthy, and service_completed_successfully. The last one waits for the container to exit with code 0, which is useful for initialization services.


b. The networks element

The networks element defines the networks that the services use. A network is a communication channel, and services on the same network can reach each other by name.

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
  backend:

The web service is on the frontend network, the api service is on both the frontend and backend networks, and the db service is on the backend network. The web service can reach the api service, and the api service can reach the db service. The web service cannot reach the db service directly, because they are not on the same network. This is network isolation: a service can only reach the services on its networks.

A network can have a driver and options:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

The bridge driver is the default, and it creates a Linux bridge. The internal: true option makes the network internal, which means it has no external connectivity. A service on an internal network cannot reach the internet, which is useful for a database.

The default network is created automatically if a service does not specify a network. The networks element at the top level defines the custom networks. A service can be attached to multiple networks, and it receives a DNS name on each one.


c. The volumes element

The volumes element defines the persistent storage. A volume is a storage location that survives the container’s lifecycle.

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data
  web:
    volumes:
      - ./html:/usr/share/nginx/html:ro

volumes:
  db-data:

The db-data volume is a named volume, and Docker manages it. The ./html mount is a bind mount, and it maps a host directory into the container. The :ro suffix makes the mount read-only.

A named volume has a driver and options:

volumes:
  db-data:
    driver: local
  cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

The local driver stores the data on the host’s file system. The driver_opts can specify a tmpfs mount, which stores the data in memory and is lost when the host reboots.

The difference between a named volume and a bind mount is important. A named volume is managed by Docker, and it is stored in the Docker area on the host. A bind mount is a host path that is mapped into the container, and the data is stored at the host path. A named volume is the recommended choice for database data, because it is portable and Docker manages the permissions. A bind mount is the recommended choice for source code in development, because the host and the container share the files.


d. The environment element

The environment element passes variables to the container. The element accepts a map or a list, and the values can be literals, host environment variables, or .env file variables.

services:
  api:
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://user:pass@db:5432/appdb
      PORT: 3000

The map form uses KEY: value pairs. The list form uses - KEY=value:

services:
  api:
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://user:pass@db:5432/appdb

The two forms are equivalent, and the choice is a matter of style. The map form is more common in the modern Compose files.

A value can reference a host environment variable:

services:
  api:
    environment:
      DATABASE_URL: ${DATABASE_URL}
      API_KEY: ${API_KEY:?API_KEY is required}

The ${VAR} syntax interpolates the host environment variable. The ${VAR:-default} syntax provides a default value. The ${VAR:?error} syntax fails with an error if the variable is not set. The ${VAR:+replacement} syntax substitutes a replacement if the variable is set.

The values can come from an .env file in the project directory. The .env file is read automatically, and its variables are available for interpolation:

# .env
DATABASE_URL=postgres://user:pass@db:5432/appdb
API_KEY=secret

The environment element can also use the env_file key to load variables from a file:

services:
  api:
    env_file:
      - .env
      - .env.local
    environment:
      NODE_ENV: production

The env_file key loads the variables from the files, and the environment key overrides them. The precedence is: the environment key wins over the env_file, and the env_file wins over the host environment.


Complete Example Session

# ============================================
# PART 1: A BASIC COMPOSE FILE
# ============================================

name: myapp

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"


# ============================================
# PART 2: THE SERVICES ELEMENT
# ============================================

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    environment:
      - NGINX_HOST=example.com
    restart: unless-stopped

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/appdb
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped


# ============================================
# PART 3: THE NETWORKS ELEMENT
# ============================================

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true


# ============================================
# PART 4: THE VOLUMES ELEMENT
# ============================================

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data
  web:
    volumes:
      - ./html:/usr/share/nginx/html:ro

volumes:
  db-data:
    driver: local


# ============================================
# PART 5: THE ENVIRONMENT ELEMENT
# ============================================

services:
  api:
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://app:secret@db:5432/appdb
      PORT: 3000


# ============================================
# PART 6: ENVIRONMENT VARIABLE INTERPOLATION
# ============================================

services:
  api:
    environment:
      DATABASE_URL: ${DATABASE_URL}
      API_KEY: ${API_KEY:?API_KEY is required}
      LOG_LEVEL: ${LOG_LEVEL:-info}
      DEBUG: ${DEBUG:+true}


# ============================================
# PART 7: THE ENV_FILE KEY
# ============================================

services:
  api:
    env_file:
      - .env
      - .env.local
    environment:
      NODE_ENV: production


# ============================================
# PART 8: THE COMPLETE FILE
# ============================================

name: fullstack

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - api
    networks:
      - frontend
    restart: unless-stopped

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    image: myapp/api:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/appdb
      REDIS_URL: redis://cache:6379
      LOG_LEVEL: ${LOG_LEVEL:-info}
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks:
      - frontend
      - backend
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD is required}
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - backend
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    networks:
      - backend
    restart: unless-stopped

volumes:
  db-data:
    driver: local

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true


# ============================================
# PART 9: THE .env FILE
# ============================================

# .env
DB_PASSWORD=secretpassword
LOG_LEVEL=debug


# ============================================
# PART 10: THE CLI COMMANDS
# ============================================

# $ docker compose up -d
# $ docker compose ps
# $ docker compose logs -f api
# $ docker compose exec db psql -U app -d appdb
# $ docker compose down
# $ docker compose down -v

The ten parts show a basic Compose file, the services element, the networks element, the volumes element, the environment element, environment variable interpolation, the env_file key, the complete file, the .env file, and the CLI commands.


Quick Reference

Top-Level Elements

ElementRequiredPurpose
nameNoProject name
servicesYesContainer definitions
networksNoNetwork definitions
volumesNoNamed volume definitions
configsNoConfiguration files
secretsNoSensitive data

Service Keys

KeyPurpose
imageContainer image
buildBuild context
portsPort mappings
volumesStorage mounts
environmentEnvironment variables
env_fileEnvironment file
depends_onStartup dependencies
networksNetwork attachments
restartRestart policy
healthcheckHealth check

Environment Interpolation

SyntaxMeaning
${VAR}Host environment variable
${VAR:-default}Default if unset
${VAR:?error}Error if unset
${VAR:+replacement}Replacement if set
env_fileLoad from a file

Networks and Volumes

FormType
frontend:Named network (bridge driver)
internal: trueNo external connectivity
db-data:Named volume (local driver)
./html:/pathBind mount
./html:/path:roRead-only bind mount

Best Practices

✅ Do This:

# Use the name key for the project name
name: myapp                                                               # ✅
# Use named volumes for database data
volumes:
  - db-data:/var/lib/postgresql/data                                      # ✅
# Use internal networks for databases
networks:
  backend:
    internal: true                                                        # ✅
# Use condition: service_healthy for dependencies
depends_on:
  db:
    condition: service_healthy                                            # ✅
# Use environment interpolation with defaults
LOG_LEVEL: ${LOG_LEVEL:-info}                                             # ✅
# Use env_file for environment-specific values
env_file:
  - .env                                                                  # ✅

❌ Don’t Do This:

# Don't use the deprecated version key
version: '3.8'                                                            # ❌
# Don't use bind mounts for database data
volumes:
  - ./data:/var/lib/postgresql/data  # permission issues                  # ❌
# Don't hardcode secrets in the file
POSTGRES_PASSWORD: secret                                                 # ❌
# Don't use depends_on without a condition for readiness
depends_on:
  - db  # does not wait for readiness                                     # ❌
# Don't put all services on one network
networks:
  - default  # no isolation                                               # ❌

Common Pitfalls

PitfallWhy It HappensFix
Service cannot reach anotherDifferent networksAttach both to the same network
Container starts before dependency is readydepends_on without conditionUse condition: service_healthy
Data lost after down -vVolumes removedOmit -v
Environment variable not setNo .env file or host variableAdd the variable or a default
Permission denied on bind mountHost and container UIDs differUse a named volume
Port conflictTwo services map the same host portChange the host port
Network not isolatedAll services on the default networkDefine custom networks

Real-World Examples

1. Basic Service

services:
  web:
    image: nginx:alpine

2. Service with Build

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile

3. Service with Ports

services:
  web:
    ports:
      - "8080:80"

4. Service with Volumes

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data

5. Service with Environment

services:
  api:
    environment:
      DATABASE_URL: ${DATABASE_URL}

6. Service with Depends On

services:
  api:
    depends_on:
      db:
        condition: service_healthy

7. Network Isolation

networks:
  frontend:
  backend:
    internal: true

8. Named Volume

volumes:
  db-data:
    driver: local

9. Env File

services:
  api:
    env_file:
      - .env

10. Complete File

name: fullstack
services:
  web: { image: nginx }
  api: { build: ./api, depends_on: [db] }
  db: { image: postgres:16, volumes: [db-data:/var/lib/postgresql/data] }
volumes:
  db-data:

Visual

The Compose Specification Structure

┌──────────────────────────────────────────────────────────────┐
│  COMPOSE SPECIFICATION STRUCTURE                             │
│                                                              │
│  compose.yaml                                                │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  name: myapp          ← project name                 │    │
│  │                                                       │    │
│  │  services:            ← required                     │    │
│  │    web:                                              │    │
│  │      image, ports, volumes, environment, ...         │    │
│  │    api:                                              │    │
│  │      build, depends_on, networks, ...                │    │
│  │    db:                                               │    │
│  │      image, volumes, healthcheck, ...                │    │
│  │                                                       │    │
│  │  networks:            ← optional                     │    │
│  │    frontend:                                         │    │
│  │    backend:                                          │    │
│  │                                                       │    │
│  │  volumes:             ← optional                     │    │
│  │    db-data:                                          │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
│  The services element is the only required one.              │
│  The version key is deprecated.                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Network Isolation

┌──────────────────────────────────────────────────────────────┐
│  NETWORK ISOLATION                                           │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  frontend network                                    │    │
│  │  ┌──────────┐      ┌──────────┐                      │    │
│  │  │  web     │─────►│  api     │                      │    │
│  │  │  nginx   │      │  node    │                      │    │
│  │  └──────────┘      └──────────┘                      │    │
│  └──────────────────────────────────────────────────────┘    │
│                              │                               │
│                              │ also on backend               │
│                              ▼                               │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  backend network (internal)                          │    │
│  │  ┌──────────┐      ┌──────────┐                      │    │
│  │  │  api     │─────►│  db      │                      │    │
│  │  │  node    │      │  postgres│                      │    │
│  │  └──────────┘      └──────────┘                      │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
│  web can reach api.                                          │
│  api can reach db.                                           │
│  web cannot reach db directly.                               │
│  The backend network has no external connectivity.           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Environment Precedence

┌──────────────────────────────────────────────────────────────┐
│  ENVIRONMENT PRECEDENCE                                      │
│                                                              │
│  Highest:  environment: key in the service                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  environment:                                        │    │
│  │    NODE_ENV: production                               │    │
│  │                                                       │    │
│  │  This value wins.                                    │    │
│  └──────────────────────────────────────────────────────┘    │
│    ▲                                                         │
│    │                                                         │
│  Middle:  env_file: files                                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  env_file:                                           │    │
│  │    - .env                                             │    │
│  │                                                       │    │
│  │  This value is overridden by environment.            │    │
│  └──────────────────────────────────────────────────────┘    │
│    ▲                                                         │
│    │                                                         │
│  Lowest:  host environment and .env interpolation            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  DATABASE_URL: ${DATABASE_URL}                       │    │
│  │                                                       │    │
│  │  The host variable or .env value is used.            │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Volume Types

┌──────────────────────────────────────────────────────────────┐
│  VOLUME TYPES                                                │
│                                                              │
│  NAMED VOLUME:                                               │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  volumes:                                            │    │
│  │    - db-data:/var/lib/postgresql/data                │    │
│  │                                                       │    │
│  │  volumes:                                            │    │
│  │    db-data:                                          │    │
│  │      driver: local                                   │    │
│  │                                                       │    │
│  │  Docker manages the storage.                         │    │
│  │  Portable. Recommended for database data.            │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
│  BIND MOUNT:                                                 │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  volumes:                                            │    │
│  │    - ./html:/usr/share/nginx/html:ro                 │    │
│  │                                                       │    │
│  │  The host directory is mapped into the container.    │    │
│  │  Shared between host and container.                  │    │
│  │  Recommended for source code in development.         │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Summary

ItemValue
servicesThe only required top-level element
networksCommunication channels; default bridge
volumesPersistent storage; named and bind
environmentVariables passed to the container
env_fileLoad variables from a file
nameProject name; prefixes resources
versionDeprecated; omit it
depends_onStartup order; use service_healthy for readiness
internal: trueNetwork with no external connectivity

Key takeaways:

  • The Compose specification defines the top-level elements. The services element is required, and the networks, volumes, configs, and secrets elements are optional. The name key sets the project name, and the version key is deprecated.
  • The services element defines the containers. Each service has an image or a build key, and the service name is the DNS hostname on the Compose network. The ports, volumes, environment, depends_on, networks, restart, and healthcheck keys configure the container.
  • The networks element defines the communication channels. Services on the same network can reach each other by name. A service can be on multiple networks, and the internal: true option creates a network with no external connectivity.
  • The volumes element defines the persistent storage. A named volume is managed by Docker and is the recommended choice for database data. A bind mount maps a host directory into the container and is the recommended choice for source code in development.
  • The environment element passes variables to the container. The element accepts a map or a list, and the values can be literals, host environment variables, or .env file variables. The interpolation syntax provides defaults and error checking.
  • The environment precedence is: environment > env_file > host environment. The environment key in the service wins over the env_file, and the env_file wins over the host environment and the .env interpolation.
  • The depends_on key controls the startup order. The short form waits for the container to start. The long form with condition: service_healthy waits for the healthcheck to pass, which is the correct pattern for services that need their dependencies to be ready.
  • The project name prefixes all created resources. The name is set by the -p flag, the COMPOSE_PROJECT_NAME environment variable, the name key, or the directory name. The name key is the recommended way because it is committed with the file.

Remember: The Compose specification is the schema for the compose.yaml file. The services element is the only required one, and it defines the containers. The networks element defines the communication channels, and the internal: true option isolates a network from the internet. The volumes element defines the persistent storage, and the choice between a named volume and a bind mount depends on whether the data is managed by Docker or shared with the host. The environment element passes variables to the container, and the precedence is environment over env_file over the host. The name key sets the project name, and the version key is deprecated. The specification is the standard, and a file that conforms to it is portable across the tools that implement it.


Was this helpful?


Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!