Scaling services and overriding Compose files for different environments

Scaling and Environment-Specific Configuration

Compose supports running multiple instances of a service and layering multiple Compose files for environment-specific config.

Scaling a Service

# Run 3 instances of the api service
docker compose up -d --scale api=3

Each instance gets a unique container name. The built-in Compose network DNS will round-robin across all instances. Note: if your service has a fixed host port mapping, scaling will fail — remove the host port or use a range.

Override Files

Compose automatically merges docker-compose.yml with docker-compose.override.yml when both exist. Use this for dev extras (volume mounts, debugger ports) without touching the base file:

# docker-compose.override.yml (dev only)
services:
  api:
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=true

Explicit Environment Selection

# Production — only base file
docker compose -f docker-compose.yml up -d

# Staging — base + staging overrides
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d

This pattern keeps secrets and dev tooling out of the production config while sharing the core service definitions.