Start optional tools only when needed with Compose profiles

Approach

Put optional services in a profile. They start only with --profile name (or COMPOSE_PROFILES).

Solution

services:
  api:
    build: .
  db:
    image: postgres:18-alpine
    environment: {POSTGRES_PASSWORD: dev}
  adminer:
    image: adminer:5
    ports: ["127.0.0.1:8081:8080"]
    profiles: [tools]
  mailpit:
    image: axllent/mailpit:v1.27
    ports: ["127.0.0.1:8025:8025"]
    profiles: [tools]

docker compose --profile tools up -d

Pitfalls

• A default service depending on a profiled one: Compose can't start it without the profile.
• Forgetting --profile on down, leaving profiled containers running.

Variations

• Several profiles per service (profiles: [tools, debug]).
• COMPOSE_PROFILES=tools in .env for developers who always want them.

Further reading: Compose profiles