Docker for Microservices

# Services reach each other by Compose service name — not by IP
version: "3.8"

services:
  api-gateway:
    image: acmecorp/api-gateway:${GIT_SHA}
    environment:
      - PAYMENT_SERVICE_URL=http://payment-service:3001
      - ORDER_SERVICE_URL=http://order-service:3002
      - USER_SERVICE_URL=http://user-service:3003
      # Service names resolve via Docker's built-in DNS.
      # When payment-service restarts and gets a new IP,
      # http://payment-service:3001 still works — DNS resolves the new IP.
    ports:
      - "80:3000"
    networks:
      - frontend
      - backend

  payment-service:
    image: acmecorp/payment-service:${GIT_SHA}
    environment:
      - DB_HOST=payment-db
      # payment-db resolves to the database container — same DNS mechanism.
    networks:
      - backend
    # NOT on the frontend network — cannot be reached directly from outside.

  order-service:
    image: acmecorp/order-service:${GIT_SHA}
    environment:
      - PAYMENT_SERVICE_URL=http://payment-service:3001
      # order-service can call payment-service by name — same backend network.
    networks:
      - backend

  user-service:
    image: acmecorp/user-service:${GIT_SHA}
    networks:
      - backend

  payment-db:
    image: postgres:15-alpine
    networks:
      - backend
      # Database is on backend only — never reachable from frontend network.
    volumes:
      - payment-db-data:/var/lib/postgresql/data

networks:
  frontend:
    # The public-facing network — only api-gateway sits here.
  backend:
    # The private network — all services and databases communicate here.

volumes:
  payment-db-data:

# Network topology — three-tier architecture
networks:
  frontend:    # Internet-facing — only the gateway lives here
  backend:     # Service-to-service — all application services
  data:        # Database tier — only services that need direct DB access

services:
  api-gateway:
    networks: [frontend, backend]
    # Can receive public traffic. Can call backend services. Cannot reach databases.

  payment-service:
    networks: [backend, data]
    # Can receive calls from gateway. Can query payment-db. Cannot be reached from internet.

  order-service:
    networks: [backend, data]

  user-service:
    networks: [backend]
    # Does not query a database directly — calls payment-service via backend network.

  payment-db:
    networks: [data]
    # Only reachable by services on the data network.
    # api-gateway, user-service: cannot reach this. payment-service: can.

  redis:
    networks: [backend]
    # Session store — reachable by all services. Not in data tier (no persistent data concern).

# Deploy a new version of payment-service only — everything else keeps running:
GIT_SHA=b4d9e1f docker compose \
  -f docker-compose.yml \
  -f docker-compose.prod.yml \
  up -d \
  --no-deps \
  --force-recreate \
  payment-service
# --no-deps        → do not restart dependencies (databases, redis)
#                   without this flag, Compose would also restart everything
#                   payment-service depends_on — bringing down the database
# --force-recreate → always recreate the container even if config hasn't changed
#                   ensures the new image tag is actually pulled and used
# payment-service  → only this service is affected

# Verify the other services were not touched:
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"
NAMES              STATUS           IMAGE
api-gateway        Up 3 hours       acmecorp/api-gateway:a3f2c8d
payment-service    Up 4 seconds     acmecorp/payment-service:b4d9e1f  ← new
order-service      Up 3 hours       acmecorp/order-service:a3f2c8d
user-service       Up 3 hours       acmecorp/user-service:a3f2c8d
payment-db         Up 3 hours       postgres:15-alpine
redis              Up 3 hours       redis:7-alpine
# Only payment-service has a new uptime and a new image tag.
# api-gateway, order-service, user-service: zero downtime, zero restarts.

# docker-compose.infra.yml — shared infrastructure, deployed once
version: "3.8"

services:
  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    volumes:
      - redisdata:/data
    networks:
      - infra
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

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

networks:
  infra:
    name: acmecorp_infra
    # Named network — application stacks join this by name.
  frontend:
    name: acmecorp_frontend

volumes:
  redisdata:

# Deploy the infrastructure stack once:
# docker compose -f docker-compose.infra.yml up -d

# docker-compose.payment.yml — payment service joins the shared infrastructure
version: "3.8"

services:
  payment-service:
    image: acmecorp/payment-service:${GIT_SHA}
    environment:
      - REDIS_HOST=redis
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      # redis resolves via the shared infra network — same DNS mechanism.
    networks:
      - infra
      # Join the shared infrastructure network to reach redis and nginx.
      - payment_internal
      # Private network for payment-service and its database only.

  payment-db:
    image: postgres:15-alpine
    networks:
      - payment_internal
    volumes:
      - payment-db-data:/var/lib/postgresql/data

networks:
  infra:
    external: true
    name: acmecorp_infra
    # external: true → this network was created by the infra stack.
    # Do not create it here — just join it.
    # If the infra stack is not running, this service fails to start cleanly.
  payment_internal:
    # Private to this Compose file — payment-service and payment-db only.

volumes:
  payment-db-data:

# Deploy the payment service independently:
# docker compose -f docker-compose.payment.yml up -d

# Deployment sequence — order matters for network creation:

# Step 1 — bring up shared infrastructure first (creates named networks):
docker compose -f docker-compose.infra.yml up -d
# Creates: acmecorp_infra, acmecorp_frontend networks.
# Starts: redis, nginx.

# Step 2 — deploy each service (joins existing networks):
docker compose -f docker-compose.payment.yml up -d
docker compose -f docker-compose.order.yml up -d
docker compose -f docker-compose.user.yml up -d

# Step 3 — validate the full topology:
# Check all containers are running and healthy:
docker ps --format "table {{.Names}}\t{{.Status}}"

# Validate inter-service DNS resolution:
docker exec payment-service nslookup redis
docker exec order-service nslookup payment-service

# Validate network isolation:
docker exec nginx ping payment-db 2>&1 | grep "not known"
# Should print "Name or service not known" — nginx cannot reach the database.

# Validate end-to-end request flow:
curl http://localhost/api/orders
# nginx → api-gateway → order-service → payment-service → payment-db