Lesson 7 of 8 in Containers with Docker

Docker Compose for multi-service apps

Core12 min

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

One file describes the whole app
One file describes the whole appDocker Compose reads compose.yaml and then creates the cache and web containers and the volume it describes.1 read2 create2 create2 createcompose.yamlthe descriptiondocker composecreates and wirescache serviceredis containerweb servicenginx containercache-datanamed volume
  • Control
  • Runs code
  • Data

Docker Compose reads compose.yaml and then creates the cache and web containers and the volume it describes.

  1. compose.yaml to docker compose: 1 read
  2. docker compose to cache service: 2 create
  3. docker compose to web service: 2 create
  4. docker compose to cache-data: 2 create
Started is not the same as ready
Started is not the same as readyCompose can hold back a service until its dependency passes a health check, which is a stronger condition than the container merely running.1 probedrepeatedly2 healthy, sostartcachecontainer is runningHealth checkredis-cli pingcheckerneeds cache ready
  • 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.

  1. cache to Health check: 1 probed repeatedly
  2. 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.

  1. 1
    Write 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:
    EOF

    Indentation is meaningful in YAML. Use spaces, never tabs.

  2. 2
    Check the file, then start the app
    docker compose config
    docker compose up -d

    config prints the file as Compose understands it and reports mistakes. up -d starts everything in the background.

  3. 3
    See the state of each service
    docker compose ps -a

    cache and web are running. checker runs one command and then shows as exited, which is expected.

  4. 4
    Read the checker's answer
    docker compose logs checker

    You should see PONG. The host name cache was resolved by Compose's network, with no IP address written anywhere.

  5. 5
    Reach the published service
    curl http://localhost:8080

    This is the nginx welcome page. Only web publishes a port. cache is reachable only by other services.

  6. 6
    Tear it all down
    docker compose down -v
    cd ~ && rm -rf ~/learn-compose

    -v also 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_on without a condition only waits for the database container to be running. The database process inside was still starting up.
    CHECK FIRST
    Add a healthcheck to the database and depends_on: { db: { condition: service_healthy } }. Watch docker compose ps for 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 ls to confirm the volume exists. For a disposable dev database, docker compose down -v resets 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 .env file 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.

Lesson 45 of 92 in the DevOps path

Search

Search cheat sheets and projects