VuongKB/reference/docker-compose.md

created, id, keywords, links, modified, summary, tags, title

created	id	keywords	links	modified	summary	tags	title
2026-04-15T18:11:45+00:00	9ee96ac8-e1ff-4946-b08f-680be1d1b2bb	docker compose compose.yaml compose.yml docker-compose multi-container services networks volumes build environment variables depends_on docker documentation compose specification configs secrets deploy healthcheck docker compose up docker compose down docker compose build docker compose watch		2026-04-15T18:11:45+00:00	Comprehensive reference for Docker Compose covering the Compose file specification (compose.yaml), all top-level elements (services, networks, volumes, configs, secrets), key CLI commands, build specification, environment variable interpolation, and usage examples. Derived from official Docker documentation (docs.docker.com).	reference docker compose containers devops orchestration	Docker Compose Reference

Docker Compose Reference

Overview

Docker Compose is a tool for defining and running multi-container applications. You use a YAML configuration file (compose.yaml) to configure your application's services, networks, and volumes. Then with a single command (docker compose up), you create and start all services from your configuration.

Compose works in all environments: production, staging, development, testing, and CI workflows. It manages the whole lifecycle: start, stop, rebuild, view status, stream logs, run one-off commands.

Source: Official Docker Compose documentation — https://docs.docker.com/compose/ | https://docs.docker.com/reference/compose-file/ | Fetched: July 2025

---

Compose File (compose.yaml)

Aspect	Detail
Default path	compose.yaml (preferred) or compose.yml
Legacy paths	docker-compose.yaml and docker-compose.yml (backwards compatibility)
Conflict resolution	If both canonical and legacy exist, Compose prefers compose.yaml
Merging	Multiple Compose files can be merged; simple attributes are overridden by the highest-order file, lists are merged by appending
include	Reference other Compose files from different teams
extends	Share common configurations among services (supports file and service keys)

---

Top-Level Elements

The Compose Specification defines the following top-level elements:

services (required)

A map whose keys are service names and values are service definitions. Key service attributes include:

Core

Attribute	Description
image	Docker image to use
build	Build config (context, dockerfile, args, target, cache_from/cache_to, tags, secrets, ssh, network, no_cache, platforms, etc.)
command	Overrides default CMD from image
entrypoint	Overrides default ENTRYPOINT from image
container_name	Custom container name (prevents scaling)
hostname	Custom hostname (must be valid RFC 1123)
domainname	Custom domain name

Networking

Attribute	Description
ports	Publish ports (HOST:CONTAINER format)
expose	Expose ports to linked services only (not published to host)
networks	Networks to join
network_mode	Special network mode (host, none, service:name)
dns	Custom DNS servers
dns_opt	DNS options
dns_search	DNS search domains
extra_hosts	Additional hostname mappings

Storage

Attribute	Description
volumes	Volume mounts (supports short and long syntax with type, source, target, read_only, etc.)
volumes_from	Mount volumes from another service/container
tmpfs	Temporary filesystem mounts

Dependencies & Ordering

Attribute	Description
depends_on	Control startup/shutdown order. Short syntax: service names. Long syntax: condition (service_started, service_healthy, service_completed_successfully), required (bool), restart (bool)

Configuration & Secrets

Attribute	Description
environment	Container environment variables (map or array syntax)
env_file	Files containing environment variables (supports required and format attributes)
configs	Grant access to configs (short or long syntax with source, target, uid, gid, mode)
secrets	Grant access to secrets (short or long syntax)

Resource Limits

Attribute	Description
cpu_count, cpu_percent, cpu_shares	CPU allocation controls
cpu_period, cpu_quota	CPU throttling
cpu_rt_runtime, cpu_rt_period	Real-time CPU scheduling
cpus, cpuset	CPU count and affinity
mem_limit, mem_reservation	Memory limits
mem_swappiness, memswap_limit	Swap controls
blkio_config	Block I/O limits (weight, weight_device, device_read/write_bps, device_read/write_iops)
pids_limit	Process ID limit

Health & Lifecycle

Attribute	Description
healthcheck	Container health check configuration
restart	Restart policy (no, always, on-failure, unless-stopped)
stop_grace_period	Grace period before SIGKILL
stop_signal	Signal to send on stop
init	Run an init process inside the container
post_start, pre_stop	Lifecycle hooks

