Skip to content
Velloreth
Developer Tools 7 min read

Docker Compose: Running Multi-Container Apps Locally

Compose defines a multi-container application in one file. Learn services, networks, volumes, and the commands you use daily.

By

The file

Compose defines a multi-container application in compose.yaml.

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    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
      timeout: 5s
      retries: 5

volumes:
  pgdata:

Start it:

docker compose up
docker compose up -d      # detached
docker compose up --build # rebuild first

Stop it:

docker compose down
docker compose down -v    # also remove volumes

Services

A service is a container definition. Compose creates one container per service by default.

Build from a Dockerfile:

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile

Use an image:

services:
  db:
    image: postgres:16-alpine

Ports:

ports:
  - "3000:3000"       # host:container
  - "127.0.0.1:3000:3000"  # bind to localhost only

Environment:

environment:
  NODE_ENV: production
  PORT: 3000

Or from a file:

env_file:
  - .env

Command override:

command: npm run dev

Restart policy:

restart: unless-stopped

Networking

Compose creates a network and attaches every service to it. A service reaches another by its service name.

services:
  api:
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app

The hostname db resolves to the db service’s container. This is why you do not need to know the container’s IP.

Custom networks:

services:
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
  backend:

This isolates the database from the frontend, so only the API can reach it.

Volumes

Named volume:

volumes:
  - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Named volumes persist across docker compose down. They are removed only with -v.

Bind mount:

volumes:
  - ./src:/app/src

The host path is mapped into the container. Edits appear immediately, which is why this is the standard development setup.

Read-only bind mount:

volumes:
  - ./config:/app/config:ro

depends_on and healthchecks

depends_on controls start order, but it does not wait for the dependency to be ready.

depends_on:
  - db

This starts db before api, but api may start before Postgres is accepting connections. The result is a connection error on startup.

The fix is a healthcheck plus a condition.

services:
  api:
    depends_on:
      db:
        condition: service_healthy

  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 5s
      timeout: 5s
      retries: 5

Now Compose waits for the healthcheck to pass before starting api.

This is the most common Compose mistake, and the healthcheck is the fix.

Development workflow

A typical development setup mounts the source and runs a watcher.

services:
  api:
    build: .
    volumes:
      - ./src:/app/src
      - /app/node_modules   # keep the container's node_modules
    command: npm run dev
    ports:
      - "3000:3000"

The anonymous volume at /app/node_modules is important: it prevents the host’s node_modules from overwriting the container’s, which would break native modules built for a different platform.

Override file. compose.override.yaml is merged automatically, which is the place for development-only settings.

# compose.override.yaml
services:
  api:
    volumes:
      - ./src:/app/src
    command: npm run dev

The base file stays production-like, and the override adds development conveniences.

Useful commands

docker compose up -d
docker compose down
docker compose ps
docker compose logs -f api
docker compose exec api sh
docker compose build
docker compose pull
docker compose restart api
docker compose run --rm api npm test
docker compose config   # validate and print the merged config

docker compose config is the fastest way to check that the file is valid and to see the merged result of the base and override files.

Compose versus Kubernetes

Compose runs containers on a single host. It is aimed at local development and simple deployments.

Kubernetes orchestrates containers across many hosts, with scaling, rolling updates, self-healing, and service discovery. It is aimed at production at scale.

The honest assessment: Compose is the right tool for development and for a small deployment on one machine. Reaching for Kubernetes for a single-host application adds a large amount of complexity for no benefit.

Common mistakes

A connection error on startup. depends_on started the dependency but did not wait for it to be ready. Add a healthcheck and condition: service_healthy.

Data lost after down. The volume was anonymous, or -v was used. Use a named volume and avoid -v unless you intend to delete the data.

The host’s node_modules overwriting the container’s. A bind mount of the whole project copies the host’s node_modules over the container’s, which breaks native modules built for a different platform. Add an anonymous volume at /app/node_modules.

