# Docker Compose — Orchestrate Multi-Container Applications

> Practical guide to Docker Compose — start services, follow logs, scale containers and structure compose files, with examples for every command.

Source: https://www.jpkc.com/db/en/cheatsheets/containers/docker-compose/

<!-- PROSE:intro -->
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.
<!-- PROSE:intro:end -->

## Basic Commands

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

```bash
docker compose up
```

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

```bash
docker compose up -d
```

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

```bash
docker compose down
```

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

```bash
docker compose down -v
```

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

```bash
docker compose down --rmi all
```

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

```bash
docker compose start
```

`docker compose stop` — Stop running services without removing containers.

```bash
docker compose stop
```

`docker compose restart` — Restart all services.

```bash
docker compose restart
```

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

```bash
docker compose restart nginx
```

## Service Management

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

```bash
docker compose ps
```

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

```bash
docker compose ps -a
```

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

```bash
docker compose up -d web
```

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

```bash
docker compose stop worker
```

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

```bash
docker compose rm worker
```

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

```bash
docker compose up -d --scale worker=3
```

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

```bash
docker compose up -d --no-deps web
```

## Logs & Monitoring

`docker compose logs` — View logs from all services.

```bash
docker compose logs
```

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

```bash
docker compose logs -f
```

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

```bash
docker compose logs nginx
```

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

```bash
docker compose logs -f --tail 50 web
```

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

```bash
docker compose logs --since 30m
```

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

```bash
docker compose top
```

## Executing Commands

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

```bash
docker compose exec web bash
```

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

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

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

```bash
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).

```bash
docker compose run web npm install
```

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

```bash
docker compose run --rm web php artisan migrate
```

## Building & Pulling

`docker compose build` — Build or rebuild all service images.

```bash
docker compose build
```

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

```bash
docker compose build web
```

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

```bash
docker compose build --no-cache
```

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

```bash
docker compose pull
```

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

```bash
docker compose up -d --build
```

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

```bash
docker compose push
```

## Configuration & Debugging

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

```bash
docker compose config
```

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

```bash
docker compose config --services
```

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

```bash
docker compose config --volumes
```

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

```bash
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).

```bash
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.

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

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

```bash
docker compose --profile debug up -d
```

## Volumes & Networks

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

```bash
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.

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

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

```bash
docker volume ls
```

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

```bash
docker volume inspect myapp_db-data
```

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

```bash
docker network ls
```

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

```bash
docker network inspect myapp_default
```

## Common Compose File Snippets

`ports:` — Basic service with port mapping.

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

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

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

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

```yaml
services:
  web:
    depends_on:
      db:
        condition: service_healthy
```

`healthcheck:` — Define a health check for a service.

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

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

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

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

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

<!-- PROSE:outro -->
## 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.

## Further Reading

- [Docker Compose – official documentation](https://docs.docker.com/compose/) – reference and guides
- [Compose file reference](https://docs.docker.com/reference/compose-file/) – every key and option in detail
- [Docker – Wikipedia](https://en.wikipedia.org/wiki/Docker_(software)) – background and ecosystem
<!-- PROSE:outro:end -->

## Related Commands

- [ddev](https://www.jpkc.com/db/en/cheatsheets/containers/ddev/) – local PHP development environments on top of Docker
- [docker](https://www.jpkc.com/db/en/cheatsheets/containers/docker/) – manage individual containers and images directly
- [helm](https://www.jpkc.com/db/en/cheatsheets/containers/helm/) – package manager for Kubernetes deployments