Introduction to Docker Compose

Most applications consist of multiple services - an API, a database, a cache, a message broker, and perhaps a scheduler. Managing these individually with docker run commands leads to mistakes: forgotten network flags, mismatched passwords, and uncertainty about which container runs on which port. Docker Compose solves this by describing the entire stack in a single YAML file and bringing it up with one command, eliminating the guesswork of multi-container deployments.

What Docker Compose Is

Docker Compose is the tool that ships with Docker for defining and running multi-container applications. You declare services, networks, and volumes in a compose.yaml file (the old name docker-compose.yml still works), and docker compose up -d creates the network, pulls the images, builds what needs building, and starts everything in dependency order.

One naming note that confuses people: the modern command is docker compose (a Docker plugin, with a space) — the standalone docker-compose binary is the older v1 tool. Both read the same file; modern files no longer need a version: key at the top, and if you see one in an old guide you can safely drop it.

A Compose File That Looks Like Real Life

This is the shape of a typical stack: an API built from a local Dockerfile, a PostgreSQL database, and health checks so the API does not start before the database is actually ready:

services:
  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      - DB_HOST=db
      - DB_USER=postgres
      - DB_PASSWORD=${DB_PASSWORD}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

Compared with a "hello world" example, the practical differences that actually matter in daily use:

How Compose Networking Works

Compose creates a default network for the project, and every service can reach every other service by service name: inside the API container, the database is reachable at db:5432 rather than localhost:5432 (inside the container, localhost is the container itself). This is why the API uses DB_HOST=db. You never need to know the database container's IP address — Compose's built-in DNS handles it, and that is also the basis of the bridge network model.

The Commands You Will Actually Use

Problems You Will Hit and Why

The most common failure with this file is a port conflict: if anything else on the host already listens on 5432 (a natively installed PostgreSQL, for instance), up fails with bind: address already in use. The container's internal port stays the same — change only the left-hand side of the mapping, e.g. "5433:5432", and update DB_PORT in the API.

The second classic: docker compose down followed by "where did my data go?" — data is safe because it lives in the named pgdata volume, not in the container. Containers are ephemeral; volumes are the point of persistence, which matters when you back up and restore databases.

Where to Go Next

Compose removes the "which container, which port, which network" guesswork from a multi-service stack. The file above is a solid template: a healthchecked database, an API that waits for it, secrets outside the repo, and a restart policy that keeps things running.

A.M. Rinas

Written by A.M. Rinas

Full-Stack Software Engineer working on web applications, DevOps automation, and databases. More about me on the about page, or say hi through the contact page and LinkedIn.

← Back to all articles