Lesson 5 of 9 · 10 min · Running real applications

Docker Compose: multi-container applications

Covers: Docker Compose 5 on Ubuntu 24.04; python 3.12-slim, postgres 16-alpine. Updated 13 Nov 2026. Part of the DevOps Engineer roadmap.

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_on with conditions
  • The commands you use daily, and what down and down -v delete

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 web or db.
  • 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 either image: (pull) or build: (build from a Dockerfile in that directory, with optional context, 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 watch or a reloading dev server, expose debug ports, use docker-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 -v at 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 -d layers a production override on the base file.

Common mistakes

  • Assuming depends_on waits for readiness. Add health checks and connection retries.
  • Tabs in YAML or unquoted ports (80:80 can be misread as base-60 numbers in old YAML parsers).
  • Committing secrets in environment:.
  • down -v on 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 latest image tags.
  • Expecting Compose to scale across machines.

Try it yourself

  1. 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.
  2. Remove the health check and condition, restart from scratch, and watch whether the app can start before the database is ready.
  3. Run down, then up: is your data still there? Then try down -v.
  4. Create a docker-compose.override.yml that 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, down cover daily work; down -v deletes volumes.
  • Use health checks with depends_on conditions and make the app retry.
  • It is perfect for development, CI and small deployments; Kubernetes takes over for clusters.

Going deeper

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.