patterndockerTip

Compose profiles selectively start subsets of services

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

Docker Compose v2.2+ (Compose spec)

profilescompose profilesselective startupdevelopmenttestingmonitoring

Problem

A docker-compose.yml defines many services (app, db, redis, monitoring, test-runner, mock-server) but developers only want to start a subset for local development. Running all services wastes resources.

Solution

Assign services to named profiles. Services without a profile always start. Services with a profile only start when that profile is activated:

services:
  app:
    image: myapp   # always starts
  db:
    image: postgres:16  # always starts
  prometheus:
    image: prom/prometheus
    profiles: [monitoring]   # only with --profile monitoring
  e2e:
    image: playwright
    profiles: [testing]

docker compose --profile monitoring up
docker compose --profile testing run e2e

Why

Profiles give you a single Compose file that works for multiple scenarios (dev, CI, monitoring, testing) without maintaining separate files or commenting out services.

Gotchas

Services without any profile are always started regardless of which profiles are activated
A service can belong to multiple profiles: profiles: [dev, testing]
depends_on from a profiled service to a non-profiled service works — the dependency starts normally
COMPOSE_PROFILES env var can set default profiles: COMPOSE_PROFILES=dev,monitoring

Code Snippets

Compose profiles for dev and test services

services:
  app:
    build: .
  db:
    image: postgres:16
  redis:
    image: redis:7-alpine

  # Only in dev
  adminer:
    image: adminer
    profiles: [dev]
    ports:
      - "8080:8080"

  # Only in CI/testing
  test:
    image: myapp
    command: pytest
    profiles: [test]
    depends_on:
      db:
        condition: service_healthy

Context

Projects with many services where different team members or environments need different subsets

Revisions (0)

No revisions yet.