Compose Service Topologies

Model APIs, databases, workers, queues, and admin tools with compose.yaml services and networks.

8 min readDocker & ContainersProvision

Topology Patterns

Service topologies define how containers are organized and connected. Common patterns include API + database, background workers, message queues, and multi-tier architectures. Each pattern has specific networking, dependency, and scaling requirements.

API + Database

API with PostgreSQL


services:
  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend

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

volumes:
  pgdata:

networks:
  backend:

The api and db services share a backend network. The api connects to db using the service name as hostname. The healthcheck ensures the database is ready before the API starts.

Worker Pattern

Background worker services


services:
  api:
    build: .
    command: node api.js
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  worker:
    build: .
    command: node worker.js
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    deploy:
      replicas: 3

  scheduler:
    build: .
    command: node scheduler.js
    depends_on:
      redis:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

Workers share the same image as the API but run different commands. The scheduler manages periodic tasks. All services depend on the database and Redis with health checks.

Queue Pattern

Message queue topology


services:
  producer:
    build: .
    command: node producer.js
    environment:
      AMQP_URL: amqp://rabbitmq:5672
    depends_on:
      rabbitmq:
        condition: service_healthy

  consumer:
    build: .
    command: node consumer.js
    environment:
      AMQP_URL: amqp://rabbitmq:5672
    depends_on:
      rabbitmq:
        condition: service_healthy
    deploy:
      replicas: 2

  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "15672:15672"  # Management UI
    healthcheck:
      test: rabbitmq-diagnostics -q ping
      interval: 10s
      timeout: 5s
      retries: 5

The producer sends messages to RabbitMQ. The consumer processes them. Multiple consumer replicas process messages in parallel. The management UI is accessible for monitoring.

Multi-Tier Architecture

Full multi-tier stack


services:
  frontend:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - frontend

  api:
    build: ./api
    networks:
      - frontend
      - backend

  worker:
    build: ./worker
    networks:
      - backend

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend

  redis:
    image: redis:7-alpine
    networks:
      - backend

networks:
  frontend:
  backend:

volumes:
  pgdata:

Frontend connects only to the API. The API connects to both frontend and backend networks. Workers and databases are on the backend network only. This limits the blast radius of a compromise.

Network Topology

Network isolation strategy


services:
  web:
    networks:
      - public    # Can reach internet

  api:
    networks:
      - public    # Can reach web
      - internal  # Can reach db, cache

  db:
    networks:
      - internal  # Only accessible from api

  cache:
    networks:
      - internal  # Only accessible from api, worker

  worker:
    networks:
      - internal  # Can reach db, cache

networks:
  public:
    driver: bridge
  internal:
    driver: bridge
    internal: true  # No internet access

The internal network has no internet access. Services on it can only communicate with each other. This prevents databases and caches from being accessible from outside the stack.

Isolate by network, not by service

Use multiple networks to control which services can communicate. Put databases and caches on internal-only networks. Put user-facing services on public networks. This limits the blast radius if a service is compromised.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 4 · Provision

Networking, Storage & Compose Deep Dive