🏗️ Multi-Container Applications

Beyond Single Containers

In the last lesson you ran a three-service stack. That wasn't an accident of the example — it reflects how modern software is actually built. Instead of one giant program that does everything, we split responsibilities across services that can be developed, deployed, scaled, and even rewritten independently.

Monolith to services

The trade-off is real and worth naming honestly. A monolith is simpler to start and deploy. Splitting into services buys you independent scaling and fault isolation but adds operational complexity — more moving parts, more network hops, more ways to misconfigure. Compose is what makes the multi-service approach practical on a single machine during development.

Architecture Patterns

You don't have to invent structure from scratch. A handful of patterns show up again and again; recognizing them helps you organize services sensibly.

API Gateway

A single entry point receives every client request and routes it to the right internal service. Clients only ever talk to the gateway, which also becomes a natural home for cross-cutting concerns like authentication, rate limiting, and TLS termination.

Backend for Frontend (BFF)

Different clients have different needs. A web app and a mobile app might want the same data shaped differently. A BFF gives each client type its own tailored backend, each talking to the shared internal services.

Database per Service

Each service owns its own database and no other service touches it directly. This keeps services loosely coupled and lets each pick the right storage — Postgres for orders, MongoDB for a product catalog, Redis for a cart. The cost is that cross-service data consistency now requires deliberate coordination.

How Services Communicate

Once you have multiple services, they need to talk. There are two broad styles, and mature systems use both.

Synchronous: direct HTTP calls

The most common style. One service makes an HTTP request to another and waits for the response. Thanks to Compose's built-in DNS, the target is just the service name:

// Inside the "orders" service, calling the "users" service.
// "users" is the service name → Compose resolves it on the network.
const res = await fetch('http://users:3000/api/users/123');
const user = await res.json();

Simple and easy to reason about, but it couples the caller's availability to the callee's: if users is down, orders feels it immediately.

Asynchronous: message queues

For work that doesn't need an instant answer — sending a confirmation email, generating a report, updating analytics — a message broker decouples the services. The producer drops a message and moves on; a consumer processes it whenever it's ready. This adds resilience (the broker buffers work if a consumer is briefly down) at the cost of eventual, rather than immediate, consistency.

services:
  publisher:
    build: ./publisher
    depends_on:
      - rabbitmq

  consumer:
    build: ./consumer
    depends_on:
      - rabbitmq

  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "15672:15672"   # management UI at http://localhost:15672

A Four-Service Stack

Let's grow last lesson's three-tier app into the shape most real projects take: web, API, database, and a Redis cache. The cache sits between the API and the database, holding frequently read data so the API can skip a database round-trip on a hit.

# compose.yaml — web + api + db + cache
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./web/dist:/usr/share/nginx/html:ro
    depends_on:
      - api

  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/appdb
      REDIS_URL: redis://cache:6379      # "cache" is the Redis service name
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  cache:
    image: redis:7-alpine
    volumes:
      - cache_data:/data

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  db_data:
  cache_data:

Notice how naturally the fourth service slots in. The API reaches Redis at redis://cache:6379 — again, just a service name. Each stateful service gets its own named volume. And the two databases start with different depends_on conditions: Postgres has a real readiness check, while Redis is fast enough that waiting for the container to start is enough.

Real Example: E-commerce

Here's a trimmed but realistic e-commerce stack. It uses the API-gateway and database-per-service patterns, mixes storage engines (polyglot persistence), and adds a message broker for asynchronous work like order notifications.

