Docker Compose is a tool for defining and running multi-container Docker applications using a declarative YAML configuration file.
Instead of managing containers individually with complex Docker CLI commands, you define your entire application stack in a
docker-compose.yml file and orchestrate it with simple commands.
Docker Compose is ideal for:
Local development: Replicate production environments on your machine
Testing and CI/CD: Spin up test environments quickly
Small deployments: Single-host deployments with multiple interdependent services
Prototyping: Rapidly experiment with different service combinations
Docker Compose is not suitable for:
Large-scale distributed systems (use Kubernetes instead)
Multi-host orchestration (use Docker Swarm or Kubernetes)
High-availability requirements across multiple nodes
Core Components: Services, Volumes, Networks
Every Docker Compose application consists of three fundamental components:
Services
Services are containers that make up your application. Each service definition includes the image to run,
ports to expose, volumes to mount, environment variables, and networking configuration. Services communicate
with each other using their service names as hostnames within the Compose network.
Volumes
Volumes persist data beyond container lifecycle. Named volumes are managed by Docker; bind mounts connect to
host directories. Essential for stateful services like databases, caches, and application data storage.
Networks
Networks enable service-to-service communication. Docker Compose creates a default network automatically, but
custom networks provide better isolation and segmentation (e.g., frontend networks separate from backend).
Versioning and Compatibility
Choose the Right Compose File Version
Docker Compose file format has evolved through multiple versions. Each version introduces new features and
maintains backward compatibility. Choose based on your Docker Engine version and required features.
Version
Docker Engine
Release Year
Key Features
3.8
19.03+
2019
Profiles, service secrets
3.9
20.10+
2021
Extension fields, depends_on conditions
3.x (latest)
20.10+
Current
Stable, recommended for most users
Recommendation: Use version 3.8 or 3.9 for new projects. Avoid version 2.0 unless you have
legacy constraints. The 3.x series is stable, widely supported, and includes modern features without
experimental functionality.
The latest tag is a moving target that can introduce breaking changes and inconsistencies across environments.
Always specify exact versions for reproducibility and predictability.
❌ Bad:
services:
db:
image: postgres:latest
# Unpredictable - could upgrade at any time
✅ Good:
services:
db:
image: postgres:15.3-alpine
# Explicit version - reproducible everywhere
Use Lightweight Alpine-Based Images
Alpine Linux images are significantly smaller than standard distributions, reducing download times,
storage footprint, and attack surface. Use them whenever available.
postgres:15.3-alpine (~150MB) vs postgres:15.3 (~330MB)
node:18-alpine (~170MB) vs node:18 (~990MB)
redis:7-alpine (~28MB) vs redis:7 (~114MB)
Build and Test Images Locally
Always build and test custom images in your Compose setup before pushing to production. Use
docker-compose build to build images defined in your Compose file.
Run containers with non-root users to limit damage if a container is compromised.
services:
app:
image: node:18-alpine
user: “1000:1000”
# Run as UID 1000, GID 1000 (non-root)
Keep Images Minimal and Updated
Remove unnecessary files and tools from your custom images. Regularly update base images to include security patches.
# Dockerfile - minimal and clean
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci –only=production
FROM node:18-alpine
WORKDIR /app
COPY –from=builder /app/node_modules ./node_modules
COPY –chown=node:node . .
USER node
CMD [“node”, “app.js”]
Configuration Management
Separate Development and Production Configurations
Use base and override Compose files to manage environment-specific configurations. This prevents
duplicating configuration and reduces errors.
# Structure
docker-compose.yml # Base configuration (shared)
docker-compose.dev.yml # Development overrides
docker-compose.prod.yml # Production overrides
docker-compose.test.yml # Test environment overrides
Run with multiple files:
# Development
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
# Production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up
Use Profiles for Conditional Services
Profiles allow you to selectively enable/disable services without removing them from the file.
version: '3.9'
services:
web:
image: nginx:latest
profiles:
- prod
- dev
testing-db:
image: postgres:15-alpine
profiles:
- test
cache:
image: redis:7-alpine
# No profile = always active
Start with specific profiles:
docker-compose --profile prod up
docker-compose –profile test up
Document Your Configuration
Add comments explaining non-obvious settings and configuration choices. This helps team members understand the setup.
version: '3.9'
services:
# Main web application - Node.js 18 LTS
# Exposed on port 3000 for development
web:
image: myapp:1.0.0
ports:
- ‘3000:3000’
depends_on:
db:
condition: service_healthy
environment:
NODE_ENV: ${NODE_ENV:-development}
DATABASE_URL: postgresql://user:pass@db:5432/myapp
# PostgreSQL 15 - database layer
# Uses named volume for persistence across restarts
db:
image: postgres:15.3-alpine
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: [“CMD-SHELL”, “pg_isready -U postgres”]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres_data:
driver: local
Performance Optimization
Set Resource Limits
Define CPU and memory limits to prevent containers from consuming all system resources and causing
other services to fail.
services:
web:
image: nginx:latest
deploy:
resources:
limits:
cpus: ‘1’ # Maximum 1 CPU core
memory: 512M # Maximum 512MB RAM
reservations:
cpus: ‘0.5’ # Guaranteed 0.5 CPU
memory: 256M # Guaranteed 256MB RAM
Optimize Layer Caching
Order Dockerfile instructions to maximize layer caching. Put frequently-changing instructions
(like COPY and RUN) after stable instructions.
# Good - caching order optimized
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./ # Stable, cache this
RUN npm ci –only=production # Cache dependencies
COPY . . # Frequently changes
CMD [“node”, “app.js”]
Use .dockerignore Files
Reduce build context size by excluding unnecessary files from Docker builds.
Docker Compose creates a default network, but custom networks provide better isolation and explicit control over
which services can communicate.
version: '3.9'
services:
web:
image: nginx:latest
networks:
- frontend
api:
image: node:18-alpine
networks:
- frontend
- backend
# Can communicate with both web (via frontend) and db (via backend)
db:
image: postgres:15-alpine
networks:
- backend
# Isolated from web - no direct connection
networks:
frontend:
driver: bridge
backend:
driver: bridge
Service Discovery with DNS
Docker's embedded DNS server allows services to communicate by service name. Service names resolve to the container's IP address.
# Inside a container:
$ curl http://db:5432 # ‘db’ resolves to the database service’s IP
$ curl http://cache:6379 # ‘cache’ resolves to Redis service IP
Expose Ports Carefully
Only expose ports that need to be accessed externally. Use expose for internal service-to-service communication.
services:
web:
image: nginx:latest
ports:
- ‘80:80’ # Expose to host
api:
image: node:18-alpine
expose:
- ‘3000’ # Only expose to other services via network
networks:
- backend
db:
image: postgres:15-alpine
expose:
- ‘5432’ # No host port - internal only
Storage and Volumes Best Practices
Named Volumes vs Bind Mounts
Named volumes are managed by Docker and persist independently. Bind mounts connect to host directories.
Use named volumes for production data, bind mounts for development.
Type
Use Case
Example
Named Volume
Production data, databases, persistence
- postgres_data:/var/lib/postgresql/data
Bind Mount
Development, hot reload, source code
- ./src:/app/src
Tmpfs
Temporary data, cache, performance
- type: tmpfs target: /tmp
Define Named Volumes Explicitly
Always define named volumes at the top level to ensure they're created and can be managed independently.
Be careful with volume ownership. Use chown in Dockerfile or specify user permissions to avoid permission issues.
FROM node:18-alpine
WORKDIR /app
COPY –chown=node:node . .
USER node
volumes:
app_data:
# Created with root ownership - potential permission issues
driver: local
Health Checks and Service Readiness
Implement Health Checks
Health checks allow Docker to detect if a container is healthy and ready to serve traffic.
Use them with depends_on condition to ensure proper startup order.