Lesson 03 — Multi-Service Builds

From one image to a running system. docker-compose, env config, shared networks.

Cloud & DevOps Module 1

The shift in mindset

  ┌─────────┐     ┌────────┐
  │   api   │────▶│postgres│
  └────┬────┘     └────────┘
       │
  ┌────▼────┐     ┌────────┐
  │ worker  │────▶│ redis  │
  └─────────┘     └────────┘
      

Why not just docker run four times?

• Networking by hand is painful — you’d need to create networks, set DNS, expose ports for inter-container traffic
• Env-var management gets messy — each docker run needs its own -e flags repeated everywhere
• Lifecycle becomes a shell script — start in the right order, stop together, restart one service cleanly
• Volume sharing is awkward — naming volumes and wiring them to multiple containers requires extra bookkeeping
• No single source of truth — the stack is defined in your terminal history, not in code

docker-compose: one YAML for the whole stack

services:
  api:
    build: ./api
    ports: ["8000:8000"]
    env_file: ./.env
    depends_on: [postgres]
  worker:
    build: ./worker
    env_file: ./.env
    depends_on: [postgres, redis]
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes: ["pgdata:/var/lib/postgresql/data"]
  redis:
    image: redis:7-alpine
volumes:
  pgdata:

• One file, one command (docker compose up)
• All four services with networking, env vars, and persistence wired up

The implicit network

• Compose creates a default bridge network for the stack (named <projectdir>_default)
• Every service is reachable by its service name as the hostname: postgres, redis, api, worker
• DNS is provided by Docker’s embedded DNS server — no /etc/hosts editing required
• Service-to-service traffic flows on the internal network — no ports: mapping needed
• Only api needs to expose a port to the host (8000:8000) so your browser can reach it

Env files vs environment: keys

The .env file pattern

A file literally named .env in the same directory as docker-compose.yml. Compose reads it automatically.

POSTGRES_PASSWORD=devpassword
DATABASE_URL=postgresql://urls:devpassword@postgres:5432/urls
REDIS_URL=redis://redis:6379/0
BASE_URL=http://localhost:8000

depends_on is weak

• depends_on: [postgres] means “start postgres first” — NOT “wait until postgres is ready to accept connections”
• Your API container starts immediately after Docker launches the Postgres container
• Postgres takes ~2–5 s to initialise — the API gets ECONNREFUSED and crashes
• Three real solutions: app-level retry, condition: service_healthy + healthcheck, or a wait-for-it entrypoint script

Healthchecks

postgres:
  image: postgres:16-alpine
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 3s
    retries: 5
api:
  depends_on:
    postgres:
      condition: service_healthy

• condition: service_healthy makes api literally wait until pg_isready succeeds
• Docker polls the healthcheck command on the defined interval
• The service transitions: starting → healthy / unhealthy
• Dependent services only launch once healthy is reached

Volumes: named vs bind mounts

• Compose creates named volumes lazily; they persist across compose down
• Pass -v to compose down to also remove volumes (destroys DB data)
• Bind mounts expose your laptop’s filesystem inside the container — development only

Hot-reload for development

api:
  build: ./api
  volumes: ["./api:/app"]   # bind-mount source
  command: ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

• Bind-mount your source into the container
• Override the CMD to add --reload
• Edits to api/app.py on your laptop are picked up by uvicorn inside the container
• No rebuild needed for code changes — only for dependency changes

docker compose up lifecycle

What lands in sample-app/ after this lesson

Recap & what’s next

• Compose = one YAML for the whole stack; docker compose up is one command
• Service-to-service traffic uses service names as DNS — no IP addresses, no port mappings
• Healthchecks + condition: service_healthy beat plain depends_on for real readiness