services:
  gateway:
    build: ./gateway
    ports:
      - "8000:8000"
    environment:
      AUTH_URL: http://auth:3001
      CATALOG_URL: http://catalog:3002
      ORDER_URL: http://orders:3003
      PAYMENT_URL: http://payment:3004
    depends_on:
      - auth
      - catalog
      - orders
      - payment

  auth:
    build: ./auth
    environment:
      DATABASE_URL: postgres://postgres:password@auth-db:5432/authdb
    depends_on:
      auth-db:
        condition: service_healthy

  catalog:
    build: ./catalog
    environment:
      MONGO_URL: mongodb://product-db:27017/products
    depends_on:
      - product-db

  orders:
    build: ./orders
    environment:
      DATABASE_URL: postgres://postgres:password@order-db:5432/orders
      RABBITMQ_URL: amqp://rabbitmq:5672
    depends_on:
      order-db:
        condition: service_healthy
      rabbitmq:
        condition: service_started

  payment:
    build: ./payment
    environment:
      STRIPE_API_KEY: ${STRIPE_API_KEY}    # from a .gitignored .env
      RABBITMQ_URL: amqp://rabbitmq:5672
    depends_on:
      - rabbitmq

  notification:
    build: ./notification
    environment:
      RABBITMQ_URL: amqp://rabbitmq:5672
    depends_on:
      - rabbitmq

  # --- Data stores (database per service) ---
  auth-db:
    image: postgres:16
    environment:
      POSTGRES_DB: authdb
      POSTGRES_PASSWORD: password
    volumes:
      - auth_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  product-db:
    image: mongo:7
    volumes:
      - product_db_data:/data/db

  order-db:
    image: postgres:16
    environment:
      POSTGRES_DB: orders
      POSTGRES_PASSWORD: password
    volumes:
      - order_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "15672:15672"
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq

volumes:
  auth_db_data:
  product_db_data:
  order_db_data:
  rabbitmq_data:

This one file captures a lot of design at once:

• API gateway as the single client entry point, holding the URLs of every internal service
• Database per service — auth and orders each own a Postgres instance, catalog owns MongoDB
• Polyglot persistence — the right storage engine for each job rather than one database forced everywhere
• Asynchronous events — orders and payments publish to RabbitMQ; the notification service consumes them
• Secrets by substitution — STRIPE_API_KEY comes from a .gitignored .env, never the committed YAML

Scaling a Service

Compose can run several copies of a single service, which is handy for load testing or squeezing more throughput out of a stateless API on one host.

# Run 3 instances of the api service
docker compose up -d --scale api=3

For this to help, the scaled service must be stateless — it must not keep important data in its own memory, because each request might hit a different instance. Push shared state to Redis or the database. You'll also want a reverse proxy in front to spread traffic across the instances:

services:
  proxy:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api

  api:
    build: ./api
    expose:
      - "3000"     # visible to other services, not published to the host

# nginx.conf — Compose load-balances "api" across all scaled instances
upstream api_pool {
    server api:3000;
}
server {
    listen 80;
    location / {
        proxy_pass http://api_pool;
        proxy_set_header Host $host;
    }
}

Practice & Quiz

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/appdb
      REDIS_URL: redis://cache:6379
    depends_on:
      - db
      - cache

  cache:
    image: redis:7-alpine
    volumes:
      - cache_data:/data

volumes:
  db_data:
  cache_data:

Best Practices & Pitfalls

✅ Do

• Give each service one clear responsibility
• Reach other services by service name, never a hard-coded IP
• Use synchronous HTTP for "I need the answer now," queues for "this can happen later"
• Give each stateful service its own named volume
• Keep scaled services stateless; push shared state to Redis or a database
• Start simpler and decompose further only when a real pressure demands it

❌ Don't

• Let two services write to the same database schema in the database-per-service pattern
• Chain long synchronous call graphs — one slow service stalls the whole request
• Store session or cart state in the memory of a service you plan to scale
• Add services for their own sake — every one is more to operate and debug
• Forget healthchecks on databases that other services depend on

Summary

📚 Additional Resources

• Docker Docs — Working with multiple Compose files
• Docker Docs — Compose services reference
• Docker Docs — Control startup and shutdown order
• Awesome Compose — multi-service example projects

🚀 What's Next?

You've been reaching services by name and persisting data with named volumes without fully unpacking how either works. The next lesson does exactly that: networking and volumes in depth — custom networks for isolation, the difference between named volumes and bind mounts, and how to keep your data safe.