How to Use Docker Compose Profiles for Multiple Environments

How to Use Docker Compose Profiles for Multiple Environments

Docker Compose profiles let you define groups of services that can be selectively started. This is ideal for managing development, staging, and production configurations on your Breeze server from a single compose file.

Defining Profiles in docker-compose.yml

services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASS}

  redis:
    image: redis:7-alpine
    profiles: ["production", "staging"]

  debug:
    image: myapp:latest
    command: ["node", "--inspect=0.0.0.0:9229", "server.js"]
    ports:
      - "9229:9229"
    profiles: ["dev"]

  monitoring:
    image: prom/prometheus:latest
    profiles: ["production"]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

volumes:
  pgdata:

Running Specific Profiles

# Start only default services (app + db)
docker compose up -d

# Start with dev tools
docker compose --profile dev up -d

# Start production services including monitoring
docker compose --profile production up -d

# Combine multiple profiles
docker compose --profile production --profile staging up -d

Using Environment-Specific Overrides

Combine profiles with environment files:

# .env.production
DB_PASS=ProductionSecurePass
COMPOSE_PROFILES=production

# Start with env file
docker compose --env-file .env.production up -d

Best Practices

• Keep core services profile-free so they always start
• Use profiles for environment-specific tooling only
• Set COMPOSE_PROFILES in your environment file for convenience
• Document which profiles exist in your project README