Lesson 7 of 8 in Containers with Docker
Docker Compose for multi-service apps
Docker Compose reads a compose.yaml file that describes an app's services, networks and volumes, and starts them together with docker compose up. It creates a shared network where each service is reachable by its service name.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Volumes and bind mounts, Container networking
The problem this solves
Once an app has more than one container, the commands pile up: create a network, create volumes, start each container with the right flags in the right order. Nobody remembers all of that, and nobody else can reproduce it from your shell history.
Compose turns that pile into one file you commit next to your code. A teammate runs a single command and gets the same set of services, wired the same way.
How it works
- Control
- Runs code
- Data
Docker Compose reads compose.yaml and then creates the cache and web containers and the volume it describes.
- compose.yaml to docker compose: 1 read
- docker compose to cache service: 2 create
- docker compose to web service: 2 create
- docker compose to cache-data: 2 create
- Runs code
- Control
Compose can hold back a service until its dependency passes a health check, which is a stronger condition than the container merely running.
- cache to Health check: 1 probed repeatedly
- Health check to checker: 2 healthy, so start
A Compose file has top-level sections. services lists the containers: each has an image or a build, ports, environment, volumes and so on. volumes declares named volumes. Compose also makes a network for the project, and every service joins it, so services find each other by service name.
docker compose up creates whatever is missing and starts it. docker compose down stops and removes the containers and network, and keeps named volumes unless you add -v.
depends_on controls start order. By default it only waits until the dependency's container is running, which is not the same as the program inside being ready to accept connections. For real readiness, give the dependency a healthcheck and use condition: service_healthy.
Try it yourself
This example needs no code of your own. A cache service waits until it is healthy, and a second container asks it for a reply by name. Run it in a throwaway folder.
- 1Write the Compose file
mkdir -p ~/learn-compose && cd ~/learn-compose cat > compose.yaml <<'EOF' services: cache: image: redis:7-alpine healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 3s timeout: 2s retries: 10 volumes: - cache-data:/data checker: image: redis:7-alpine command: redis-cli -h cache ping depends_on: cache: condition: service_healthy web: image: nginx:alpine ports: - "8080:80" volumes: cache-data: EOFIndentation is meaningful in YAML. Use spaces, never tabs.
- 2Check the file, then start the app
docker compose config docker compose up -d
configprints the file as Compose understands it and reports mistakes.up -dstarts everything in the background. - 3See the state of each service
docker compose ps -a
cacheandwebare running.checkerruns one command and then shows as exited, which is expected. - 4Read the checker's answer
docker compose logs checker
You should see
PONG. The host namecachewas resolved by Compose's network, with no IP address written anywhere. - 5Reach the published service
curl http://localhost:8080
This is the nginx welcome page. Only
webpublishes a port.cacheis reachable only by other services. - 6Tear it all down
docker compose down -v cd ~ && rm -rf ~/learn-compose
-valso removes the named volume. That is right for this throwaway project, and dangerous for one with real data.
What breaks, and where to look
The app container starts, then crashes with connection refused to the database, but works if you restart it a few seconds later.
- WHY IT HAPPENS
depends_onwithout a condition only waits for the database container to be running. The database process inside was still starting up.- CHECK FIRST
- Add a
healthcheckto the database anddepends_on: { db: { condition: service_healthy } }. Watchdocker compose psfor the health status. Also make the app retry its connection on startup.
You changed the database password in compose.yaml and restarted, but logins still use the old password.
- WHY IT HAPPENS
- Many database images read their initial user and password only the first time, when the data directory is empty. The existing volume already holds the data created with the old values.
- CHECK FIRST
- Run
docker volume lsto confirm the volume exists. For a disposable dev database,docker compose down -vresets it. For real data, change the password inside the database instead.
yaml: line 7: mapping values are not allowed in this context, or services.web Additional property ... is not allowed.
- WHY IT HAPPENS
- An indentation or syntax mistake in the file, such as a mixed tab, a missing space after a colon, or a key in the wrong place.
- CHECK FIRST
- Run
docker compose config. It names the line and key it could not parse. Check that child keys are indented two spaces under their parent.
When not to use this
- Compose runs everything on one machine. For scheduling across many machines, self-healing and rolling updates, use an orchestrator such as Kubernetes.
- Do not commit real secrets into
compose.yaml. Use an.envfile kept out of version control, or a secrets mechanism.
Check yourself
How does one Compose service find another?
By its service name. Compose creates a shared network with name lookup, so cache resolves to that service's container.
Why is plain depends_on not enough for a database?
It waits only until the container is running, not until the database is ready for connections. Use a healthcheck with condition: service_healthy.
What does docker compose down -v remove that down does not?
The named volumes, and so any data stored in them.
Keep going
Lesson 45 of 92 in the DevOps path