Docker Compose Profiles & Overrides

Profiles for Selective Service Startup

Compose profiles let you group services and start only what you need:

services:
  web:
    image: nginx:alpine
    # No profile = always starts

  api:
    image: my-api:latest
    profiles: ["backend"]

  debug-tools:
    image: busybox
    profiles: ["debug"]

  monitoring:
    image: grafana/grafana
    profiles: ["monitoring", "debug"]

Activating Profiles

# Start only default services (web)
docker compose up -d

# Start default + backend services
docker compose --profile backend up -d

# Activate multiple profiles
docker compose --profile backend --profile monitoring up -d

# Or use environment variable
COMPOSE_PROFILES=backend,monitoring docker compose up -d

Override Files

Docker Compose automatically merges docker-compose.yml with docker-compose.override.yml:

docker-compose.yml (base):

services:
  api:
    image: my-api:latest
    ports:
      - "3000:3000"

docker-compose.override.yml (development):

services:
  api:
    build: .
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=true

Environment-Specific Files

# Development (uses override automatically)
docker compose up -d

# Production (explicit file, no override)
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Using .env Files

# docker-compose.yml
services:
  db:
    image: postgres:${POSTGRES_VERSION:-16}
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}

Variables are read from a .env file in the project root or can be set in the shell.