Docker Compose Multi-Service Stack
What you'll build
A docker-compose.yml that brings up a full stack: Node.js web app, PostgreSQL database, Redis cache, and Nginx reverse proxy — all connected with a custom network.
Goals
- Define multiple services in docker-compose.yml
- Connect services with custom networks
- Use volumes for persistent data
- Configure service dependencies with depends_on
Prerequisites
- Docker basics (Dockerfile, build, run)
- Understanding of web app architecture
- YAML syntax
Steps
- 1
Create the web app Dockerfile
Create a simple Node.js Express app and its Dockerfile. This will be the main web service in the compose stack.
Code// app/index.js const express = require('express'); const app = express(); app.get('/', (req, res) => { res.json({ message: 'Hello from the web app!', time: new Date() }); }); app.get('/health', (req, res) => res.json({ status: 'ok' })); app.listen(3000, () => console.log('App on :3000')); # app/Dockerfile FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . EXPOSE 3000 CMD ["node", "index.js"]Expected result
A Node.js app with a Dockerfile, ready to be composed.
- 2
Define the compose file with web and database
Create docker-compose.yml with the web service and a PostgreSQL database. Use environment variables for the database connection.
Code# docker-compose.yml services: web: build: ./app ports: - "3000:3000" environment: - DB_HOST=db - DB_PORT=5432 - DB_NAME=myapp depends_on: db: condition: service_healthy db: image: postgres:16-alpine environment: - POSTGRES_DB=myapp - POSTGRES_PASSWORD=secret volumes: - db_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 5s timeout: 3s retries: 5 volumes: db_data:Expected result
Running docker compose up starts the web app and database with a health check.
- 3
Add Redis cache service
Add a Redis service to the compose file. Redis will serve as a cache for the web app.
Code# Add to docker-compose.yml services: redis: image: redis:7-alpine ports: - "6379:6379" volumes: - redis_data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s retries: 3 # Add to volumes: redis_data:Expected result
Redis is available at redis:6379 within the compose network.
- 4
Add Nginx reverse proxy
Add an Nginx service that proxies requests to the web app. This is the entry point for external traffic.
Code# nginx/nginx.conf upstream web_app { server web:3000; } server { listen 80; location / { proxy_pass http://web_app; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } # Add to docker-compose.yml services: nginx: image: nginx:alpine ports: - "80:80" volumes: - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro depends_on: - webExpected result
Nginx proxies port 80 to the web app on port 3000.
- 5
Define a custom network
Add a custom bridge network so services can communicate by name. Run the full stack and verify connectivity.
Code# Add to docker-compose.yml: networks: app_network: driver: bridge # Update each service to use the network: # networks: # - app_network # Run the full stack: # docker compose up -d # curl localhost/ → proxied to web app # docker compose exec web ping db → database reachable # docker compose exec web ping redis → cache reachableExpected result
All four services are up, connected via a custom network, and accessible through Nginx on port 80.
Try it yourself
# docker-compose.yml
services:
web:
build: ./app
# TODO: add ports and environment
db:
image: postgres:16-alpine
# TODO: add environment and volumeservices:
web:
build: ./app
ports: ["3000:3000"]
depends_on: [db]
db:
image: postgres:16-alpine
environment: [POSTGRES_PASSWORD=secret]
volumes: [db_data:/var/lib/postgresql/data]
volumes:
db_data:What you learned
You orchestrated a multi-service stack with Docker Compose — the standard for local development environments. You connected services with networks, persisted data with volumes, and added health checks for reliable startup ordering.
Related Resources
Related Glossary
- Docker Compose
Multi-container orchestration
- Container
Lightweight isolation
Related Glossary
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
- Docker Compose
Multi-container orchestration
- Container
Lightweight isolation
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.