Docker Compose is the gap between "docker run" chaos and a reproducible dev environment. These are the patterns I reach for in nearly every project, with the reasoning behind each.
The Canonical Multi-Service App
services:
web:
build: .
ports:
- "3000:3000"
env_file: .env
depends_on:
db:
condition: service_healthy
volumes:
- .:/app
- node_modules:/app/node_modules
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: dev
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 10
volumes:
pgdata:
Three things doing the heavy lifting:
depends_on with condition: service_healthy โ startup order by readiness, not by declaration order. Without the healthcheck, your app races the database and you spend an hour on a "mystery" connection refused.
- Named volume for data, bind mount for code โ the data outlives the container; the code hot-reloads.
- Anonymous
node_modules volume โ prevents the host's node_modules (different OS/arch) from shadowing the image's.
Pattern: The One-Command Environment
The whole point is that a new developer's setup is:
cp .env.example .env
docker compose up
If it's more than that, the compose file isn't done. Environment variables go in .env (gitignored) with a committed .env.example listing every variable and its meaning.
Pattern: Production-Grade Without Kubernetes
For small production workloads, Compose scales further than people think:
web:
deploy:
replicas: 2
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
Plus a reverse proxy in front (Caddy is 10 lines and does TLS for free):
# Caddyfile
app.example.com {
reverse_proxy web:3000
}
This pattern โ Compose + Caddy + a health endpoint โ runs real production traffic comfortably at small-to-medium scale. It's what I recommend before "we should look at k8s."
Pattern: The Debugging Moves
When the stack is broken, in this order:
docker compose ps
docker compose logs -f --tail=100 web
docker compose exec web sh
docker compose exec db psql -U postgres -c '\dt'
docker compose exec web env | grep DB
The two questions that resolve 90% of compose issues:
- "Can service A reach service B by name?" โ services resolve each other by service name on the internal network (
db, not localhost). localhost inside a container is the container.
- "Is the env var actually in the container?" โ
exec <svc> env. The .env file, env_file:, and environment: have subtly different precedence and the difference bites constantly.
Pattern: Profiles for Optional Services
Not every service runs every time:
selenium:
profiles: ["e2e"]
image: selenium/standalone-chrome
mailhog:
profiles: ["dev"]
docker compose up
docker compose --profile dev up
docker compose --profile e2e up
Keep the default stack minimal; opt in to extras. Your docker compose up should do the common thing, fast.
The Rules I Enforce
depends_on + healthchecks for every dependency that has a startup delay
- Named volumes for all persistent data โ never bind-mount into a data directory
- No hardcoded ports โ
3000:3000 is fine, 3000:80 is a future bug
.env gitignored, .env.example committed
- A
/health endpoint on every service โ compose healthchecks and future load balancers both need it
Compose is not a production platform. It is the interface between your project and your machine โ and done well, it makes "clone, up, works" a contract instead of a prayer.
Discussion (0)
Sign in or create an account to join the discussion.
No comments yet. Start the discussion.