Docker Compose — Orchestrate Multi-Container Applications

Docker Compose describes a complete multi-container application in a single YAML file – services, networks and volumes included. Instead of starting each container by hand with long docker run commands, you bring the whole stack up with one docker compose up and tear it down again with docker compose down. Since Compose v2 the tool ships as the docker compose subcommand built right into the Docker CLI – the old hyphenated docker-compose is considered legacy. This guide walks you through the commands you reach for daily, from starting and scaling individual services through following logs to the building blocks of a compose file.

Basic Commands

docker compose up — Create and start all services defined in the compose file.

docker compose up

docker compose up -d — Start services in detached mode (background).

docker compose up -d

docker compose down — Stop and remove containers, networks, and default volumes.

docker compose down

docker compose down -v — Stop services and remove named volumes declared in the compose file.

docker compose down -v

docker compose down --rmi all — Stop services and remove all images used by the services.

docker compose down --rmi all

docker compose start — Start existing (already created) containers.

docker compose start

docker compose stop — Stop running services without removing containers.

docker compose stop

docker compose restart — Restart all services.

docker compose restart

docker compose restart <service> — Restart a specific service.

docker compose restart nginx

Service Management

docker compose ps — List containers and their status for the current project.

docker compose ps

docker compose ps -a — List all containers including stopped ones.

docker compose ps -a

docker compose up -d <service> — Start only a specific service (and its dependencies).

docker compose up -d web

docker compose stop <service> — Stop a specific service.

docker compose stop worker

docker compose rm <service> — Remove stopped service containers.

docker compose rm worker

docker compose up -d --scale <service>=<n> — Scale a service to n instances.

docker compose up -d --scale worker=3

docker compose up -d --no-deps <service> — Recreate a service without restarting its dependencies.

docker compose up -d --no-deps web

Logs & Monitoring

docker compose logs — View logs from all services.

docker compose logs

docker compose logs -f — Follow (stream) logs from all services in real time.

docker compose logs -f

docker compose logs <service> — View logs from a specific service.

docker compose logs nginx

docker compose logs -f --tail <n> <service> — Follow logs showing only the last n lines.

docker compose logs -f --tail 50 web

docker compose logs --since <time> — Show logs since a specific time or duration.

docker compose logs --since 30m

docker compose top — Display the running processes in each service container.

docker compose top

Executing Commands

docker compose exec <service> <command> — Execute a command in a running service container.

docker compose exec web bash

docker compose exec -T <service> <command> — Execute a command without a pseudo-TTY (for scripting).

docker compose exec -T db mysqldump mydb > backup.sql

docker compose exec -u <user> <service> <command> — Execute a command as a specific user.

docker compose exec -u root web bash

docker compose run <service> <command> — Run a one-off command in a new container (not the running one).

docker compose run web npm install

docker compose run --rm <service> <command> — Run a one-off command and remove the container afterwards.

docker compose run --rm web php artisan migrate

Building & Pulling

docker compose build — Build or rebuild all service images.

docker compose build

docker compose build <service> — Build a specific service image.

docker compose build web

docker compose build --no-cache — Build without using the layer cache (clean rebuild).

docker compose build --no-cache

docker compose pull — Pull the latest images for all services.

docker compose pull

docker compose up -d --build — Rebuild images before starting services.

docker compose up -d --build

docker compose push — Push built service images to a registry.

docker compose push

Configuration & Debugging

docker compose config — Validate and display the resolved compose file.

docker compose config

docker compose config --services — List all service names defined in the compose file.

docker compose config --services

docker compose config --volumes — List all volume names defined in the compose file.

docker compose config --volumes

docker compose -f <file> up -d — Use a specific compose file instead of the default.

docker compose -f docker-compose.prod.yml up -d

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d — Merge multiple compose files (later files override earlier ones).

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

docker compose --env-file <file> up -d — Specify an environment file for variable substitution.

docker compose --env-file .env.production up -d

docker compose --profile <name> up -d — Start services tagged with a specific profile.

docker compose --profile debug up -d

Volumes & Networks

docker compose cp <service>:<src> <dest> — Copy files from a service container to the local filesystem.

docker compose cp web:/var/log/app.log ./logs/

docker compose cp <src> <service>:<dest> — Copy files from the local filesystem into a service container.

docker compose cp ./config.json web:/app/config.json

docker volume ls — List all Docker volumes (including those created by compose).

docker volume ls

docker volume inspect <project>_<volume> — Inspect a specific compose volume (prefixed with project name).

docker volume inspect myapp_db-data

docker network ls — List all Docker networks (including those created by compose).

docker network ls

docker network inspect <project>_<network> — Inspect a compose network and see connected containers.

docker network inspect myapp_default

Common Compose File Snippets

ports: — Basic service with port mapping.

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

build: — Service built from local Dockerfile with bind mount.

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/app

depends_on: — Wait for a dependency's health check to pass before starting.

services:
  web:
    depends_on:
      db:
        condition: service_healthy

healthcheck: — Define a health check for a service.

services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes: — Define a named volume for persistent data storage.

services:
  db:
    volumes:
      - db-data:/var/lib/mysql
volumes:
  db-data:
    driver: local

env_file: — Load environment variables from a file into the service.

services:
  web:
    env_file:
      - .env
      - .env.local

Conclusion

Docker Compose is the link between a single container and full-blown orchestration: for development, testing and smaller deployments it covers nearly every need. As your stack grows, it pays to explore profiles, layered compose files and health checks – keeping a single YAML file as a reproducible, version-controlled image of your entire application.