Docker Compose Basics
Define and run multi-container applications with a single YAML file
Skills taught: docker.compose, docker.compose-yaml, docker.services, docker.depends-on
What is Docker Compose?
Running a modern application typically means running several containers together: an API server, a database, a cache, a message queue. Typing five docker run commands with all their flags is tedious, error-prone, and impossible to share. Docker Compose lets you define your entire multi-service stack in a single docker-compose.yml file, then start everything with one command: docker compose up.
A complete docker-compose.yml
# docker-compose.yml — a full-stack web app: API + PostgreSQL + Redis
services:
# ── API server ────────────────────────────────────────────
api:
build: . # build from Dockerfile in current dir
image: myapp-api:dev # name the built image
container_name: myapp-api
ports:
- "3000:3000" # host:container
environment:
NODE_ENV: development
DATABASE_URL: postgres://postgres:secret@postgres:5432/myapp
REDIS_URL: redis://redis:6379
env_file:
- .env.local # override with local env file
volumes:
- ./src:/app/src # bind mount for hot reload
depends_on:
postgres:
condition: service_healthy # wait until postgres passes healthcheck
redis:
condition: service_started
restart: unless-stopped
# ── PostgreSQL database ───────────────────────────────────
postgres:
image: postgres:16-alpine
container_name: myapp-postgres
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: secret
POSTGRES_DB: myapp
volumes:
- postgres-data:/var/lib/postgresql/data # named volume — data persists
- ./init.sql:/docker-entrypoint-initdb.d/init.sql # auto-run on first start
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
restart: unless-stopped
# ── Redis cache ───────────────────────────────────────────
redis:
image: redis:7-alpine
container_name: myapp-redis
volumes:
- redis-data:/data
restart: unless-stopped
# Named volumes (persists data across compose down/up)
volumes:
postgres-data:
redis-data:
Essential Compose commands
# Start all services (in background)
docker compose up -d
# Start and rebuild images (after Dockerfile changes)
docker compose up -d --build
# Start specific services only
docker compose up -d api redis
# Stop all services (containers stop, data preserved)
docker compose down
# Stop AND delete volumes (nuclear — deletes all data!)
docker compose down -v
# View logs for all services
docker compose logs -f
# View logs for a specific service
docker compose logs -f api
# Open a shell in a running service
docker compose exec api sh
docker compose exec postgres psql -U postgres myapp
# List running services
docker compose ps
# Run a one-off command in a service
docker compose run --rm api npm run migrate
Tip: docker compose vs docker-compose: The old standalone docker-compose (v1, Python) is deprecated. Use docker compose (space, no hyphen) — the v2 plugin built into Docker CLI. It's faster, has better error messages, and supports the latest features.
Frequently Asked Questions
How do services reach each other in Compose?
Docker Compose automatically creates a custom network for all services and makes each service reachable by its service name as a hostname. In the example above, the api service reaches PostgreSQL at 'postgres:5432' — no network: config needed. This is one of Compose's biggest conveniences.