4.8 KiB
| title | desription | keywords |
|---|---|---|
| Using profiles with Compose | Using profiles with Compose | cli, compose, profile, profiles reference |
Profiles allow adjusting the Compose application model for various usages and environments by selectively enabling 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 one to define additional services in a single docker-compose.yml file
that should only be started in specific scenarios, e.g. 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:
version: "{{ site.compose_file_v3 }}"
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 will always be enabled, i.e. in this
case running docker compose up would only start backend and db.
Valid profile names follow the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+.
Note
The core services of your application should not be assigned
profilesso they will always be enabled and automatically started.
Enabling profiles
To enable a 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 command would both start your application with the debug profile enabled.
Using the docker-compose.yml file above, this would start the services backend,
db and phpmyadmin.
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-enabling profiles and dependency resolution
When a service with assigned profiles is explicitly targeted on the command
line its profiles will be enabled automatically so you don't need to enable them
manually. This can be used for one-off services and debugging tools.
As an example consider this configuration:
version: "{{ site.compose_file_v3 }}"
services:
backend:
image: backend
db:
image: mysql
db-migrations:
image: backend
command: myapp migrate
depends_on:
- db
profiles:
- tools
# will only start backend and db
$ docker compose up -d
# this will run db-migrations (and - if necessary - start db)
# by implicitly enabling profile `tools`
$ docker compose run db-migrations
But keep in mind that docker compose will only automatically enable the
profiles of the services on the command line and not of any dependencies. This
means that all services the targeted service depends_on must have a common
profile with it, be always enabled (by omitting profiles) or have a matching
profile enabled explicitly:
version: "{{ site.compose_file_v3 }}"
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
# will only start "web"
$ docker compose up -d
# this will start mock-backend (and - if necessary - db)
# by implicitly enabling profile `dev`
$ docker compose up -d mock-backend
# this will fail because profile "dev" is disabled
$ docker compose up phpmyadmin
Although targeting phpmyadmin will automatically enable its profiles - i.e.
debug - it will not automatically enable the profile(s) required by db -
i.e. dev. To fix this you either have to add the debug profile to the db service:
db:
image: mysql
profiles: ["debug", "dev"]
or enable a profile of db explicitly:
# profile "debug" is enabled automatically by targeting phpmyadmin
$ docker compose --profile dev up phpmyadmin
$ COMPOSE_PROFILES=dev docker compose up phpmyadmin