375 lines
11 KiB
Markdown
375 lines
11 KiB
Markdown
---
|
|
created: '2026-04-15T18:11:45+00:00'
|
|
id: 9ee96ac8-e1ff-4946-b08f-680be1d1b2bb
|
|
keywords:
|
|
- 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
|
|
links: []
|
|
modified: '2026-04-15T18:11:45+00:00'
|
|
summary: 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).
|
|
tags:
|
|
- reference
|
|
- docker
|
|
- compose
|
|
- containers
|
|
- devops
|
|
- orchestration
|
|
title: 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
|
|
|
|
```yaml
|
|
services:
|
|
web:
|
|
build: .
|
|
ports:
|
|
- "5000:5000"
|
|
volumes:
|
|
- .:/code
|
|
environment:
|
|
FLASK_ENV: development
|
|
redis:
|
|
image: "redis:alpine"
|
|
```
|
|
|
|
---
|
|
|
|
## Advanced Example
|
|
|
|
```yaml
|
|
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: {}
|
|
``` |