From 991848f871b0e19c63bbed1324bfa14f1f055a1b Mon Sep 17 00:00:00 2001 From: Atlas Date: Wed, 15 Apr 2026 11:11:45 -0700 Subject: [PATCH] Create: reference/docker-compose.md --- reference/docker-compose.md | 375 ++++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 reference/docker-compose.md diff --git a/reference/docker-compose.md b/reference/docker-compose.md new file mode 100644 index 0000000..55da163 --- /dev/null +++ b/reference/docker-compose.md @@ -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: {} +``` \ No newline at end of file