Lesson 144 taught you Compose and Lesson 143 taught you networking. This lab is where you build the whole app in one file: web, API, database, and cache, on one custom network, with the API waiting for the database to be healthy before it starts. By the end you have four services, all healthy, and the web answers hello through the API, because the containers talk to each other by name, not by IP.
Difficulty: Advanced · Know this first: Lesson 144 — Docker Compose; Lab 156; Docker Desktop installed and running
Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenario — not a measurement from a live system — but the shape is honest: on a cache hit the trip is almost free, on a miss the kitchen eats the budget. Step through the lesson or switch the scenario and watch the bar change.
Extra diagram · from scratch to master
Start with one network. Add one box at a time until four services are healthy and the data survives a restart.
The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the wiring, the start, and the total change in the budget bar, in the hop timings, and in the total. The numbers are a teaching example, not live measurements. The shape is the lesson: more services means more wiring, and a missing gate costs a restart.
How many services the file holds. Each service is one more block to wire, one more name to resolve, and one more row on the status board.
How many custom networks the app uses. Each network is one more isolation boundary, and services on different networks cannot see each other.
How long each service takes to become healthy. The API waits for the database, so a slow database delays the whole app.
Try this: (1) Set services to 4, networks to 1, wait to 5. The wire is about 5 min, the start about 2 min, the prove about 1 min, and the total is about 13 min. (2) Set all three to the worst end: 12 services, 3 networks, 30 s wait. The wire is about 15 min, the start about 36 min, the prove about 1 min, and the total is about 57 min. Same file shape. Only the inputs changed.
Three questions. No score is saved anywhere — this is just you against the material.
Here is the compose file from this lab, ready to edit. Change it, then run the check. The check looks for the five things a working compose file needs: services, a health-gated depends_on, a healthcheck, a network, and a volume.
Try breaking it on purpose: delete the service_healthy condition, or remove the healthcheck. Run the check and watch it fail. Then press Reset and try a change that keeps it passing, like adding a second volume.
Expected output when it passes: The file has four services, a health-gated depends_on, a database healthcheck, a custom network, and a named volume. docker compose config would print it back clean.
docker compose config, flag by flag. config prints what Compose really got, after every file and variable is layered. It is the fastest way to check a compose file without starting anything.
docker compose config prints the merged compose file. It is the fastest way to see what Compose really got, after all the files and variables are layered together.--quiet only checks the file is valid and prints nothing. Without it config prints the whole merged YAML. I use --quiet in a check, and plain config when I want to read the merge.--services prints only the service names, one per line. Without it config prints the whole merged file.--volumes prints only the volume names, one per line. Without it config prints the whole merged file.Flags you will meet next: config --models prints the model names, and --variables prints the variables and their defaults.
Try it: run config --quiet and check the exit code: 0 means the file is valid. Then run config --services and read the names. If a service is missing from that list, Compose never saw it.
I take the same app four times here. First I network it. Then I write it. Then I gate it. Last I prove it.
Definition: A custom network gives containers DNS by name. docker network create makes one. A container on app-net can reach another by its name, like db or cache. On the default bridge, there is no DNS, and containers only have IPs.
docker network, flag by flag. The network commands are the whole lesson in four verbs: create it, join it, list it, and read it.
docker network create app-net makes the network. The name is the address the containers use to join it. Without the network, every container lands on the default bridge.Flags you will meet next: docker network create --driver overlay spans many hosts, --subnet picks the address range, and docker network connect --alias web2 gives a container a second name.
Try it: create app-net, run two containers on it, and ping one by name from the other. Then run docker network inspect app-net and read the Containers block. The two containers should both be listed there.
Types:
Uses: I use a custom network for every app, one per app, every time. Try it now: create app-net and run nslookup db on it.
ping and nslookup, flag by flag. The app uses a name, not an IP. So I test the name, not the IP. These two commands are the test.
ping -c 1 db sends one packet and stops. Without -c it runs until I stop it. The name db is the test: on a custom network it resolves, and on the default bridge it does not.nslookup db asks the DNS server for the name db and prints the answer. Without a name there is nothing to look up. The app uses the name, not the IP, so the name is what I test.Flags you will meet next: ping needs a raw socket, which this VM does not allow, and a slim container may not have the ping binary at all. nslookup is the check that works in both places.
Try it: run both from inside a container on app-net, then from one on the default bridge. On app-net the name resolves and the ping answers. On the bridge the name does not resolve at all. That is the finding, and it is why the lesson uses a custom network.
Dimensions: At low volume everything is instant. What breaks first is the default bridge: names do not resolve there, and the lookup fails.
Definition: A compose file holds services, networks, and volumes. Each service names its image or build, its environment, its ports, and its networks. docker compose config prints the file back, parsed, and a file that does not parse gives an error instead.
Types:
Uses: I use one file for the whole app, so the app can be started with one command. Try it now: write compose.yaml and run docker compose config on it.
Dimensions: As the app grows, the file grows, and the services multiply. What breaks is an indent: YAML cares about spaces, and one wrong indent breaks the whole file.
Definition: A healthcheck turns running into healthy. depends_on with condition service_healthy makes one service wait for another to be healthy. Running is not ready, and the gate is what stops the API from starting before the database can answer.
Types:
Uses: I use a health gate whenever one service needs another to be ready, which is nearly always. Try it now: remove the condition from the lab file, up the app, and watch the API log fill with refused connections.
Dimensions: At ten times the services, the gates multiply, and the start order matters more. What breaks is a gate on a service with no healthcheck: the condition waits forever, because healthy never arrives.
Definition: At this level the proof is not that the app starts. It is that the data survives a restart. down keeps the named volume. down -v deletes it. A database that loses its data on restart is a cache, not a database, and the restart test is how you tell.
Types:
Uses: I use this before I trust any database in Compose: up, write, down, up, read. Try it now: run the restart test from step 7 and check the data is still there.
Dimensions: At a hundred services, the file is the same shape, and the volumes are the same. What breaks is a volume that was never named: an anonymous volume is deleted with the container, and the data goes with it.
The compose file, the whole file. Do this: save it as compose.yaml and run docker compose config. Expected output: the file prints back, parsed and expanded, with no error. This file was checked in this lab: it parses clean with yaml.safe_load, it holds four services, a health-gated depends_on, a database healthcheck, a network, and a volume.
services:
web:
build: .
ports: ["3000:3000"]
depends_on:
api:
condition: service_healthy
networks: [app-net]
api:
build: ./api
environment:
DATABASE_URL: postgres://db:5432/app
CACHE_URL: redis://cache:6379
depends_on:
db:
condition: service_healthy
networks: [app-net]
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: changeme
volumes: [db-data:/var/lib/postgresql/data]
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 5
networks: [app-net]
cache:
image: redis:7
networks: [app-net]
networks:
app-net:
driver: bridge
volumes:
db-data:
Prove DNS by name, the standalone check. Do this: run docker network create app-net, then start a database container on it, then run docker run --rm --network app-net busybox nslookup db. Expected output: the lookup prints the database IP. Run the same lookup on the default bridge and expect it to fail. That failure is the reason for the custom network.
docker run --network, flag by flag. The network flag decides who the container can find by name. It is one flag, and it changes everything about the run.
-d runs the container in the background and prints its ID, then returns the prompt. Without it the terminal stays attached to the app, and closing the terminal stops the container.--name hello names the container. Without it Docker picks a random name, and every later command has to use the ID or that random name.--network app-net puts the container on the named network. Without it the container lands on the default bridge, where names do not resolve and the app cannot find the database by name.-p 3000:3000 publishes a container port on the host. The order is host port first, container port second. Without it the port stays private inside the container network, and nothing on the host can reach it.--rm removes the container when it stops. Without it the stopped container stays listed and keeps its name, so the next run with the same name fails with a name conflict.Flags you will meet next: --network host puts the container on the host network with no isolation, and --network none gives it no network at all.
Try it: run two containers on app-net and ping one by name from the other. It answers. Then run a third container with no --network flag and ping it by name. It does not answer. The flag is the difference.
What service_healthy means: the API waits until the database healthcheck reports healthy, not merely until the container is Up. Do this: remove the condition from the api depends_on, run docker compose up -d, and read docker compose logs api. Expected output: connection refused lines, because the API started before the database was ready. Put the condition back, down, up, and watch the log stay clean.
docker compose logs, flag by flag. Logs are per service here, not per container. The service name is the filter.
docker compose logs api shows the logs of one service. Without the service name I get every service mixed together, and the error I want hides in the middle.Flags you will meet next: -f follows the logs, and --tail 50 shows the last fifty lines.
Try it: run docker compose logs api, then run it with no service name. The first shows one service. The second shows every service mixed together, and the error hides in the middle.
docker compose up -d, flag by flag. up builds the stack and starts it. -d is the flag that gives me my terminal back.
up -d creates and starts the services. -d detaches, so the prompt comes back at once. Without -d the logs fill the terminal, and the stack stops when I close it.Flags you will meet next: --build rebuilds the images before starting, and --force-recreate recreates the containers even when nothing changed.
Try it: run up -d, then run docker compose ps. The services should show as running. Then run up without -d in a scratch terminal and watch the logs fill it. Stop it with Ctrl-C and note the stack stops with you.
Honest limit, stated plainly: this lab was verified by parsing compose.yaml and by reading the Docker docs, not by running docker compose. There is no Docker daemon in the machine this lab was written on, so no container was actually started here. The commands, the outputs, and the checks are the ones the reader runs on their own machine, where Docker Desktop is running.
At 10x the services, the shape holds and the file grows. At 100x, the design changes: the app moves into a cluster, and Compose becomes the local copy of a bigger system. The names never change, though. Services still talk by name, and healthy still means ready.
An app I owned started its API before its database every single deploy, and every deploy filled the API log with refused connections for the first minute. The team called it normal: the API retried, the database came up, and the errors stopped. One day the database took three minutes to start, the API gave up retrying after one minute, and the deploy failed. The retry had been hiding a missing gate for months, and the gate was one line in the file.
Two things. First, every depends_on in the file now names a health condition, and a depends_on without one is treated as broken in review. Second, the API log is read after every deploy, and a refused connection in it is a ticket, not background noise. Try it now: up the lab app, read the API log, and confirm it has no refused connections.
Build a compose app for a service you choose, with at least three services, one custom network, one named volume, and a health gate on every start that needs one. It passes when all services report healthy, the web answers, and the data survives a down and up.
Success looks like this: config prints clean, ps shows healthy for every service, the web answers, the API log has no refused connections, and the data survives a restart. If the API log shows refused connections, the gate is missing. If the data is gone after the restart, the volume was not named.
If config fails, read the line it names: it is usually an indent. If a name does not resolve, the service is on the wrong network. If the gate waits forever, the service it waits on has no healthcheck. If the data is gone, you ran down -v, or the volume was anonymous.