9.3.5.2 Development Compose Profiles

Development Compose profiles group together services specifically useful during local development — debugging tools, development-only utilities, verbose logging sidecars — tagged with a profile so they're easily included when actively developing but excluded from other contexts like CI or production-like testing.

Tagging Development-Specific Services

A development-oriented profile groups together services relevant only to that context.

services:
  api:
    build: .
  pgadmin:
    image: dpage/pgadmin4
    profiles:
      - dev
    ports:
      - "5050:80"

pgadmin, a database administration UI useful during development, only starts when the dev profile is explicitly activated.

Activating the Development Profile

A developer working locally activates this profile to get access to these convenience tools alongside the application's core services.

docker compose --profile dev up -d

Why Keeping Development Tools Out of Other Contexts Matters

A CI pipeline running automated tests, or a staging environment intended to closely mirror production, generally shouldn't include development-only conveniences like a database admin UI — tagging these appropriately ensures they're cleanly excluded from contexts where they're unnecessary or even undesirable.

docker compose up -d

Without explicitly activating the dev profile, this command in a CI context correctly starts only the core, non-development services.

Setting the Development Profile as a Convenient Default Locally

A developer can set an environment variable in their own local shell configuration to avoid needing to specify --profile dev on every invocation.

export COMPOSE_PROFILES=dev

Why Development Compose Profiles Matter

Grouping development-specific services under a dedicated profile keeps a single Compose file practical and consistent across every context it's used in, while still providing developers convenient, easy access to the tools that make local development more productive.