Docker Compose

def port_clashes(services):
    return []


services = {
    "api": {"ports": ["8000:8000"]},
    "admin": {"ports": ["8000:3000"]},
    "db": {"ports": ["5432:5432"]},
    "cache": {},
}
print(port_clashes(services))

Data lives in volumes, secrets live elsewhere

A container's own files vanish when it's removed, and Compose removes and recreates containers all the time. Anything that must survive, above all a database's files, goes in a volume: dbdata:/var/lib/postgresql/data mounts a named volume, managed by Docker, at the folder where Postgres keeps its data. A bind mount such as ./src:/app maps a folder on your machine instead, which is handy in development so code changes show up without rebuilding.

Passwords are the other thing that doesn't belong in the file, because Compose files go into git. Write POSTGRES_PASSWORD: ${DB_PASSWORD} and Compose fills it in from your environment or from a .env file next to the Compose file, which stays out of git (add it to .gitignore). For production, use the platform's secret store.

The same ${...} mechanism is how one Compose file serves several environments: image: shop-api:${API_VERSION} lets CI run the exact version it just built, and a developer's .env can point the app at a local mail catcher instead of a real mail service. Keep a committed .env.example that lists every variable with a harmless sample value, so a new teammate knows what to set.

Start order, and waiting for "ready"

depends_on makes Compose start the database before the API. But "started" isn't "ready": Postgres takes a few seconds to accept connections, and an API that connects immediately crashes. The fix is a health check on the database and condition: service_healthy on the dependency, or an app that retries its first connection, which is good practice anyway.

Working out a start order from depends_on is the topological sort problem: everything must come after the things it needs, and a loop (A needs B, B needs A) has no valid order at all. Here's a short version that starts whatever has no unstarted needs, over and over:

def start_order(needs):
    order, started = [], set()
    while len(order) < len(needs):
        ready = sorted(s for s in needs if s not in started and all(d in started for d in needs[s]))
        if not ready:
            raise ValueError("these services depend on each other in a loop: " + ", ".join(sorted(set(needs) - started)))
        for s in ready:
            order.append(s)
            started.add(s)
    return order

print(start_order({"api": ["db", "cache"], "worker": ["db", "cache"], "db": [], "cache": []}))
try:
    start_order({"api": ["worker"], "worker": ["api"]})
except ValueError as e:
    print(e)

Here's the health check that makes "ready" mean ready, in the Compose file itself:

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "shop"]
      interval: 5s
      retries: 10
  api:
    depends_on:
      db:
        condition: service_healthy

pg_isready is a small tool that ships with Postgres and answers "accepting connections" or not. Docker runs it every 5 seconds and marks the database healthy once it passes; only then does it start the API. Notice that depends_on changed shape: from a list of names to a dictionary of names with a condition each. Both forms are valid, which is why a checker has to handle either.

def start_order(needs):
    order, started = [], set()
    while len(order) < len(needs):
        ready = sorted(s for s in needs if s not in started and all(d in started for d in needs[s]))
        if not ready:
            raise ValueError("loop")
        for s in ready:
            order.append(s)
            started.add(s)
    return order

print(start_order({"web": ["api"], "api": ["db"], "db": [], "worker": ["db"]}))

Beyond the laptop

The same file earns its keep in two more places. In CI, a test job runs docker compose up -d db cache, waits for the health checks, runs the test suite against real services instead of fakes, and tears everything down with docker compose down -v (the -v removes the volumes too, so every run starts clean). On a small server, Compose can run a whole product: restart: unless-stopped brings containers back after a crash or a reboot, and docker compose pull && docker compose up -d updates to newly published images. What it doesn't do is spread containers over several machines or replace a failed machine; when one server is no longer enough, that's the job Kubernetes takes on.