Docker Compose Profiles: Activate Service Groups

WHY IT EXISTS: To avoid managing multiple, slightly different compose.yaml files for various scenarios like local development, debugging, and CI. Profiles allow you to define all these variations within a single, authoritative file, reducing duplication and complexity.

THE MENTAL MODEL: Think of profiles as tags you apply to your services. By default, Compose only starts untagged services. You can then tell Compose, "run the untagged services AND any services tagged 'debug'". This lets you selectively activate optional groups of services on top of your base configuration.

HOW IT WORKS: In your compose.yaml, add a profiles list to any service you want to make optional (e.g., profiles: ["debug"]). When you run docker compose up, only services without a profiles key will start. To activate a profile, use the flag: docker compose --profile debug up. This command starts all un-profiled services plus any services matching the debug profile. You can activate multiple profiles at once, and a service will run if any of its assigned profiles are active.

WHEN TO USE IT: Profiles are ideal for separating optional services from your core application stack. Three common use cases: first, adding debugging tools like a database GUI or a log analyzer that you only need occasionally; second, defining environment-specific setups, like a dev profile that mounts source code volumes for hot-reloading; third, running mock services for isolated testing in a CI pipeline.

WHEN NOT TO USE IT: For fundamentally different application stacks or major configuration changes that affect most services, using separate compose.yaml files (e.g., compose.ci.yaml) and merging them is often clearer. Profiles are best for enabling or disabling subsets of services within a single, coherent application, not for managing entirely separate deployments.

ONE CANONICAL EXAMPLE: A web app might have a backend and db service with no profile assigned. A phpmyadmin service for database inspection could be assigned profiles: ["debug"]. Running docker compose up starts only the backend and db. To also run the admin tool, you would execute docker compose --profile debug up, which starts backend, db, AND phpmyadmin.