Lesson 5 of 9 · 10 min · Running real applications
Docker Compose: multi-container applications
What you will learn
- What Compose is for and when it is the right tool
- The structure of
compose.yaml: services, volumes, networks - Environment variables,
.env, ports, restart policies - Health checks and
depends_onwith conditions - The commands you use daily, and what
downanddown -vdelete
In simple words
A real application is rarely one container. It is a website, a database and perhaps a cache, all working together. Starting each by hand with a long command is tiring and easy to get wrong. Compose lets you describe all of them in one file and start the whole set with one command.
Words to know
- Compose: the Docker tool that runs several containers from one description file.
- compose.yaml: the file that lists the containers and how they connect.
- Service: one part of the application in that file, such as
webordb. - Health check: a small test that tells Docker whether a container is really ready, not just started.
Why Compose
A real application is several containers: a web app, a database, a cache, a worker. Starting each with a long docker run command and wiring them by hand is error-prone. Docker Compose lets you describe the whole stack in a YAML file and manage it with one command. It is ideal for local development, tests in CI and small single-host deployments. For clusters of machines with scaling and self-healing, the next step is Kubernetes (a later course); Compose files are a good first model of the same ideas.
A complete example
compose.yaml (the file name compose.yaml is the current default; docker-compose.yml still works):
services:
web:
build: .
ports:
- "18090:8000"
environment:
DB_HOST: db
APP_ENV: ${APP_ENV:-dev}
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD: example
volumes:
- dbdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 3s
timeout: 3s
retries: 10
volumes:
dbdata:
YAML cares about indentation (spaces, never tabs). The top-level keys:
services: each entry becomes one or more containers. A service uses eitherimage:(pull) orbuild:(build from a Dockerfile in that directory, with optionalcontext,dockerfile,args,target).volumes: named volumes the services can mount.networks: custom networks (optional; the next lessons).
Service keys you will use all the time:
| Key | Purpose |
|---|---|
image, build |
where the image comes from |
ports |
"host:container" publishing (always quote them) |
environment, env_file |
variables, from the file or a separate .env-style file |
volumes |
named volumes or bind mounts (./src:/app/src) |
depends_on |
start order and conditions |
restart |
no, on-failure, always, unless-stopped |
command, entrypoint |
override the image's defaults |
healthcheck |
how to test that the service is healthy |
deploy.resources, mem_limit, cpus |
limits |
user, read_only, cap_drop |
hardening |
Variables and .env
Compose substitutes ${VAR} from your shell environment or from a file named .env next to the compose file. ${APP_ENV:-dev} means "use APP_ENV, defaulting to dev". docker compose config shows the final, fully substituted file; with APP_ENV=prod it printed APP_ENV: prod. Keep secrets out of the compose file and out of Git (see the secrets lesson); commit a .env.example instead of .env.
Running it
docker compose config --quiet # validate; prints nothing when valid
docker compose up -d --build # create networks and volumes, build, start in the background
docker compose ps
docker compose logs -f web # follow one service's logs
docker compose exec web sh # shell in a running service
docker compose down # stop and remove containers and networks
What up did in our test:
Network comp_default Created
Volume comp_dbdata Created
Container comp-db-1 Started
Container comp-web-1 Started
and docker compose ps:
SERVICE STATE HEALTH PORTS
db running healthy 5432/tcp
web running 0.0.0.0:18090->8000/tcp
The web service answered on the published port (hello from 1d74d65258e9 ...). Notes on what Compose created: a project named after the directory (comp), a default network comp_default shared by all services, the volume comp_dbdata, and containers named <project>-<service>-<number>. Everything is labelled with the project so down knows what to remove.
Useful commands: docker compose up -d --scale web=3 (several replicas; remove fixed host ports first), docker compose pull, docker compose build --no-cache, docker compose restart web, docker compose run --rm web pytest (a one-off container), docker compose top.
Start order and health
depends_on alone only controls the order in which containers are started, not whether the dependency is ready. A database container is "started" long before it accepts connections, so the app would fail on first connect. Use a health check on the dependency and wait for it:
depends_on:
db:
condition: service_healthy
pg_isready returns success when PostgreSQL accepts connections; Compose waited for healthy before starting web. Even so, applications should retry their connections with backoff: databases restart, networks blip, and depends_on does not help after the first start. Health checks should be cheap and test what really matters.
What `down` deletes
docker compose down # removes containers and the project's network, KEEPS named volumes
docker compose down -v # also removes the project's named volumes: your data is gone
Our test: after down, docker volume ls still listed comp_dbdata; after down -v the volume count was 0. Make this distinction habit. Also docker compose stop/start keep containers, only pausing them.
Compose in practice
- Development: bind-mount source code, use
docker compose watchor a reloading dev server, expose debug ports, usedocker-compose.override.yml(merged automatically) or profiles (profiles: ["debug"]) for optional services. - CI:
docker compose up -d, run tests against real dependencies (database, cache),docker compose down -vat the end. - Production on one host: workable for small services with
restart: unless-stopped, a reverse proxy container with TLS, pinned image tags, backups of volumes, and monitoring. Know its limits: one machine, no automatic rescheduling if the host dies, manual rolling updates. - Multiple files:
docker compose -f compose.yaml -f compose.prod.yaml up -dlayers a production override on the base file.
Common mistakes
- Assuming
depends_onwaits for readiness. Add health checks and connection retries. - Tabs in YAML or unquoted
ports(80:80can be misread as base-60 numbers in old YAML parsers). - Committing secrets in
environment:. down -von a database you wanted to keep.- Publishing database ports (
5432:5432) on a server. Services reach each other by name inside the network; publish only what users need. - Using
latestimage tags. - Expecting Compose to scale across machines.
Try it yourself
- Write a compose file with a web app and PostgreSQL (or Redis), start it, and prove the web container can resolve and reach the database by service name.
- Remove the health check and
condition, restart from scratch, and watch whether the app can start before the database is ready. - Run
down, thenup: is your data still there? Then trydown -v. - Create a
docker-compose.override.ymlthat bind-mounts source code for development.
Check yourself
What does depends_on do, and what does it not do?
It controls start order and, with condition: service_healthy, waits for a health check. By default it does not wait for the service to be ready, only for its container to start.
What is the difference between docker compose down and docker compose down -v?
down removes containers and networks but keeps named volumes. down -v also deletes the project's named volumes, destroying persisted data.
How do services in one Compose project reach each other?
By service name over the project's default network (Compose's embedded DNS), for example db:5432. No published ports are needed for internal traffic.
When is Compose not enough?
When you need multiple hosts, automatic rescheduling after node failure, rolling updates, autoscaling or advanced networking; use Kubernetes or a managed container service.
Interview questions
How would you run integration tests that need a database in CI?
Define the app and database in a compose file with a health check, docker compose up -d --wait, run the tests against the services, then docker compose down -v to clean up.
How do you pass configuration to different environments?
Environment variables or env files per environment, override files (-f compose.prod.yaml), and secrets via the platform's secret mechanism, never hard-coded in the image.
What is the benefit of defining infrastructure in compose.yaml instead of shell scripts of docker run?
It is declarative and versioned, reproducible, readable, and handles networks, volumes, dependencies and lifecycle consistently with a few commands.
Summary
- Compose describes a multi-container stack in one YAML file: services, volumes, networks.
up -d --build,ps,logs,exec,downcover daily work;down -vdeletes volumes.- Use health checks with
depends_onconditions and make the app retry. - It is perfect for development, CI and small deployments; Kubernetes takes over for clusters.
Going deeper
- Docker Compose overview: concepts and getting started.
- Compose file reference: every key in
compose.yaml. - Control startup order in Compose:
depends_on, health checks and retries. - Use Compose in production: what to change for a server.
See how much of this you can explain
A free mock interview asks you new questions on Docker and containers for DevOps Engineer and scores every answer, with what to fix.