From ca88315234f099e88a3055b5e8f7f5c1aedf67a7 Mon Sep 17 00:00:00 2001 From: Roman Anasal Date: Thu, 3 Dec 2020 20:39:29 +0100 Subject: [PATCH] Add documentation for Compose service profiles Adds docs for the new service profiles feature introduced in docker/compose#7930 Co-authored-by: Chris Crone --- compose/compose-file/compose-file-v3.md | 18 +++ compose/env-file.md | 1 + compose/profiles.md | 179 ++++++++++++++++++++++++ compose/reference/envvars.md | 13 ++ compose/reference/overview.md | 13 +- 5 files changed, 223 insertions(+), 1 deletion(-) create mode 100644 compose/profiles.md diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index b0f213f153..782fa9e753 100644 --- a/compose/compose-file/compose-file-v3.md +++ b/compose/compose-file/compose-file-v3.md @@ -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 diff --git a/compose/env-file.md b/compose/env-file.md index 18edd77b20..d5ee6623df 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -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` diff --git a/compose/profiles.md b/compose/profiles.md new file mode 100644 index 0000000000..aef2e07f15 --- /dev/null +++ b/compose/profiles.md @@ -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) diff --git a/compose/reference/envvars.md b/compose/reference/envvars.md index 800ad326d1..ae318f5baa 100644 --- a/compose/reference/envvars.md +++ b/compose/reference/envvars.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 diff --git a/compose/reference/overview.md b/compose/reference/overview.md index 80d67c172a..25e8306ed8 100644 --- a/compose/reference/overview.md +++ b/compose/reference/overview.md @@ -17,7 +17,7 @@ command line. Define and run multi-container applications with Docker. Usage: - docker-compose [-f ...] [options] [COMMAND] [ARGS...] + docker-compose [-f ...] [--profile ...] [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