Multi-service apps with Compose

This is your first compose file — one YAML file that describes an entire app. Under services: you list each container you want; Compose reads this and starts them all. Indentation is meaningful in YAML: the lines indented under a name belong to that service.

1. services: opens the list. api:, db: and cache: are the three services — three separate containers Compose will run together.
2. Under api: build: . means "build this service's image from the Dockerfile in the current folder". ports: ["8000:8000"] exposes port 8000 so you can open it in a browser (host port : container port).
3. environment: passes settings in as environment variables. Notice @db:5432 in the DATABASE_URL — db is the service name above, used as a hostname (more on that below).
4. depends_on: [db, cache] tells Compose to start the database and cache before the api. The db service uses a ready-made image: postgres:16 (no build needed), and volumes: saves its data so it survives restarts.
5. At the bottom, the top-level volumes: dbdata: declares the named storage the database uses. Declaring it here is what makes the data outlive the container.

What the output means: Nothing runs yet — this is a description. It defines a three-service app (web api + Postgres database + Redis cache) ready to launch with one command.

Try this: Read it top to bottom and list the three service names out loud. Then find where the api gets the database's address — that @db:5432 is the whole trick of service-name networking.

These are the everyday commands for running the app you just described. Each starts with docker compose, which reads the docker-compose.yml in the current folder and acts on all the services at once.

1. docker compose up -d builds and starts every service. -d means "detached" — it runs in the background and gives your terminal back instead of filling it with logs.
2. docker compose ps lists what's running, so you can confirm all services came up.
3. docker compose logs -f api shows the api service's output; -f "follows" it live, like watching a tail. Swap api for another service name to watch that one.
4. docker compose exec db psql -U app opens a shell inside the running db container — here the Postgres client — so you can poke at the database.
5. docker compose down stops and removes the containers. Adding -v also deletes the volumes, which wipes your data — so leave -v off unless you truly want a clean slate.

What the output means: After up -d the whole app is running in the background; ps and logs let you inspect it, and down tears it back down.

Try this: Run up -d, then ps to see three services, then down (without -v) and up -d again — your database data should still be there because the volume survived.

This fixes a classic trap: depends_on waits for a container to start, but a database can be "started" and still not ready to answer queries — so the api connects too early and crashes. The fix is a healthcheck: a little test Compose runs until the service is truly ready.

1. Under db, the healthcheck: block defines the readiness test. test: ["CMD-SHELL", "pg_isready -U app"] runs Postgres's own pg_isready command, which succeeds only once the database is actually accepting connections.
2. interval: 5s checks every 5 seconds, timeout: 3s gives each check 3 seconds to answer, and retries: 5 means it tries up to 5 times before declaring the service unhealthy.
3. Under api, depends_on now uses the longer form with condition: service_healthy. That says: don't start the api until the db healthcheck actually passes — not merely until its container exists.

What the output means: With this in place, Compose holds the api back until Postgres reports healthy, so the api never crashes trying to connect to a database that isn't ready yet.

Try this: Picture removing the healthcheck: the api would launch the instant the db container appears, often a second too early, and fail on boot. The healthcheck is the difference between "started" and "ready".

This small Python program answers "in what order must these services start?" given who depends on whom. It's the same reasoning depends_on does, written out so you can see it. The technique is a topological sort: order things so every dependency comes before the thing that needs it.

1. def start_order(deps): takes a dictionary mapping each service to the list of services it needs first. order collects the answer; done remembers which services we've already placed.
2. visit(s, stack) is a helper that handles one service. stack is the chain of services we're currently in the middle of — if s is already in it, we've gone in a circle, so it raises dependency cycle (A needs B needs A can never start).
3. Before adding a service, the for d in deps.get(s, []) loop visits every service it depends on first. Only after those are placed do we done.add(s) and order.append(s) — guaranteeing dependencies land earlier in the list.
4. The final for s in deps: visit(s, set()) kicks the process off for every service, then returns the safe start order.

What the output means: It prints ['db', 'cache', 'api', 'worker']: the database and cache come first (nothing depends on them yet), then the api (needs both), then the worker (needs the db). Every service appears after the things it relies on.

Try this: Add a fake cycle — set "db": ["api"] so db needs api and api needs db — and run it. You'll get the dependency cycle error, which is exactly the mistake a topological sort is designed to catch.

This is the realistic, put-it-all-together stack: four services — api, worker, db, cache — with health gating, saved data, and shared config. It combines every idea from the lesson into one file you'd actually run locally.

1. api builds from your Dockerfile, exposes port 8000, and reads its settings from a shared .env file via env_file: .env (so secrets live in one place, not in the YAML).
2. Its depends_on waits for db to be service_healthy and cache to be service_started. restart: unless-stopped tells Compose to relaunch the container if it crashes.
3. worker reuses the same built image as the api but overrides the startup command with command: python -m worker — one image, two roles. This is a common, money-saving pattern.
4. db (Postgres) keeps its data in the dbdata volume and has the same healthcheck you saw earlier; cache (Redis) keeps its data in cachedata.
5. The bottom line volumes: { dbdata: {}, cachedata: {} } declares both named volumes so the database and cache data persist across restarts.

What the output means: A production-shaped app on your laptop: web api + background worker + database + cache, all wired by name, started in the right order, with data that survives restarts.

Try this: Spot the two services that share an image (api and worker) and the one line that makes them behave differently. Then find every service that saves data and match it to a name in the bottom volumes block.

Dev and production want different setups: while coding you want your edits to appear instantly; in production you want the frozen, built image. Compose lets you keep a small override file with just the dev-only differences, layered on top of the base file.

1. The filename matters: docker-compose.override.yml is loaded automatically alongside docker-compose.yml when you run docker compose up in dev. You don't name it explicitly.
2. volumes: [".:/app"] is a bind mount: it maps your current project folder into the container at /app. Now editing a file on your machine changes it inside the container instantly — no rebuild.
3. environment: { ENV: dev } flags this as a dev run, and the command: line starts the server with --reload, so it restarts itself whenever you save a file.
4. The comment at the bottom shows production: run docker compose -f docker-compose.yml up -d to use only the base file — no code mount, no auto-reload, just the built image.

What the output means: In dev, Compose merges base + override so you get live-reloading code; in prod, you point at only the base file and get the stable, built version. One codebase, two behaviors.

Try this: Notice you never duplicate the whole config — the override only lists what changes for dev. That's why the base file stays clean and production-ready.

This runnable helper answers "does my compose file actually contain the services it should?" — a quick sanity check a tech lead might run so a teammate's stack isn't missing a piece. It reads the YAML as plain text and looks for the service names.

1. check_stack(compose_yaml, required) takes the compose file's text and a list of service names you expect to find.
2. re.findall(r"^ (\w+):", compose_yaml, re.M) uses a regular expression to grab every name indented by exactly two spaces followed by a colon — i.e. the service names under services:. present is the set it found.
3. missing = [s for s in required if s not in present] lists any required service that's absent. The function returns (not missing, missing): a True/False "is it complete?" plus the list of what's missing.
4. The two print calls test it against a sample compose file that has api, db and cache but no worker.

What the output means: First line prints (True, []) — all of api+db+cache are present. Second prints (False, ['worker']) — the stack is incomplete because worker is missing. The empty vs non-empty list tells you exactly what to add.

Try this: Add worker: to the sample compose string and re-run — the second line should flip to (True, []). This is a tiny version of the automated checks real teams put in CI.