Security & Isolation

Attribute	Description
cap_add, cap_drop	Linux capabilities
security_opt	Security options
privileged	Give full access to host
read_only	Read-only root filesystem
user	Username/UID
group_add	Additional groups
userns_mode	User namespace mode
cgroup, cgroup_parent	Cgroup settings
isolation	Container isolation technology
devices	Device mappings
device_cgroup_rules	Device cgroup rules

Logging

Attribute	Description
logging	Logging configuration with driver and options

Other

Attribute	Description
labels	Metadata labels
annotations	Container annotations
scale	Scale to N containers
profiles	Service profiles for selective startup
platform	Target platform
pull_policy	Image pull policy
runtime	Container runtime
shm_size	Shared memory size
stdin_open, tty	Interactive mode
ulimits	System ulimit settings
sysctls	Kernel parameters
working_dir	Working directory inside container
extends	Extend another service's configuration
deploy	Deployment config (replicas, update_config, rollback_config, resources, restart_policy, placement, labels, mode)
develop	Development config (Compose Watch)
models	AI model configuration (Compose Model Runner)

---

networks

Define named networks for service communication.

Attribute	Description
driver	bridge (default), overlay, host, none, or custom
driver_opts	Driver-specific options
attachable	Allow standalone containers to attach (for overlay networks)
external	Reference an existing network
internal	No external connectivity
enable_ipv4, enable_ipv6	IP version support
ipam	Custom IPAM config (driver, config with subnet/ip_range/gateway/aux_addresses, options)
labels	Metadata
name	Custom network name

Default network: When no networks are declared, Compose creates an implicit default network. All services without explicit networks join it.

---

volumes

Define named volumes for persistent data.

Attribute	Description
driver	Volume driver
driver_opts	Driver-specific options (e.g., NFS config)
external	Reference an existing volume
labels	Metadata
name	Custom volume name

---

configs

Runtime configuration data mounted as files into containers.

Attribute	Description
file	File containing config content
external	Reference existing config
name	Custom name
labels	Metadata

---

secrets

Sensitive data (passwords, keys, certificates) mounted as files.

Attribute	Description
file	File containing secret content
external	Reference existing secret
name	Custom name
labels	Metadata

---

name (top-level)

Project name used to group and isolate resources.

---

Key Commands

Command	Description
docker compose up	Create and start all services
docker compose up -d	Run in detached (background) mode
docker compose down	Stop and remove containers, networks
docker compose down --volumes	Also remove volumes
docker compose build	Build or rebuild services
docker compose start	Start existing services
docker compose stop	Stop services (without removing)
docker compose restart	Restart services
docker compose ps	List running services and their status
docker compose logs	View service logs
docker compose exec	Execute command in running container
docker compose run	Run a one-off command on a service
docker compose config	Validate and view the Compose file
docker compose pull	Pull service images
docker compose push	Push service images
docker compose watch	Watch for file changes and sync (development)
docker compose scale	Scale services

---

Compose Build Specification

The build section defines how to build images from source:

Attribute	Description
context	Build context path or Git URL
dockerfile / dockerfile_inline	Alternate Dockerfile
args	Build arguments (ARG values)
target	Multi-stage build target
cache_from, cache_to	Build cache sources/targets
secrets	Build-time secrets
ssh	SSH authentication for builds
network	Network for RUN instructions
no_cache	Disable cache
tags	Additional image tags
platforms	Target platforms
additional_contexts	Named build contexts
labels	Image labels
ulimits	Build ulimits
entitlements, privileged, isolation	Security settings
provenance, sbom	Attestation settings
shm_size	Shared memory for build

---

Environment Variables & Interpolation

• Variables in compose.yaml use ${VARIABLE:-default} syntax
• env_file loads from files; environment takes precedence
• .env file in project directory provides default values
• Compose-specific variables: COMPOSE_PROJECT_NAME, COMPOSE_FILE, COMPOSE_PROFILES, COMPOSE_PATH_SEPARATOR, etc.

---

Quickstart Example

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
    environment:
      FLASK_ENV: development
  redis:
    image: "redis:alpine"

---

Advanced Example

services:
  frontend:
    image: example/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: example/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  front-tier: {}
  back-tier: {}