9.3.4.4 Profile Specific Config

Profile-specific config refers to using Compose's profiles mechanism to scope certain services so they only start when their associated profile is explicitly activated, allowing a single Compose file to define optional services that aren't part of every default startup.

Assigning a Service to a Profile

A service tagged with a profile only starts when that profile is explicitly requested.

services:
  api:
    build: .
  db:
    image: postgres:16
  debug-tools:
    image: debug-toolkit:1.0
    profiles:
      - debugging

docker compose up -d

This starts api and db but not debug-tools, since that service's profile wasn't activated.

Activating a Profile to Include Its Services

Explicitly specifying the profile includes services tagged with it in the startup.

docker compose --profile debugging up -d

This now also starts debug-tools, alongside the always-included api and db.

Why Profiles Are Useful for Optional, Situational Services

A debugging tool, a one-off data seeding script, or an administrative interface might be useful in certain situations but shouldn't run as part of every ordinary startup — profiles allow these to be defined once, in the same Compose file, without affecting normal usage.

services:
  admin-ui:
    image: admin-panel:1.0
    profiles:
      - admin

Assigning a Service to Multiple Profiles

A service can belong to more than one profile, becoming active if any of its assigned profiles are activated.

services:
  monitoring:
    image: monitoring-agent:1.0
    profiles:
      - debugging
      - monitoring

Why Profile-Specific Config Matters

Profiles provide a clean way to consolidate an application's full range of services — including optional, situational ones — into a single Compose file, without forcing every optional service to run during ordinary, everyday usage.