Docker Compose Basics & Specification

1. Compose V2 Evolution: docker compose

In legacy systems, Compose was an external Python utility invoked with a hyphen (docker-compose). Today, Compose V2 is rewritten in Go and integrated directly into the Docker CLI engine as docker compose.

2. The 4 Top-Level Compose Keys

A compose.yaml document organizes application architecture across four primary root keys:

3. Solving the Database Startup Race Condition

A common bug in multi-container setups is the API container starting before the database is ready. Standard depends_on: [db] only waits for the database container to start, not for PostgreSQL to finish initializing its internal transaction logs and listen on port 5432!

Modern Compose solves this using Health-Aware Dependencies (condition: service_healthy):

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: "postgresql://app_user:secret@postgres-db:5432/production_db"
    # Wait until PostgreSQL healthcheck passes before booting the API!
    depends_on:
      postgres-db:
        condition: service_healthy

  postgres-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: production_db
    volumes:
      - pg_data:/var/lib/postgresql/data
    # Native Healthcheck probe:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app_user -d production_db"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

volumes:
  pg_data:

4. Ports vs Expose: Crucial Security Nuance