📖 Guide
Docker Compose — Complete Reference
Docker Compose cheat sheet covering CLI commands, service configuration, networking, volumes, environment variables, and common patterns.
77 commands across 9 categories
CLI CommandsService ConfigurationNetworkingVolumesEnvironment VariablesBuildHealth ChecksProfilesCommon Patterns
CLI Commands
| Command | Description |
|---|---|
docker compose up | Create and start all services |
docker compose up -d | Start services in detached (background) mode |
docker compose up --build | Rebuild images before starting |
docker compose down | Stop and remove containers, networks |
docker compose down -v | Stop and also remove named volumes |
docker compose ps | List running containers for the project |
docker compose logs -f web | Follow logs for a specific service |
docker compose exec web sh | Open a shell in a running service container |
docker compose run web npm test | Run a one-off command in a new container |
docker compose restart web | Restart a specific service |
docker compose pull | Pull latest images for all services |
docker compose config | Validate and view the resolved Compose file |
Service Configuration
| Command | Description |
|---|---|
image: postgres:16-alpine | Use a pre-built image from a registry |
build: ./app | Build image from a Dockerfile in the specified directory |
ports:
- '3000:3000' | Map host port to container port |
ports:
- '127.0.0.1:5432:5432' | Bind to localhost only (not exposed externally) |
expose:
- '3000' | Expose port to other services only (not host) |
depends_on:
- db
- redis | Start services in dependency order |
depends_on:
db:
condition: service_healthy | Wait for dependency to be healthy before starting |
restart: unless-stopped | Restart policy (no, always, on-failure, unless-stopped) |
command: ['node', 'server.js'] | Override the default container command |
entrypoint: /entrypoint.sh | Override the container entrypoint |
Networking
| Command | Description |
|---|---|
networks:
frontend:
backend: | Define custom networks at top level |
services:
web:
networks:
- frontend
- backend | Attach a service to specific networks |
networks:
backend:
driver: bridge | Set network driver (bridge is default) |
networks:
proxy:
external: true | Use a pre-existing external network |
http://db:5432 | Services communicate using service name as hostname |
services:
web:
network_mode: host | Use host networking (no port mapping needed) |
networks:
internal:
internal: true | Create an isolated network with no external access |
services:
web:
dns:
- 8.8.8.8 | Set custom DNS servers for a service |
Volumes
| Command | Description |
|---|---|
volumes:
- ./src:/app/src | Bind mount: sync host directory into container |
volumes:
- postgres_data:/var/lib/postgresql/data | Named volume: persist data across restarts |
volumes:
postgres_data: | Define a named volume at top level |
volumes:
- ./config.yml:/app/config.yml:ro | Read-only bind mount |
volumes:
- /app/node_modules | Anonymous volume: prevent host overwrite of container path |
volumes:
data:
external: true | Use a pre-existing external volume |
docker compose down -v | Remove named volumes when stopping |
docker volume ls | List all Docker volumes |
docker volume prune | Remove all unused volumes |
Environment Variables
| Command | Description |
|---|---|
environment:
- NODE_ENV=production
- DEBUG=app:* | Set environment variables inline |
environment:
NODE_ENV: production
DB_HOST: db | Set environment variables as a map |
env_file:
- .env | Load variables from an env file |
env_file:
- .env
- .env.local | Load from multiple env files (later overrides earlier) |
image: 'postgres:${PG_VERSION:-16}' | Use variable substitution with default value |
docker compose --env-file .env.prod up | Specify env file for variable substitution |
environment:
DB_PASSWORD: ${DB_PASSWORD:?error msg} | Require a variable (error if unset) |
Build
| Command | Description |
|---|---|
build:
context: .
dockerfile: Dockerfile.prod | Specify build context and custom Dockerfile |
build:
args:
NODE_VERSION: '20' | Pass build arguments to Dockerfile |
build:
target: production | Build a specific stage of a multi-stage Dockerfile |
build:
cache_from:
- 'myapp:latest' | Use an existing image as build cache |
build:
platforms:
- linux/amd64
- linux/arm64 | Build for multiple platforms |
docker compose build --no-cache | Rebuild without using cache |
docker compose build --parallel | Build multiple services in parallel |
build:
context: .
additional_contexts:
shared: ../shared | Add extra build contexts (Compose v2.17+) |
Health Checks
| Command | Description |
|---|---|
healthcheck:
test: ['CMD', 'curl', '-f', 'http://localhost:3000/health'] | HTTP health check |
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U postgres'] | Database readiness check |
healthcheck:
interval: 30s | Time between health checks (default 30s) |
healthcheck:
timeout: 10s | Max time for a single check to complete |
healthcheck:
retries: 3 | Consecutive failures needed to mark unhealthy |
healthcheck:
start_period: 40s | Grace period before checks count |
healthcheck:
disable: true | Disable health check from base image |
docker compose ps | View container health status in the status column |
Profiles
| Command | Description |
|---|---|
services:
debug:
profiles:
- debug | Assign a service to a profile (won't start by default) |
docker compose --profile debug up | Start services including a specific profile |
docker compose --profile debug --profile monitoring up | Enable multiple profiles |
COMPOSE_PROFILES=debug,monitoring docker compose up | Enable profiles via environment variable |
services:
web:
# no profiles = always starts | Services without profiles start with every 'up' |
services:
seed:
profiles: [tools]
depends_on: [db] | Tool/utility service that only runs on demand |
Common Patterns
| Command | Description |
|---|---|
docker compose -f compose.yml -f compose.prod.yml up | Override/merge multiple Compose files |
docker compose up -d --scale worker=3 | Run multiple instances of a service |
docker compose cp web:/app/logs ./logs | Copy files from a container to host |
docker compose top | Display running processes for each service |
docker compose watch | Auto-rebuild and restart on file changes (Compose v2.22+) |
deploy:
resources:
limits:
memory: 512M
cpus: '0.5' | Limit CPU and memory for a service |
logging:
driver: json-file
options:
max-size: '10m'
max-file: '3' | Configure log rotation |
docker compose alpha dry-run up | Preview what would happen without executing |
include:
- ./monitoring/compose.yml | Include another Compose file (v2.20+) |
📖 Free, searchable command reference. Bookmark this page for quick access.