Docker Compose
Define and run multi-container applications with a single docker-compose.yml file.
What you'll learn
- What Docker Compose is and when to use it
- Writing a docker-compose.yml file
- Services, networks, and volumes
- Common compose commands
Concept
What Is Docker Compose?
Docker Compose is a tool for defining and running multi-container Docker applications. Instead of running multiple docker run commands with long lists of flags, you describe your entire application — services, networks, volumes — in a single docker-compose.yml file. Then one command, docker compose up, starts everything together. Compose is perfect for local development environments, CI pipelines, and small production deployments.
The Compose File
A docker-compose.yml file uses YAML syntax. Each service defines a container: which image to use, what ports to map, what volumes to mount, and what environment variables to set. You can also define custom networks for services to communicate and named volumes for persistent data. The file is version-controlled, so your entire development environment is reproducible by anyone on the team.
Services and Dependencies
Compose lets you express dependencies between services with depends_on. If your web app depends on a database, you can ensure the database starts first. You can also define health checks so Compose waits until a service is actually ready to accept connections, not just started. Environment variables can be loaded from .env files, and you can override settings with docker-compose.override.yml for local development.
Common Commands
docker compose up starts all services (add -d for detached). docker compose down stops and removes them. docker compose logs shows all logs. docker compose build rebuilds images. docker compose exec web sh opens a shell in a service. These commands manage your entire application stack as a unit, which is much simpler than managing containers individually.
Compose in Production
While Compose is primarily a development tool, it can be used in production with Docker Swarm (docker stack deploy -c docker-compose.yml myapp). For larger production deployments, Kubernetes is preferred, but Compose is excellent for small services, CI environments, and local development. Use docker-compose.override.yml for environment-specific changes — the base file defines the common configuration, and the override adds development-only settings like debug ports and volume mounts for hot reloading.
Example
# docker-compose.yml — a web app with a database
services:
web:
build: .
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgres://user:pass@db:5432/app
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user"]
interval: 5s
volumes:
pgdata:
This compose file defines a web service and a database. The web service waits for the database health check before starting. The pgdata volume persists database data.
Try it
- Docker Compose Generator
Generate Docker Compose files visually.
- YAML Validator
Validate compose file syntax.
- YAML to JSON
Convert compose YAML to JSON for inspection.
Common mistakes
The mistake
Using depends_on without health checks
The fix
depends_on only waits for a container to start, not to be ready. Add a healthcheck so Compose waits until the service can actually accept connections.
The mistake
Not pinning image versions in compose files
The fix
Use specific versions like postgres:16 instead of postgres:latest. Unpinned images lead to unpredictable behavior when new versions are released.
Practice Docker Compose
2 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.