Docker Compose Cheat Sheet
Complete reference for Docker Compose CLI commands and docker-compose.yml configuration. Covers services, networking, volumes, health checks, deploy options, and environment variable substitution.
| Command | Description |
|---|
docker compose up | Create and start all services defined in the Compose file |
docker compose up -d | Start all services in detached (background) mode |
docker compose up --build | Rebuild images before starting services |
docker compose down | Stop and remove containers, networks created by up |
docker compose down -v | Stop and also remove named volumes declared in the file |
docker compose build | Build or rebuild all service images without starting |
docker compose ps | List containers managed by the current Compose project |
docker compose logs -f <svc> | Follow (tail) logs from a specific service |
docker compose exec <svc> sh | Open a shell inside a running service container |
docker compose restart <svc> | Restart one or more services |
docker compose pull | Pull the latest images for all services |
docker compose push | Push service images to their configured registries |
docker compose config | Validate and display the resolved Compose configuration |
docker compose run <svc> <cmd> | Run a one-off command in a new service container |
| Top-Level Key | Description |
|---|
services: | Define application containers (required) |
networks: | Create custom networks for inter-service communication |
volumes: | Declare named volumes for persistent data storage |
configs: | Define configuration objects accessible by services |
secrets: | Define sensitive data (passwords, keys) mounted into services |
name: | Set a custom project name (overrides directory-based default) |
| Key | Description |
|---|
image: nginx:alpine | Specify the image to start the container from |
build: ./app | Build image from Dockerfile in the given path |
build:
context: .
dockerfile: Dockerfile.dev | Build with custom context and Dockerfile name |
ports:
- "8080:80" | Map host port 8080 to container port 80 |
volumes:
- ./data:/app/data | Bind mount a host directory into the container |
environment:
- NODE_ENV=production | Set environment variables (list syntax) |
env_file: .env | Load environment variables from an external file |
depends_on:
- db | Start this service only after the listed services |
restart: unless-stopped | Restart policy: no, always, on-failure, unless-stopped |
command: ["npm", "start"] | Override the default CMD from the image |
entrypoint: /entrypoint.sh | Override the default ENTRYPOINT from the image |
working_dir: /app | Set the working directory inside the container |
container_name: my-app | Assign a custom name to the container |
| Syntax | Description |
|---|
ports:
- "3000:3000" | Map host:container port (published to host) |
ports:
- "127.0.0.1:3000:3000" | Bind to localhost only (not exposed externally) |
expose:
- "3000" | Expose port to other services only (not to host) |
networks:
- frontend
- backend | Attach the service to specific networks |
networks:
backend:
aliases:
- api | Set a network alias so other services can reach this as "api" |
links:
- db:database | Link to another service with an alias (legacy, prefer networks) |
| Syntax | Description |
|---|
volumes:
- mydata:/var/lib/data | Mount a named volume into the container |
volumes:
- ./src:/app/src | Bind mount: map host path to container path |
volumes:
- ./src:/app/src:ro | Bind mount as read-only inside the container |
tmpfs:
- /tmp | Mount a tmpfs (in-memory) filesystem |
volumes:
mydata:
driver: local | Top-level named volume with the local driver |
volumes:
mydata:
external: true | Use a pre-existing volume not managed by Compose |
| Key | Description |
|---|
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"] | Command to check if the service is healthy |
interval: 30s | Time between health check attempts |
timeout: 10s | Maximum time to wait for a check to complete |
retries: 3 | Consecutive failures needed to mark as unhealthy |
start_period: 40s | Grace period for the container to initialize before checks count |
test: ["CMD-SHELL", "pg_isready -U postgres"] | Use CMD-SHELL to run the check through a shell |
depends_on:
db:
condition: service_healthy | Wait for dependency to be healthy before starting |
| Key | Description |
|---|
deploy:
replicas: 3 | Run 3 instances of the service |
resources:
limits:
cpus: "0.5"
memory: 512M | Set maximum CPU and memory a container can use |
resources:
reservations:
cpus: "0.25"
memory: 256M | Reserve minimum CPU and memory for the container |
restart_policy:
condition: on-failure
max_attempts: 3 | Restart on failure up to 3 times (Swarm mode) |
placement:
constraints:
- node.role == manager | Constrain service to run on specific nodes (Swarm) |
| Syntax | Description |
|---|
environment:
- DEBUG=true | Set variable using list syntax |
environment:
DEBUG: "true" | Set variable using map syntax |
env_file:
- .env
- .env.local | Load variables from one or more files |
${VARIABLE} | Substitute a shell or .env variable into the Compose file |
${VARIABLE:-default} | Use "default" if VARIABLE is unset or empty |
${VARIABLE-default} | Use "default" only if VARIABLE is unset |
${VARIABLE:?error msg} | Exit with error message if VARIABLE is unset or empty |