Skip to content

Docker Compose Multi-Service Stack

Medium ~40 min

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. 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. 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. 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. 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:
          - web

    Expected result

    Nginx proxies port 80 to the web app on port 3000.

  5. 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 reachable

    Expected result

    All four services are up, connected via a custom network, and accessible through Nginx on port 80.

Try it yourself

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

Related Glossary

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to topic