Conceptly
← All Concepts
🎼

Docker Compose

OrchestrationThe tool for declaring multiple container services in one file

Docker Compose is the tool for defining and running multiple container services from one `compose.yml` file. It acts as a lightweight orchestration layer for application stacks rather than single containers.

β–ΆArchitecture Diagram

πŸ” Structure

Dashed line animations indicate the flow direction of data or requests

Why do you need it?

As soon as an application needs a web container, an API, a database, and perhaps a cache, raw `docker run` commands become long and fragile. Ports, environment variables, networks, and volumes must all line up. Dependency order also becomes painful when one service needs another to be ready before it can start cleanly.

Why did this approach emerge?

Containers solved packaging for individual workloads, but real applications are usually service sets. Teams especially needed one standard way to start the same multi-container project in development and testing. Compose became the declarative layer for that smaller-scope orchestration problem.

How does it work inside?

A Compose file declares each service's image or build rule, ports, environment variables, networks, and volumes. `docker compose up` then creates the project-level resources and starts the services according to that declaration. Service names become internal DNS names, so one service can call another by name instead of by fixed IP.

Seen as a Compose file

Defining a web service and a database together

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

volumes:
  db-data: {}

Once services, storage, and readiness checks sit in one file, the execution recipe lives in the declaration itself rather than in a separate setup document.

Service names become internal DNS names

services:
  api:
    image: my-api:latest
  worker:
    image: my-worker:latest
    environment:
      API_BASE_URL: http://api:8080

Inside one Compose project, `api` can be used directly as a hostname, so teams do not need to hard-code container IP addresses.

Boundaries & Distinctions

Compose and Dockerfile are both text files in the container workflow, but they sit at different scopes. Dockerfile defines how one image is built. Compose defines how multiple services should run together. Compose also sits above the runtime layer rather than replacing it.

When should you use it?

Compose is especially effective for local development, integration testing, and small production-style stacks where teams want one repeatable project command. It reduces onboarding friction by turning setup steps into declarations. The key design choice is not to force everything into one file, but to group only the services that truly belong in one runnable stack.

Local development stacksIntegration test environmentsShared infrastructure declarationsStartup coordination