Lifecycle & Scaling

The core lifecycle commands

Once you have a compose.yaml, these six commands cover day-to-day operations.

docker compose up

Start all services defined in compose.yaml. Press Ctrl-C to stop.

docker compose up

Start in the background (detached mode):

docker compose up -d

Rebuild images before starting (useful after changing a Dockerfile):

docker compose up -d --build

docker compose down

Stop and remove containers and the default network. Named volumes are kept.

docker compose down

Also remove named volumes:

docker compose down -v

docker compose logs

Stream logs from all services:

docker compose logs -f

Stream logs from a specific service:

docker compose logs -f app

docker compose ps

List running containers for the current project:

docker compose ps

docker compose build

Build or rebuild images for services that use build::

docker compose build

Build a specific service:

docker compose build app

docker compose exec

Run a command inside a running service container:

docker compose exec app sh

Scaling services

Run multiple replicas of a stateless service with --scale:

docker compose up -d --scale worker=3

This starts three containers for the worker service. Each replica gets a unique name such as project-worker-1, project-worker-2, project-worker-3.

Important constraints on scaled services:

Do not use a fixed container_name: — Compose cannot give three containers the same name.
Do not use host-port mappings on a scaled service — you cannot bind the same host port to three containers.

A scalable service definition:

services:
  worker:
    image: myapp:latest
    # No container_name — Compose auto-names replicas
    # No ports — no host-port binding on scaled services
    environment:
      - QUEUE_URL=amqp://rabbit

Understanding down vs down -v

docker compose down        stops containers + removes containers + removes networks
docker compose down -v     same as above + removes named volumes

Named volumes hold your database data, uploaded files, and caches. Only pass -v when you deliberately want to wipe that data — for example, when resetting a development database to a clean state.

Full lifecycle in practice

# Build images
docker compose build

# Start everything detached
docker compose up -d

# Watch logs
docker compose logs -f

# Check status
docker compose ps

# Scale the worker up
docker compose up -d --scale worker=3

# Shut down (keep volumes)
docker compose down

# Full reset — destroy volumes too
docker compose down -v

Hands-on practice

# Create a compose.yaml with a scalable worker
cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

  worker:
    image: alpine
    command: >
      sh -c "echo Worker $$HOSTNAME started && sleep 20"
EOF

# Start in detached mode
docker compose up -d

# Show running containers
docker compose ps

# Scale workers to 3
docker compose up -d --scale worker=3

# Show all containers (1 web + 3 workers)
docker compose ps

# Stream logs from all workers
docker compose logs worker

# Tear down (containers + network, volumes kept)
docker compose down

echo "All containers removed. Named volumes (if any) are still intact."

Trade-offs

Option	Benefit	Cost
`docker compose --scale`	Scales a service horizontally fast, test load on a single dev machine right away	Limited to one host, no auto-scaling or self-healing across nodes
Kubernetes Deployment/HPA	Scales across many nodes automatically based on load, with self-healing	Requires setting up a cluster and controllers, and a much more complex operational model

Common mistakes

Using depends_on: - db and assuming Compose waits until the database is actually ready to accept connections, when it only waits for the container to start — add healthcheck and condition: service_healthy if you need real readiness.
Running docker compose up -d --scale db=3 on a stateful service like a database, when the image was never designed to run multiple instances at once (leading to data corruption or port conflicts).
Forgetting that docker compose down -v deletes named volumes with no undo, and running it without checking which environment it’s pointed at first.

💡 Real-world example

Many platform teams use docker compose up -d --scale worker=N to test how a stateless worker behaves when scaled on a dev machine first, then move the same pattern to Kubernetes replicas and a HorizontalPodAutoscaler in production, where they actually need to scale across multiple real machines.