Skip to content

Docker Compose

Define and run multi-container applications with a single docker-compose.yml file.

What you'll learn

  • What Docker Compose is and when to use it
  • Writing a docker-compose.yml file
  • Services, networks, and volumes
  • Common compose commands

Concept

What Is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. Instead of running multiple docker run commands with long lists of flags, you describe your entire application — services, networks, volumes — in a single docker-compose.yml file. Then one command, docker compose up, starts everything together. Compose is perfect for local development environments, CI pipelines, and small production deployments.

The Compose File

A docker-compose.yml file uses YAML syntax. Each service defines a container: which image to use, what ports to map, what volumes to mount, and what environment variables to set. You can also define custom networks for services to communicate and named volumes for persistent data. The file is version-controlled, so your entire development environment is reproducible by anyone on the team.

Services and Dependencies

Compose lets you express dependencies between services with depends_on. If your web app depends on a database, you can ensure the database starts first. You can also define health checks so Compose waits until a service is actually ready to accept connections, not just started. Environment variables can be loaded from .env files, and you can override settings with docker-compose.override.yml for local development.

Common Commands

docker compose up starts all services (add -d for detached). docker compose down stops and removes them. docker compose logs shows all logs. docker compose build rebuilds images. docker compose exec web sh opens a shell in a service. These commands manage your entire application stack as a unit, which is much simpler than managing containers individually.

Compose in Production

While Compose is primarily a development tool, it can be used in production with Docker Swarm (docker stack deploy -c docker-compose.yml myapp). For larger production deployments, Kubernetes is preferred, but Compose is excellent for small services, CI environments, and local development. Use docker-compose.override.yml for environment-specific changes — the base file defines the common configuration, and the override adds development-only settings like debug ports and volume mounts for hot reloading.

Example

              # docker-compose.yml — a web app with a database
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 5s

volumes:
  pgdata:
            

This compose file defines a web service and a database. The web service waits for the database health check before starting. The pgdata volume persists database data.

Try it

Common mistakes

The mistake

Using depends_on without health checks

The fix

depends_on only waits for a container to start, not to be ready. Add a healthcheck so Compose waits until the service can actually accept connections.

The mistake

Not pinning image versions in compose files

The fix

Use specific versions like postgres:16 instead of postgres:latest. Unpinned images lead to unpredictable behavior when new versions are released.

Practice Docker Compose

2 exercises

Practice Docker Compose

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors