Docker 41 🐳 Docker Compose Specification: services, networks, volumes, and environment
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
| Element | Required | Purpose |
|---|---|---|
name | No | Project name |
services | Yes | Container definitions |
networks | No | Network definitions |
volumes | No | Named volume definitions |
configs | No | Configuration files |
secrets | No | Sensitive data |
Service Keys
| Key | Purpose |
|---|---|
image | Container image |
build | Build context |
ports | Port mappings |
volumes | Storage mounts |
environment | Environment variables |
env_file | Environment file |
depends_on | Startup dependencies |
networks | Network attachments |
restart | Restart policy |
healthcheck | Health check |
Environment Interpolation
| Syntax | Meaning |
|---|---|
${VAR} | Host environment variable |
${VAR:-default} | Default if unset |
${VAR:?error} | Error if unset |
${VAR:+replacement} | Replacement if set |
env_file | Load from a file |
Networks and Volumes
| Form | Type |
|---|---|
frontend: | Named network (bridge driver) |
internal: true | No external connectivity |
db-data: | Named volume (local driver) |
./html:/path | Bind mount |
./html:/path:ro | Read-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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Service cannot reach another | Different networks | Attach both to the same network |
| Container starts before dependency is ready | depends_on without condition | Use condition: service_healthy |
Data lost after down -v | Volumes removed | Omit -v |
| Environment variable not set | No .env file or host variable | Add the variable or a default |
| Permission denied on bind mount | Host and container UIDs differ | Use a named volume |
| Port conflict | Two services map the same host port | Change the host port |
| Network not isolated | All services on the default network | Define 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
| Item | Value |
|---|---|
services | The only required top-level element |
networks | Communication channels; default bridge |
volumes | Persistent storage; named and bind |
environment | Variables passed to the container |
env_file | Load variables from a file |
name | Project name; prefixes resources |
version | Deprecated; omit it |
depends_on | Startup order; use service_healthy for readiness |
internal: true | Network with no external connectivity |
Key takeaways:
- The Compose specification defines the top-level elements. The
serviceselement is required, and thenetworks,volumes,configs, andsecretselements are optional. Thenamekey sets the project name, and theversionkey is deprecated. - The
serviceselement defines the containers. Each service has animageor abuildkey, and the service name is the DNS hostname on the Compose network. Theports,volumes,environment,depends_on,networks,restart, andhealthcheckkeys configure the container. - The
networkselement defines the communication channels. Services on the same network can reach each other by name. A service can be on multiple networks, and theinternal: trueoption creates a network with no external connectivity. - The
volumeselement 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
environmentelement passes variables to the container. The element accepts a map or a list, and the values can be literals, host environment variables, or.envfile variables. The interpolation syntax provides defaults and error checking. - The environment precedence is:
environment>env_file> host environment. Theenvironmentkey in the service wins over theenv_file, and theenv_filewins over the host environment and the.envinterpolation. - The
depends_onkey controls the startup order. The short form waits for the container to start. The long form withcondition: service_healthywaits 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
-pflag, theCOMPOSE_PROJECT_NAMEenvironment variable, thenamekey, or the directory name. Thenamekey 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.
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!