Stop Wrapping Multi-Container Apps in Endless docker run Calls
Nginx, an API, PostgreSQL, and Redis started one docker run at a time means hand-managing ports, volumes, networking, environment variables, and startup order — dozens of flags per command, none of it versioned. Compose describes the whole stack in one declarative YAML file, starts, stops, and rebuilds it with one command, and keeps the config in Git.
Docker Desktop bundles Compose. On Linux install docker-compose-plugin and use docker compose (V2) rather than the unmaintained docker-compose (V1).
Core Concepts
Services and the Default Network
Each service defines one container. Compose creates a network per project, and services in the same file reach each other by service name with no IP bookkeeping:
services:
web:
image: nginx:alpine
ports:
- "8080:80"
volumes:
- ./html:/usr/share/nginx/html
depends_on:
- api
api:
image: node:20-alpine
# inside web: http://api:3000
For tier isolation, define custom networks: put web and api on frontend, db only on backend, and web can no longer reach the database.
services:
web:
networks: [frontend]
api:
networks: [frontend, backend]
db:
networks: [backend]
networks:
frontend:
backend:
Volumes: Named Volume vs Bind Mount
| Type | Syntax | Use for |
|---|---|---|
| Named volume | name:/path/in/container |
Runtime data such as databases; survives container removal |
| Bind mount | ./host/path:/container/path |
Syncing source and config during development |
services:
db:
image: postgres:16
volumes:
- pgdata:/var/lib/postgresql/data
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
volumes:
pgdata:
A bind mount shadows the container's directory of the same name. Mount ./backend:/app and the node_modules installed in the image disappears behind the host directory, so the container fails with a missing module. Add an anonymous volume - /app/node_modules to keep the image's dependencies.
Environment: Interpolation Is Not Injection
services:
api:
image: myapp:latest
environment:
- NODE_ENV=production
env_file:
- .env
${VAR} is substituted while parsing the YAML, for the compose file's own use. environment and env_file are injected into the container process at runtime. The two are not interchangeable: a DB_PASSWORD in .env does not reach the container unless it is also listed under environment.
.env must sit in the directory where you run docker compose (usually the project root), not next to the compose file in a subdirectory. Debug with docker compose config, which prints the merged, interpolated result so you can see whether substitution happened.
In Practice: Nginx + Node + PostgreSQL + Redis
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./certs:/etc/nginx/certs:ro
depends_on:
- api
restart: unless-stopped
api:
build:
context: ./backend
dockerfile: Dockerfile
environment:
- NODE_ENV=production
- DATABASE_URL=postgresql://app:${DB_PASSWORD}@db:5432/app
- REDIS_URL=redis://redis:6379
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
restart: unless-stopped
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
redis:
image: redis:7-alpine
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- redisdata:/data
restart: unless-stopped
volumes:
pgdata:
redisdata:
The reverse-proxy half is covered in the Nginx config cheat sheet.
Everyday Commands
docker compose up -d # start everything detached
docker compose ps # status
docker compose logs -f api # follow logs
docker compose up -d --build # rebuild after code changes
docker compose restart api # restart one service
docker compose exec api sh # shell into a container
docker compose down # remove containers and networks, keep volumes
docker compose down -v # remove volumes too (database data is lost)
docker compose stats # resource usage
Four Checks Before Shipping
depends_on Starts, It Does Not Mean Ready
The default depends_on waits for the container to start, not for the process to serve. The symptom is familiar: the API boots, connects to the database while it is still initializing, and exits. Add a healthcheck to the dependency and a condition to the dependent:
services:
api:
depends_on:
db:
condition: service_healthy
service_healthy waits for the check to pass; service_started (the default) waits for nothing meaningful.
Override Files for Multiple Environments
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Override files contain only differences — for development, switch command: npm run dev and expose debug port 9229; the production file adjusts resource caps and logging. Do not keep two complete YAML copies, or a change in one will be missed in the other.
Resource Caps and Log Rotation
services:
api:
deploy:
resources:
limits:
cpus: '1.0'
memory: 512M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
Without caps, one container eating all memory can take down the host; without rotation, logs can fill the disk.
Permissions, Ports, and Windows Mounts
- Linux write errors: the container process UID does not match the host file owner. Align with
user: "${UID}:${GID}", orchownfrom an init container after mounting. - Port already allocated:
docker compose upfails whiledocker psshows nothing. Find the host process withnetstat -ano | findstr :8080(Windows) orlsof -i :8080(Linux/macOS). - Slow Windows mounts: with the WSL2 backend, mounting
/c/...carries significant IO overhead. Put the project inside the WSL2 filesystem (\\wsl$\Ubuntu\home\...) — the original test measured 5-10x faster.
When to Move Beyond Compose
| Scenario | Tool |
|---|---|
| Single-host development / small deployment | Docker Compose |
| Multi-host cluster / high availability | Docker Swarm (lightweight) or Kubernetes |
| Enterprise production orchestration | Kubernetes |
Compose handles small single-host production well with restart: unless-stopped, healthchecks, resource caps, and log rotation. What it lacks is multi-node scheduling, autoscaling, rolling updates, and self-healing; migrate when you need multi-host availability. A docker-compose.yml deploys to Swarm via docker stack deploy; Kubernetes needs converted manifests (Kompose helps).
Reproducible Results
docker compose config parses without deploying, so syntax errors, bad indentation, and wrong types surface immediately:
docker compose config -q && echo "compose OK" # silent + exit 0 when valid
docker compose config # final config after interpolation and defaults
Run both before up to skip the "three containers later I notice the port mapping is wrong" loop. Convert command-line flags with the docker run to compose tool, and keep the Docker command cheat sheet handy.