Compose Profiles and Scaling Services

Compose profiles allow services to be grouped and selectively started. Assign a profile to a service with profiles: [profile-name]. Services with no profile are always started; services with a profile only start when that profile is activated with --profile name. Common uses: a debug profile for pgAdmin and Redis Commander, a test profile for test databases and mock services. docker compose up --scale api=3 runs three instances of the api service. Compose assigns each a sequential name. Combined with a load balancer service in the Compose file, this creates a local multi-instance development environment. Port mappings with a single host port cannot be scaled (port conflict); use expose instead and let the load balancer route traffic. The depends_on directive with condition: service_healthy is the production-safe way to order startup. Without it, services start in parallel and your application may crash because the database is not yet ready. Health-condition dependencies retry until the dependency reports healthy, eliminating fragile sleep commands in entrypoint scripts.

Example

# compose.yaml with profiles and scaling
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD","pg_isready"]
      interval: 5s
      retries: 10

  api:
    build: .
    expose:
      - "3000"
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api

  pgadmin:
    image: dpage/pgadmin4
    profiles: [debug]
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.dev
      PGADMIN_DEFAULT_PASSWORD: admin

volumes:
  pgdata:

# Scale api to 3 instances
# docker compose up --scale api=3 -d
# Activate debug profile
# docker compose --profile debug up -d

HTML

Full Editor

Related Resources

Docker Reference

Complete tag & property list

Docker How-To Guides

Step-by-step practical guides

Docker Exercises

Practice what you've learned