Docker Compose

Pronunciation: DOK-er kum-POHZ

Updated October 3, 20262 min read

In short

Docker Compose is a tool for defining and running multi-container applications, such as a web server plus a database, from one YAML file with one command.

What is Docker Compose?

A real application rarely runs in one container. A typical setup needs the app itself, a PostgreSQL database, a Redis cache and perhaps a background worker, each with ports, environment variables and storage. Compose describes all of them in a compose.yaml file, and docker compose up starts the whole stack, with the containers able to reach each other by service name on a shared network.

Each service names an image to pull or a folder to build, and can declare ports, environment variables, volumes for data that should survive restarts, health checks and dependencies on other services. docker compose down stops and removes everything, logs shows the combined output, and exec opens a shell in a running service.

Compose is mostly used for local development and testing: a new developer clones the repository, runs one command and has the same database versions and settings as everyone else. It is also used for small single-server deployments and in CI pipelines to start the dependencies that integration tests need.

A common misconception is that Compose replaces Kubernetes. Compose runs containers on one machine and has no built-in scheduling across a cluster, self-healing or rolling updates across nodes. For production systems that span many servers, an orchestrator such as Kubernetes, or a managed container service, is the usual choice.

Key takeaways

Docker Compose runs multi-container applications from one YAML file.
docker compose up starts every service on a shared network.
Services declare images, ports, environment variables, volumes and health checks.
It is ideal for local development, testing and small single-server setups.
It runs on one machine; Kubernetes orchestrates clusters.

Example

A compose.yaml for an app with a database and a cacheyaml

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app   # "db" is the service name
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app"]

  cache:
    image: redis:8

volumes:
  db-data:

# docker compose up -d     start everything in the background
# docker compose down      stop and remove the containers

Readers ask

What is the difference between Docker and Docker Compose?

Docker builds and runs individual containers. Docker Compose sits on top and runs a group of containers that make up one application, defined together in a YAML file.

Should I use Docker Compose in production?

For small apps on a single server it can work well. For systems that need several servers, automatic failover or zero-downtime rolling updates, Kubernetes or a managed container platform is a better fit.

What is the difference between docker-compose and docker compose?

docker-compose with a hyphen is the original standalone tool. docker compose with a space is the newer version built into the Docker command line as a plugin, which is the one to use today. Both read the same file format.

Often compared

Docker Compose vs KubernetesDocker Compose runs a multi-container app on a single machine, while Kubernetes orchestrates containers across a cluster with scaling and self-healing.