Getting started
Introduction
Docker Compose defines and runs multi-container applications from a Compose file. This reference covers the Compose file format and CLI.
- Compose file reference (docs.docker.com)
- Docker CLI cheatsheet (devhints.io)
Basic example
compose.yaml
services:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
depends_on:
- redis
redis:
image: redis:8
Compose reads compose.yaml by default; docker-compose.yml also works. The top-level version field is obsolete.
See: Compose quickstart
Compose versions
docker-compose up -d # v1, retired
docker compose up -d # current plugin
Compose v1 is retired; use the docker compose plugin (currently v5).
Commands
| Command | Description |
|---|---|
docker compose up -d | Create and start in background |
docker compose up --wait | Wait for services to be running or healthy |
docker compose down | Stop and remove containers and networks |
docker compose ps | List project containers |
docker compose logs -f web | Follow service logs |
docker compose exec web sh | Run a command in a service |
docker compose run --rm web sh | Run a one-off command |
docker compose build | Build or rebuild images |
docker compose pull | Pull service images |
docker compose push | Push service images |
docker compose restart | Restart services |
docker compose stop / start | Stop or start services |
docker compose config | Render the resolved configuration |
docker compose ls | List running projects |
docker compose watch | Sync or rebuild on changes |
Global flags: -f FILE, -p NAME, --profile NAME, --env-file FILE.
Services
Building and images
services:
web:
build: .
services:
web:
build:
context: ./dir
dockerfile: Dockerfile.dev
args:
APP_HOME: app
A context path builds from ./Dockerfile; the mapping form adds a Dockerfile and build arguments.
services:
web:
image: ghcr.io/example/app:1.0
image accepts a registry path, tag, or digest.
See: build
Ports
Command and entrypoint
services:
web:
command: bundle exec thin -p 3000
services:
web:
entrypoint: ["/app/start.sh"]
command overrides the image's CMD; entrypoint overrides its ENTRYPOINT. Both accept a string or list.
See: command and entrypoint
Environment
services:
web:
environment:
RACK_ENV: development
services:
web:
env_file:
- .env
- .development.env
Environment values can use a mapping or a list. env_file loads variables from files.
See: environment
Dependencies
services:
web:
depends_on:
- db
services:
web:
depends_on:
db:
condition: service_healthy
restart: true
Long syntax waits for health or successful completion and can restart dependents.
services:
web:
links:
- db:database
Links add an alias and implicit dependency; networks are preferred.
See: depends_on and links
Runtime
Restart and resources
services:
web:
restart: unless-stopped
services:
web:
deploy:
resources:
limits:
cpus: "0.50"
memory: 512M
Policies: no, always, on-failure, unless-stopped. deploy.resources.limits caps CPUs and memory.
See: restart and deploy resources
Healthcheck
services:
web:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
start_interval: 5s
test accepts CMD, CMD-SHELL, or NONE; start_interval sets the probe rate during startup.
See: healthcheck
User
Devices
services:
web:
devices:
- "/dev/ttyUSB0:/dev/ttyUSB0"
Maps host devices into the container.
See: devices
Labels
services:
web:
labels:
com.example.description: "Accounting web app"
Labels add metadata to containers.
See: labels
Networking and storage
Networks
services:
web:
networks:
- frontend
networks:
frontend:
Creates a frontend network and attaches web to it.
See: networks
External networks
networks:
frontend:
external: true
name: shared_frontend
external: true uses a network Compose does not create; name is its actual name.
See: external networks
DNS and hosts
services:
web:
dns:
- 8.8.8.8
- 8.8.4.4
extra_hosts:
- "somehost=192.168.1.100"
dns sets resolvers; extra_hosts adds /etc/hosts entries.
See: dns and extra_hosts
Volumes
services:
db:
image: postgres:18
volumes:
- dbdata:/var/lib/postgresql
volumes:
dbdata:
Named volumes persist data; bind mounts use a host path such as ./data:/data.
See: volumes
Secrets
services:
web:
secrets:
- my_secret
secrets:
my_secret:
file: ./my_secret.txt
Secrets mount at /run/secrets/<name> and are read-only.
See: secrets
Configs
services:
web:
configs:
- http_config
configs:
http_config:
file: ./httpd.conf
Configs mount non-sensitive files at /<name> by default.
See: configs
External links
services:
web:
external_links:
- redis_1
- project_db_1:mysql
Links containers from another Compose application.
See: external_links
Composition
Profiles
services:
debug:
image: busybox
profiles: ["debug"]
Run with docker compose --profile debug up.
See: profiles
Watch
services:
web:
develop:
watch:
- action: sync
path: ./src
target: /app/src
- action: rebuild
path: package.json
Syncs files and rebuilds on changes. Run docker compose watch.
See: Compose Watch
Include
include:
- common.yaml
services:
web:
image: nginx:stable
Loads another Compose file into the project. Include can also fetch OCI or Git sources.
See: include
Extends
services:
web:
extends:
file: common.yml
service: webapp
Reuses a service definition from another file.
See: extends
Merge overrides
compose.override.yaml
services:
app:
ports: !override
- "8443:443"
environment:
FOO: !reset null
The override file merges into the base; !reset clears a value
and !override replaces it instead of appending.
See: Merge Compose files
0 Comments for this cheatsheet. Write yours!