mirror of https://github.com/docker/docs.git
Add documentation for Compose service profiles
Adds docs for the new service profiles feature introduced in docker/compose#7930 Co-authored-by: Chris Crone <christopher.crone@docker.com>
This commit is contained in:
Roman Anasal
parent
8971beb327
commit
ca88315234
|
|
@ -1687,6 +1687,24 @@ ports:
|
|||
>
|
||||
> The long syntax is new in the v3.2 file format.
|
||||
|
||||
### profiles
|
||||
|
||||
```yaml
|
||||
profiles: ["frontend", "debug"]
|
||||
profiles:
|
||||
- frontend
|
||||
- debug
|
||||
```
|
||||
|
||||
`profiles` defines a list of named profiles for the service to be enabled under.
|
||||
When not set, the service is _always_ enabled. For the services that make up
|
||||
your core application you should omit `profiles` so they will always be started.
|
||||
|
||||
Valid profile names follow the regex format `[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
|
||||
|
||||
See also [_Using profiles with Compose_](../profiles.md) to learn more about
|
||||
profiles.
|
||||
|
||||
### restart
|
||||
|
||||
`no` is the default [restart policy](../../config/containers/start-containers-automatically.md#use-a-restart-policy), and it does not restart a container under
|
||||
|
|
|
|||
|
|
@ -29,6 +29,7 @@ in your Compose file, and can also be used to define the following
|
|||
- `COMPOSE_CONVERT_WINDOWS_PATHS`
|
||||
- `COMPOSE_FILE`
|
||||
- `COMPOSE_HTTP_TIMEOUT`
|
||||
- `COMPOSE_PROFILES`
|
||||
- `COMPOSE_PROJECT_NAME`
|
||||
- `COMPOSE_TLS_VERSION`
|
||||
- `DOCKER_CERT_PATH`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,179 @@
|
|||
---
|
||||
title: Using profiles with Compose
|
||||
desription: Using profiles with Compose
|
||||
keywords: 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](compose-file/index.md#profiles) which takes an array of
|
||||
profile names:
|
||||
|
||||
```yaml
|
||||
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 `profiles` so
|
||||
> they will always be enabled and automatically started.
|
||||
|
||||
## Enabling profiles
|
||||
|
||||
To enable a profile supply the `--profile` [command-line option](reference/overview.md) or
|
||||
use the [`COMPOSE_PROFILES` environment variable](reference/envvars.md#compose_profiles):
|
||||
|
||||
```sh
|
||||
$ 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:
|
||||
|
||||
```sh
|
||||
$ 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:
|
||||
|
||||
```yaml
|
||||
version: "{{ site.compose_file_v3 }}"
|
||||
services:
|
||||
backend:
|
||||
image: backend
|
||||
|
||||
db:
|
||||
image: mysql
|
||||
|
||||
db-migrations:
|
||||
image: backend
|
||||
command: myapp migrate
|
||||
depends_on:
|
||||
- db
|
||||
profiles:
|
||||
- tools
|
||||
```
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
db:
|
||||
image: mysql
|
||||
profiles: ["debug", "dev"]
|
||||
```
|
||||
|
||||
or enable a profile of `db` explicitly:
|
||||
|
||||
```sh
|
||||
# profile "debug" is enabled automatically by targeting phpmyadmin
|
||||
$ docker-compose --profile dev up phpmyadmin
|
||||
$ COMPOSE_PROFILES=dev docker-compose up phpmyadmin
|
||||
```
|
||||
|
||||
|
||||
## Compose documentation
|
||||
|
||||
- [User guide](index.md)
|
||||
- [Installing Compose](install.md)
|
||||
- [Getting Started](gettingstarted.md)
|
||||
- [Command line reference](reference/index.md)
|
||||
- [Compose file reference](compose-file/index.md)
|
||||
- [Sample apps with Compose](samples-for-compose.md)
|
||||
|
|
@ -36,6 +36,19 @@ can also be customized using `COMPOSE_PATH_SEPARATOR`.
|
|||
|
||||
See also the `-f` [command-line option](overview.md).
|
||||
|
||||
## COMPOSE\_PROFILES
|
||||
|
||||
Specify one or multiple active profiles to enable. Calling `docker-compose up`
|
||||
with `COMPOSE_PROFILES=frontend` will start the services with the profile
|
||||
`frontend` and services without specified profiles.
|
||||
|
||||
You can specify a list of profiles separated with a comma:
|
||||
`COMPOSE_PROFILES=frontend,debug` will enable the profiles `frontend` and
|
||||
`debug`.
|
||||
|
||||
See also [_Using profiles with Compose_](../profiles.md) and the `--profile`
|
||||
[command-line option](overview.md).
|
||||
|
||||
## COMPOSE\_API\_VERSION
|
||||
|
||||
The Docker API only supports requests from clients which report a specific
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ command line.
|
|||
Define and run multi-container applications with Docker.
|
||||
|
||||
Usage:
|
||||
docker-compose [-f <arg>...] [options] [COMMAND] [ARGS...]
|
||||
docker-compose [-f <arg>...] [--profile <name>...] [options] [COMMAND] [ARGS...]
|
||||
docker-compose -h|--help
|
||||
|
||||
Options:
|
||||
|
|
@ -25,6 +25,7 @@ Options:
|
|||
(default: docker-compose.yml)
|
||||
-p, --project-name NAME Specify an alternate project name
|
||||
(default: directory name)
|
||||
--profile NAME Specify a profile to enable
|
||||
--verbose Show more output
|
||||
--log-level LEVEL Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
||||
--no-ansi Do not print ANSI control characters
|
||||
|
|
@ -174,6 +175,16 @@ Each configuration has a project name. If you supply a `-p` flag, you can
|
|||
specify a project name. If you don't specify the flag, Compose uses the current
|
||||
directory name. See also the [COMPOSE_PROJECT_NAME environment variable](envvars.md#compose_project_name).
|
||||
|
||||
## Use `--profile` to specify one or more active profiles
|
||||
|
||||
Calling `docker-compose --profile frontend up` will start the services with the
|
||||
profile `frontend` and services without specified profiles. You can also enable
|
||||
multiple profiles, e.g. with `docker-compose --profile frontend --profile debug up`
|
||||
the profiles `frontend` and `debug` will be enabled.
|
||||
|
||||
See also [_Using profiles with Compose_](../profiles.md) and the
|
||||
[`COMPOSE_PROFILES` environment variable](envvars.md#compose_profiles).
|
||||
|
||||
## Set up environment variables
|
||||
|
||||
You can set [environment variables](envvars.md) for various
|
||||
|
|
|
|||
Loading…
Reference in New Issue