A service not reachable by name. The services are on different networks, or the name is misspelled. Check with docker compose config and docker network inspect.

Changes not taking effect. The image was not rebuilt. Use docker compose up --build.

A port conflict. Two services map the same host port. Change one, or remove the host mapping for a service that only needs to be reachable internally.

Environment variables not set. The env_file path is relative to the Compose file, not the working directory, which is a common surprise.

Compose profiles

Profiles let you start a subset of services.

services:
  api:
    build: .
  debug:
    image: busybox
    profiles: ["debug"]
docker compose up              # starts api only
docker compose --profile debug up   # starts api and debug

This is useful for optional services: a database admin tool, a mail catcher, or a profiler that is not needed every day.

Compose in CI

Compose is useful in a continuous integration pipeline, because it can start the dependencies a test needs without a separate service configuration. A test job that needs Postgres and Redis can start them with Compose, run the suite, and tear them down, all within the job. The alternative is to configure the services in the CI platform’s own syntax, which duplicates the local setup and drifts from it over time. Using the same Compose file in CI and locally means the test environment matches the development environment, which is the point of the dev/prod parity idea. The one adjustment is usually to wait for the healthchecks to pass before running the tests, which the --wait flag does.

Migrating from Compose to production

Compose is a reasonable deployment tool for a single host, and many small applications run that way for years. The pattern is to build the images in CI, push them to a registry, and have the host pull and restart. A reverse proxy in front handles TLS and routing. The limits appear when you need more than one host: Compose has no scheduler, so it cannot place a container on the machine with capacity, and it has no self-healing across hosts. At that point the migration is to an orchestrator, and the Compose file is a useful starting point because it already describes the services, their dependencies, and their configuration. The concepts transfer: a service becomes a Deployment, a volume becomes a PersistentVolumeClaim, and an environment block becomes a ConfigMap and a Secret.

Practical guidance

  • Use service names as hostnames.
  • Add healthchecks and use condition: service_healthy.
  • Use named volumes for data that must persist.
  • Use bind mounts for development.
  • Keep node_modules in the container with an anonymous volume.
  • Use compose.override.yaml for development settings.
  • Run docker compose config to validate.
  • Use down -v only when you want to delete the data.

For the related guides, see docker-basics-guide and dockerfile-best-practices. For the broader context, environment-variables-explained and kubernetes-basics.

Quotable summary

Compose defines services, networks, and volumes in a single YAML file and starts them with one command, and services on the same Compose network reach each other by service name, which acts as a hostname. depends_on controls start order but does not wait for a service to be ready, so a healthcheck with condition: service_healthy is needed to avoid connection errors on startup. Named volumes persist data across docker compose down, while anonymous ones are removed, and down -v deletes the named volumes too. Compose is for local development and simple single-host deployments, while orchestration at scale needs Kubernetes. Use compose.override.yaml for development-only settings and docker compose config to validate the merged result.

Frequently asked questions

What is Docker Compose?
A tool that defines a multi-container application in a YAML file and manages the containers as a group. One command starts the whole stack, and another stops it.
How do services find each other in Compose?
Compose creates a network and attaches every service to it. A service can reach another by its service name, which resolves to the container's IP address.
What is the difference between depends_on and a healthcheck?
depends_on controls the order in which containers start, but it does not wait for the dependency to be ready. A healthcheck plus depends_on with condition: service_healthy waits for readiness.
Does docker compose down delete my data?
It removes the containers and the network, but named volumes are kept. Use docker compose down -v to also remove the volumes, which deletes the data.
What is the difference between Compose and Kubernetes?
Compose runs containers on a single host and is aimed at development and simple deployments. Kubernetes orchestrates containers across many hosts, with scaling, rolling updates, and self-healing.
How do I rebuild after changing the Dockerfile?
Use docker compose up --build, which rebuilds the images before starting. Without --build, Compose reuses the existing image.