Docker Compose is one of the most powerful and useful Docker tools. Let's dive in!
Part 1: What is Docker Compose?
The Problem Docker Compose Solves
Imagine you built a multi-container application:
Your Application needs:
├── Web server (Nginx)
├── API server (Python Flask)
├── Database (PostgreSQL)
├── Cache (Redis)
└── Message Queue (RabbitMQ)
5 containers to manage!
Without Docker Compose:
# Create networks
docker network create frontend
docker network create backend
# Start database
docker run -d \
--name postgres \
--network backend \
-e POSTGRES_PASSWORD=secret \
-e POSTGRES_DB=myapp \
-v postgres-data:/var/lib/postgresql/data \
postgres:15
# Start Redis
docker run -d \
--name redis \
--network backend \
redis:7
# Start API
docker run -d \
--name api \
--network backend \
-e DATABASE_URL=postgresql://postgres:secret@postgres:5432/myapp \
-e REDIS_URL=redis://redis:6379 \
my-api
docker network connect frontend api
# Start Web
docker run -d \
--name web \
--network frontend \
-p 80:80 \
my-web
# That's a LOT of commands! 😰
# And you need to remember all of them!
# Starting, stopping, updating... nightmare!
Docker Compose Solution
With Docker Compose, ONE file describes everything:
# docker-compose.yml
version: '3.8'
services:
postgres:
image: postgres:15
environment:
POSTGRES_PASSWORD: secret
POSTGRES_DB: myapp
volumes:
- postgres-data:/var/lib/postgresql/data
redis:
image: redis:7
api:
build: ./api
environment:
DATABASE_URL: postgresql://postgres:secret@postgres:5432/myapp
REDIS_URL: redis://redis:6379
depends_on:
- postgres
- redis
web:
build: ./web
ports:
- "80:80"
depends_on:
- api
volumes:
postgres-data:
Now just run:
docker-compose up
That's it! All 5 containers started with proper configuration! ✓
What is Docker Compose?
Simple Definition:
Docker Compose = Tool for defining and running
multi-container Docker applications
Key features:
├── Define everything in YAML file
├── Single command to start/stop all containers
├── Automatic network creation
├── Volume management
├── Service dependencies
└── Easy scaling
Think of it as:
Recipe Book (docker-compose.yml):
├── Lists all ingredients (services)
├── Preparation steps (configuration)
├── Cooking order (dependencies)
└── Final presentation (ports, networks)
One command to cook the entire meal! 🍽️
Part 2: Installing Docker Compose
Checking if Docker Compose is Installed
Docker Desktop includes Docker Compose!
docker-compose --version
Output:
Docker Compose version v2.24.5
✓ Already installed with Docker Desktop!
Docker Compose v1 vs v2
Two versions exist:
Docker Compose v1:
├── Separate tool
├── Command: docker-compose (with hyphen)
└── Older version
Docker Compose v2:
├── Integrated into Docker CLI
├── Command: docker compose (space, no hyphen)
└── Newer, faster version
Both work, but v2 is recommended:
# v1 syntax (old)
docker-compose up
# v2 syntax (new, recommended)
docker compose up
For this tutorial, we'll use v2 syntax (docker compose), but v1 also works!
Part 3: Docker Compose File Basics
Creating Your First docker-compose.yml
Docker Compose uses YAML format.
YAML Basics (Quick!):
# Comments start with #
# Key-value pairs
name: value
# Nested structure (indentation matters!)
parent:
child: value
another_child: value
# Lists
items:
- item1
- item2
- item3
# Multi-line strings
description: |
This is a
multi-line
string
⚠️ Important: YAML is VERY sensitive to indentation! Use spaces, not tabs!
Basic docker-compose.yml Structure
version: '3.8' # Compose file version
services: # Define containers
service1:
# Configuration for service1
service2:
# Configuration for service2
volumes: # Define volumes (optional)
volume1:
networks: # Define networks (optional)
network1:
Example 1: Single Service (Nginx)
docker-compose.yml:
version: '3.8'
services:
web:
image: nginx:alpine
ports:
- "8080:80"
That's it! Now run:
docker compose up
Output:
[+] Running 1/1
✔ Container project-web-1 Started
Attaching to web-1
web-1 | /docker-entrypoint.sh: Configuration complete
web-1 | nginx: [notice] starting nginx...
Open browser: http://localhost:8080
✓ Nginx running!
To stop:
# Press Ctrl+C
# Or in another terminal:
docker compose down
Understanding Service Names
In docker-compose.yml:
services:
web: # ← This is the service name
Docker Compose creates container with name:
project-web-1
↑ ↑ ↑
│ │ └── Instance number
│ └── Service name
└── Project name (directory name)
Part 4: Service Configuration Options
Common Service Options
Let's explore all important options:
1. image - Use Existing Image
services:
db:
image: postgres:15
# Uses official PostgreSQL image from Docker Hub
2. build - Build from Dockerfile
services:
api:
build: ./api
# Builds from Dockerfile in ./api directory
Or with more options:
services:
api:
build:
context: ./api # Directory with Dockerfile
dockerfile: Dockerfile.prod # Custom Dockerfile name
args: # Build arguments
VERSION: 1.0
3. ports - Port Mapping
services:
web:
image: nginx
ports:
- "8080:80" # Host:Container
- "8443:443"
Format:
ports:
- "HOST_PORT:CONTAINER_PORT"
4. environment - Environment Variables
services:
db:
image: postgres:15
environment:
POSTGRES_PASSWORD: secret
POSTGRES_DB: myapp
POSTGRES_USER: admin
Or from file:
services:
api:
image: my-api
env_file:
- .env # Load from .env file
.env file:
DATABASE_URL=postgresql://localhost/mydb
API_KEY=abc123
DEBUG=true
5. volumes - Data Persistence
Named volume:
services:
db:
image: postgres:15
volumes:
- postgres-data:/var/lib/postgresql/data
volumes:
postgres-data: # Define volume
Bind mount:
services:
web:
image: nginx
volumes:
- ./html:/usr/share/nginx/html # Host:Container
Multiple volumes:
services:
app:
image: my-app
volumes:
- app-data:/data # Named volume
- ./config:/app/config # Bind mount
- ./logs:/app/logs # Another bind mount
6. depends_on - Service Dependencies
services:
web:
image: nginx
depends_on:
- api # Start api before web
api:
image: my-api
depends_on:
- db # Start db before api
db:
image: postgres
Start order: db → api → web
⚠️ Note: depends_on only waits for container to START, not for it to be READY!
7. networks - Custom Networks
services:
web:
image: nginx
networks:
- frontend
api:
image: my-api
networks:
- frontend
- backend
db:
image: postgres
networks:
- backend
networks:
frontend:
backend:
8. restart - Restart Policy
services:
api:
image: my-api
restart: always
# Options: no, always, on-failure, unless-stopped
Options:
no = Never restart
always = Always restart (even after reboot)
on-failure = Restart only if exit code != 0
unless-stopped = Always restart unless manually stopped
9. command - Override Default Command
services:
db:
image: postgres
command: postgres -c max_connections=200
# Overrides default command
10. container_name - Custom Container Name
services:
db:
image: postgres
container_name: my-postgres-db
# Instead of default: project-db-1
Part 5: Complete Example - Web Application
Building a Full Application
Let's create: Web Frontend + API Backend + PostgreSQL Database
Project Structure
my-app/
├── docker-compose.yml
├── web/
│ ├── Dockerfile
│ └── index.html
├── api/
│ ├── Dockerfile
│ ├── app.py
│ └── requirements.txt
└── .env
Step 1: Create Project Directory
mkdir my-app
cd my-app
mkdir web api
Step 2: Create API
api/app.py:
from flask import Flask, jsonify
import psycopg2
import os
import time
app = Flask(__name__)
def get_db():
# Wait for database to be ready
max_retries = 30
for i in range(max_retries):
try:
conn = psycopg2.connect(
host=os.getenv('DB_HOST', 'db'),
database=os.getenv('DB_NAME', 'myapp'),
user=os.getenv('DB_USER', 'postgres'),
password=os.getenv('DB_PASSWORD', 'secret')
)
return conn
except psycopg2.OperationalError:
if i < max_retries - 1:
time.sleep(1)
else:
raise
@app.route('/api/status')
def status():
return jsonify({
'status': 'ok',
'message': 'API is running!'
})
@app.route('/api/db-check')
def db_check():
try:
db = get_db()
cursor = db.cursor()
cursor.execute('SELECT version()')
version = cursor.fetchone()[0]
db.close()
return jsonify({
'status': 'ok',
'database': version
})
except Exception as e:
return jsonify({
'status': 'error',
'message': str(e)
}), 500
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000)
api/requirements.txt:
flask==3.0.0
psycopg2-binary==2.9.9
api/Dockerfile:
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
CMD ["python", "app.py"]
Step 3: Create Web Frontend
web/index.html:
<!DOCTYPE html>
<html>
<head>
<title>My Docker Compose App</title>
<style>
body {
font-family: Arial, sans-serif;
max-width: 800px;
margin: 50px auto;
padding: 20px;
background-color: #f5f5f5;
}
.container {
background: white;
padding: 30px;
border-radius: 10px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
button {
background: #007bff;
color: white;
border: none;
padding: 10px 20px;
border-radius: 5px;
cursor: pointer;
margin: 5px;
}
button:hover {
background: #0056b3;
}
#result {
background: #f8f9fa;
padding: 15px;
border-radius: 5px;
margin-top: 20px;
white-space: pre-wrap;
}
</style>
</head>
<body>
<div class="container">
<h1>🐳 Docker Compose Demo App</h1>
<p>This demonstrates a multi-container application with Docker Compose!</p>
<div>
<button onclick="checkAPI()">Check API Status</button>
<button onclick="checkDB()">Check Database</button>
</div>
<div id="result"></div>
</div>
<script>
async function checkAPI() {
const result = document.getElementById('result');
result.textContent = 'Loading...';
try {
const response = await fetch('/api/status');
const data = await response.json();
result.textContent = JSON.stringify(data, null, 2);
} catch (error) {
result.textContent = 'Error: ' + error.message;
}
}
async function checkDB() {
const result = document.getElementById('result');
result.textContent = 'Loading...';
try {
const response = await fetch('/api/db-check');
const data = await response.json();
result.textContent = JSON.stringify(data, null, 2);
} catch (error) {
result.textContent = 'Error: ' + error.message;
}
}
</script>
</body>
</html>
web/nginx.conf:
server {
listen 80;
location / {
root /usr/share/nginx/html;
index index.html;
}
location /api/ {
proxy_pass http://api:5000/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
web/Dockerfile:
FROM nginx:alpine
COPY index.html /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
Step 4: Create docker-compose.yml
docker-compose.yml:
version: '3.8'
services:
# PostgreSQL Database
db:
image: postgres:15-alpine
container_name: myapp-postgres
environment:
POSTGRES_DB: myapp
POSTGRES_USER: postgres
POSTGRES_PASSWORD: secret
volumes:
- postgres-data:/var/lib/postgresql/data
networks:
- backend
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
# API Backend
api:
build: ./api
container_name: myapp-api
environment:
DB_HOST: db
DB_NAME: myapp
DB_USER: postgres
DB_PASSWORD: secret
depends_on:
db:
condition: service_healthy
networks:
- frontend
- backend
restart: unless-stopped
# Web Frontend
web:
build: ./web
container_name: myapp-web
ports:
- "8080:80"
depends_on:
- api
networks:
- frontend
restart: unless-stopped
volumes:
postgres-data:
networks:
frontend:
backend:
Step 5: Run the Application
Start everything:
docker compose up
Or run in background:
docker compose up -d
Output:
[+] Running 5/5
✔ Network myapp_frontend Created
✔ Network myapp_backend Created
✔ Volume "myapp_postgres-data" Created
✔ Container myapp-postgres Started
✔ Container myapp-api Started
✔ Container myapp-web Started
Open browser: http://localhost:8080
Click buttons to test! ✓
Part 6: Docker Compose Commands
Essential Commands
Start services:
# Start in foreground (see logs)
docker compose up
# Start in background (detached)
docker compose up -d
# Rebuild images and start
docker compose up --build
# Start specific service
docker compose up web
Stop services:
# Stop (keeps containers)
docker compose stop
# Stop and remove containers
docker compose down
# Stop, remove containers, volumes, and networks
docker compose down -v
# Remove everything including images
docker compose down --rmi all
View logs:
# All services
docker compose logs
# Follow logs (real-time)
docker compose logs -f
# Specific service
docker compose logs api
# Last 100 lines
docker compose logs --tail=100
List services:
docker compose ps
Output:
NAME IMAGE STATUS PORTS
myapp-web myapp-web Up 0.0.0.0:8080->80/tcp
myapp-api myapp-api Up
myapp-postgres postgres:15 Up
Execute commands in service:
# Open shell in service
docker compose exec api bash
# Run command
docker compose exec db psql -U postgres
# Run as different user
docker compose exec -u root api bash
View service configuration:
docker compose config
Shows resolved configuration with all variables substituted.
Restart services:
# Restart all
docker compose restart
# Restart specific service
docker compose restart api
Scale services:
# Run 3 instances of api
docker compose up -d --scale api=3
Build images:
# Build all images
docker compose build
# Build specific service
docker compose build api
# Build without cache
docker compose build --no-cache
Pull images:
# Pull all images
docker compose pull
# Pull specific service
docker compose pull db
Part 7: Environment Variables and .env Files
Using .env File
Create .env file:
# .env
DB_NAME=myapp
DB_USER=postgres
DB_PASSWORD=supersecret
API_PORT=5000
WEB_PORT=8080
docker-compose.yml:
version: '3.8'
services:
db:
image: postgres:15
environment:
POSTGRES_DB: ${DB_NAME}
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
api:
build: ./api
environment:
DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}
ports:
- "${API_PORT}:5000"
web:
build: ./web
ports:
- "${WEB_PORT}:80"
Variables automatically loaded from .env! ✓
Multiple Environment Files
# Use different env file
docker compose --env-file .env.production up
# Override with another file
docker compose --env-file .env.local up
Passing Environment Variables
# From command line
DB_PASSWORD=newsecret docker compose up
# System environment variables
export DB_PASSWORD=newsecret
docker compose up
Part 8: Profiles (Conditional Services)
What are Profiles?
Run different sets of services for different scenarios.
Example:
version: '3.8'
services:
# Always run
web:
image: nginx
ports:
- "80:80"
api:
image: my-api
depends_on:
- db
db:
image: postgres
# Only for development
adminer:
image: adminer
profiles:
- dev
ports:
- "8080:8080"
# Only for debugging
debug-tools:
image: nicolaka/netshoot
profiles:
- debug
command: sleep infinity
Usage:
# Start only core services
docker compose up
# Start with dev profile (includes adminer)
docker compose --profile dev up
# Start with debug profile
docker compose --profile debug up
# Start with multiple profiles
docker compose --profile dev --profile debug up
Part 9: Healthchecks
Adding Healthchecks
Healthcheck = Test if service is actually ready
services:
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s # Check every 10 seconds
timeout: 5s # Fail if takes > 5 seconds
retries: 3 # Try 3 times before giving up
start_period: 30s # Grace period on startup
api:
build: ./api
depends_on:
db:
condition: service_healthy # Wait for db to be healthy!
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
interval: 30s
timeout: 10s
retries: 3
Benefits:
Without healthcheck:
├── depends_on waits for container to start
├── But container might not be ready yet!
└── API tries to connect to DB → Fails! ✗
With healthcheck:
├── depends_on waits for service to be HEALTHY
├── Container started AND ready
└── API connects successfully ✓
Part 10: Advanced Example - Full Stack Application
Complete Real-World Example
docker-compose.yml:
version: '3.8'
services:
# Nginx Reverse Proxy
nginx:
image: nginx:alpine
container_name: nginx-proxy
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./nginx/ssl:/etc/nginx/ssl:ro
depends_on:
- web
- api
networks:
- frontend
restart: always
# Frontend (React)
web:
build:
context: ./frontend
args:
NODE_ENV: production
container_name: react-app
environment:
- REACT_APP_API_URL=http://localhost/api
networks:
- frontend
restart: always
# Backend API (Node.js)
api:
build: ./backend
container_name: nodejs-api
environment:
NODE_ENV: production
DB_HOST: postgres
DB_PORT: 5432
DB_NAME: ${DB_NAME}
DB_USER: ${DB_USER}
DB_PASSWORD: ${DB_PASSWORD}
REDIS_HOST: redis
REDIS_PORT: 6379
JWT_SECRET: ${JWT_SECRET}
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_started
networks:
- frontend
- backend
restart: always
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
# PostgreSQL Database
postgres:
image: postgres:15-alpine
container_name: postgres-db
environment:
POSTGRES_DB: ${DB_NAME}
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- postgres-data:/var/lib/postgresql/data
- ./database/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
networks:
- backend
restart: always
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
interval: 10s
timeout: 5s
retries: 5
# Redis Cache
redis:
image: redis:7-alpine
container_name: redis-cache
command: redis-server --appendonly yes
volumes:
- redis-data:/data
networks:
- backend
restart: always
# Database Admin (Development only)
adminer:
image: adminer
container_name: db-admin
ports:
- "8080:8080"
depends_on:
- postgres
networks:
- backend
profiles:
- dev
restart: unless-stopped
volumes:
postgres-data:
driver: local
redis-data:
driver: local
networks:
frontend:
driver: bridge
backend:
driver: bridge
.env:
# Database
DB_NAME=myapp
DB_USER=appuser
DB_PASSWORD=strongpassword123
# JWT
JWT_SECRET=your-secret-key-change-in-production
# Node
NODE_ENV=production
Usage:
# Production (no adminer)
docker compose up -d
# Development (with adminer)
docker compose --profile dev up -d
# View logs
docker compose logs -f
# Stop
docker compose down
Part 11: Docker Compose Best Practices
1. Use Specific Image Tags
Bad:
services:
db:
image: postgres # Latest version, unpredictable!
Good:
services:
db:
image: postgres:15-alpine # Specific version
2. Use .env for Sensitive Data
Bad:
services:
db:
environment:
POSTGRES_PASSWORD: hardcoded-password # Never do this!
Good:
services:
db:
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD} # From .env file
Add .env to .gitignore!
3. Use Named Volumes
Bad:
volumes:
- ./data:/var/lib/postgresql/data # Bind mount
Good:
volumes:
- postgres-data:/var/lib/postgresql/data # Named volume
volumes:
postgres-data:
4. Add Healthchecks
services:
api:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
5. Use Restart Policies
services:
web:
restart: unless-stopped # Auto-restart on failure
6. Separate Networks
networks:
frontend: # Public-facing services
backend: # Internal services (database, cache)
7. Order Services Properly
services:
db: # Database first
api: # API depends on db
depends_on:
- db
web: # Web depends on api
depends_on:
- api
Summary
What We Learned:
✅ What Docker Compose is and why it's useful
✅ docker-compose.yml file structure
✅ Service configuration options
✅ Building multi-container applications
✅ Docker Compose commands
✅ Environment variables and .env files
✅ Profiles for different scenarios
✅ Healthchecks
✅ Networks and volumes in Compose
✅ Real-world examples
✅ Best practices
Key Takeaways:
1. Docker Compose = Multi-container management tool
2. One YAML file describes entire application
3. Single command to start/stop everything
4. Automatic networking between services
5. Perfect for development and simple deployments
6. Use service names for container communication
7. Always use .env for sensitive data
8. Add healthchecks for reliable startups
Common Commands:
docker compose up -d # Start in background
docker compose down # Stop and remove
docker compose logs -f # Follow logs
docker compose ps # List services
docker compose exec api bash # Access service shell
docker compose build # Rebuild images
docker compose restart # Restart services
🎉 Excellent! You now know Docker Compose!
You can now:
- Manage multi-container applications easily
- Define entire stacks in one file
- Use Docker Compose for development
- Deploy simple production applications