vh/VuongKB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Create: reference/docker-compose.md

Browse Source
This commit is contained in:
Atlas
2026-04-15 11:11:45 -07:00
parent 442c4bf50c
commit 991848f871
1 changed files with 375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reference/docker-compose.md
+375
View File
@@ -0,0 +1,375 @@
---
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: {}
```