Using profiles with Compose
Important
From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
Compose V2 is included with all currently supported versions of Docker Desktop. For more information, see Migrate to Compose V2.
Docker's documentation refers to and describes Compose V2 functionality.
Profiles help you adjust the Compose application model for various uses and environments by selectively starting services. This is achieved by assigning each service to zero or more profiles. If unassigned, the service is always started but if assigned, it is only started if the profile is activated.
This allows you to define additional services in a single compose.yml
file
that should only be started in specific scenarios, for example for debugging or
development tasks.
Assigning profiles to services
Services are associated with profiles through the
profiles
attribute which takes an
array of profile names:
services:
frontend:
image: frontend
profiles: ["frontend"]
phpmyadmin:
image: phpmyadmin
depends_on:
- db
profiles:
- debug
backend:
image: backend
db:
image: mysql
Here the services frontend
and phpmyadmin
are assigned to the profiles
frontend
and debug
respectively and as such are only started when their
respective profiles are enabled.
Services without a profiles
attribute are always enabled. In this
case running docker compose up
would only start backend
and db
.
Valid profiles names follow the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+
.
Tip
The core services of your application shouldn't be assigned
profiles
so they are always enabled and automatically started.
Start specific profiles
To start a specific profile supply the --profile
command-line option or
use the
COMPOSE_PROFILES
environment variable:
$ docker compose --profile debug up
$ COMPOSE_PROFILES=debug docker compose up
The above commands would both start your application with the debug
profile enabled.
In the example, compose.yml
file above, this starts the services backend
,
db
and phpmyadmin
.
Start multiple profiles
Multiple profiles can be specified by passing multiple --profile
flags or
a comma-separated list for the COMPOSE_PROFILES
environment variable:
$ docker compose --profile frontend --profile debug up
$ COMPOSE_PROFILES=frontend,debug docker compose up
Auto-starting profiles and dependency resolution
When a service with assigned profiles
is explicitly targeted on the command
line its profiles are started automatically so you don't need to start them
manually. This can be used for one-off services and debugging tools.
As an example consider the following configuration:
services:
backend:
image: backend
db:
image: mysql
db-migrations:
image: backend
command: myapp migrate
depends_on:
- db
profiles:
- tools
# Only start backend and db
$ docker compose up -d
# This runs db-migrations (and,if necessary, start db)
# by implicitly enabling the profiles `tools`
$ docker compose run db-migrations
But keep in mind that docker compose
only automatically starts the
profiles of the services on the command line and not of any dependencies.
This means that any other services the targeted service depends_on
should either:
- Share a common profile
- Always be started, by omitting
profiles
or having a matching profile started explicitly
services:
web:
image: web
mock-backend:
image: backend
profiles: ["dev"]
depends_on:
- db
db:
image: mysql
profiles: ["dev"]
phpmyadmin:
image: phpmyadmin
profiles: ["debug"]
depends_on:
- db
# Only start "web"
$ docker compose up -d
# Start mock-backend (and, if necessary, db)
# by implicitly enabling profiles `dev`
$ docker compose up -d mock-backend
# This fails because profiles "dev" is disabled
$ docker compose up phpmyadmin
Although targeting phpmyadmin
automatically starts the profiles debug
, it doesn't automatically start the profiles required by db
which is dev
.
To fix this you either have to add the debug
profile to the db
service:
db:
image: mysql
profiles: ["debug", "dev"]
or start a profile of db
explicitly:
# Profiles "debug" is started automatically by targeting phpmyadmin
$ docker compose --profile dev up phpmyadmin
$ COMPOSE_PROFILES=dev docker compose up phpmyadmin