diff --git a/content/compose/compose-file/04-version-and-name.md b/content/compose/compose-file/04-version-and-name.md index 21f21161da..0151ce3035 100644 --- a/content/compose/compose-file/04-version-and-name.md +++ b/content/compose/compose-file/04-version-and-name.md @@ -4,7 +4,7 @@ description: Understand when and if to set the version and name top-level elemen keywords: compose, compose specification, services, compose file reference --- -## Version top-level element +## Version top-level element (optional) The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative. @@ -30,4 +30,6 @@ services: environment: - COMPOSE_PROJECT_NAME command: echo "I'm running ${COMPOSE_PROJECT_NAME}" -``` \ No newline at end of file +``` + +For more information on other ways to name Compose projects, see [Specify a project name](../project-name.md). \ No newline at end of file diff --git a/content/compose/compose-file/09-secrets.md b/content/compose/compose-file/09-secrets.md index 12681f3ad9..56bd3fb3dc 100644 --- a/content/compose/compose-file/09-secrets.md +++ b/content/compose/compose-file/09-secrets.md @@ -13,11 +13,6 @@ application. The source of the secret is either `file` or `environment`. - `file`: The secret is created with the contents of the file at the specified path. - `environment`: The secret is created with the value of an environment variable. -- `external`: If set to true, `external` specifies that this secret has already been created. Compose does - not attempt to create it, and if it does not exist, an error occurs. -- `name`: The name of the secret object in Docker. This field can be used to - reference secrets that contain special characters. The name is used as is - and isn't scoped with the project name. ## Example 1 @@ -41,28 +36,6 @@ secrets: environment: "OAUTH_TOKEN" ``` -Alternatively, `server-certificate` can be declared as external. Compose looks up the `server-certificate` secret to expose to relevant services. +## Additional resources -```yml -secrets: - server-certificate: - external: true -``` - -## Example 3 - -External secrets lookup can also use a distinct key by specifying a `name`. - -The following example modifies the previous example to look up a secret using the name `CERTIFICATE_KEY`. The actual lookup key is set at deployment time by the [interpolation](12-interpolation.md) of -variables, but exposed to containers as hard-coded ID `server-certificate`. - -```yml -secrets: - server-certificate: - external: true - name: "${CERTIFICATE_KEY}" -``` - -If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. - -Your Compose file needs to explicitly grant access to the secrets to relevant services in your application. \ No newline at end of file +For more information, see [How to use secrets in Compose](../use-secrets.md). \ No newline at end of file diff --git a/content/compose/compose-file/13-merge.md b/content/compose/compose-file/13-merge.md index e8b9b913a0..6b2c7dfd2e 100644 --- a/content/compose/compose-file/13-merge.md +++ b/content/compose/compose-file/13-merge.md @@ -204,4 +204,9 @@ networks: foo: !override {} ``` -Results in a Compose application model equivalent to the override YAML tree. \ No newline at end of file +Results in a Compose application model equivalent to the override YAML tree. + +## Additional resources + +For more information on how merge can be used to create a composite Compose file, see [Working with multiple Compose files](../multiple-compose-files/_index.md) + diff --git a/content/compose/compose-file/14-include.md b/content/compose/compose-file/14-include.md index e5031a3d23..aa9962fb73 100644 --- a/content/compose/compose-file/14-include.md +++ b/content/compose/compose-file/14-include.md @@ -110,4 +110,8 @@ include: ``` The local project's environment has precedence over the values set by the Compose file, so that the local project can -override values for customization. \ No newline at end of file +override values for customization. + +## Additional resources + +For more information on using `include`, see [Working with multiple Compose files](../multiple-compose-files/_index.md) \ No newline at end of file diff --git a/content/compose/compose-file/15-profiles.md b/content/compose/compose-file/15-profiles.md index a7266007ad..6ef27981f0 100644 --- a/content/compose/compose-file/15-profiles.md +++ b/content/compose/compose-file/15-profiles.md @@ -5,7 +5,6 @@ keywords: compose, compose specification, profiles, compose file reference --- With profiles you can define a set of active profiles so your Compose application model is adjusted for various usages and environments. -The exact mechanism is implementation specific and may include command line flags, environment variables, etc. The [services](05-services.md) top-level element supports a `profiles` attribute to define a list of named profiles. Services without a `profiles` attribute are always enabled. diff --git a/content/compose/environment-variables/env-file.md b/content/compose/environment-variables/env-file.md index 331de1f2df..9f152fa6d0 100644 --- a/content/compose/environment-variables/env-file.md +++ b/content/compose/environment-variables/env-file.md @@ -59,5 +59,4 @@ For braced expressions, the following formats are supported: - `${VAR:+replacement}` -> `replacement` if `VAR` is set and non-empty, otherwise empty - `${VAR+replacement}` -> `replacement` if `VAR` is set, otherwise empty - - +For more information, see [Interpolation](../compose-file/12-interpolation.md) in the Compose Specification. diff --git a/content/compose/file-watch.md b/content/compose/file-watch.md index 025ada068f..d6a393eaa9 100644 --- a/content/compose/file-watch.md +++ b/content/compose/file-watch.md @@ -59,7 +59,8 @@ by the configured user, use the `COPY --chown` flag: ```dockerfile # Run as a non-privileged user -RUN adduser -ms /bin/bash -u 1001 app +FROM node:18-alpine +RUN useradd -ms /bin/sh -u 1001 app USER app # Copy source files into application directory @@ -168,3 +169,7 @@ This pattern can be followed for many languages and frameworks, such as Python w ## Feedback We are actively looking for feedback on this feature. Give feedback or report any bugs you may find in the [Compose Specification repository](https://github.com/compose-spec/compose-spec/pull/253). + +## Reference + +- [Compose Develop Specification](compose-file/develop.md) \ No newline at end of file diff --git a/content/compose/multiple-compose-files/_index.md b/content/compose/multiple-compose-files/_index.md index 880f786c15..335d62b25b 100644 --- a/content/compose/multiple-compose-files/_index.md +++ b/content/compose/multiple-compose-files/_index.md @@ -1,20 +1,20 @@ --- description: General overview for the different ways you can work with multiple compose files in Docker Compose -keywords: compose, compose file, merge, extends, include, docker compose +keywords: compose, compose file, merge, extends, include, docker compose, -f flag title: Overview --- {{< include "compose-eol.md" >}} -This section contains information on the three key ways you can use multiple Compose files in your Compose application. +This section contains information on the ways you can work with multiple Compose files. -Using multiple Compose files lets you customize a Compose application for different environments or workflows. This is useful for large applications that may use dozens of containers, with ownership distributed across multiple teams. +Using multiple Compose files lets you customize a Compose application for different environments or workflows. This is useful for large applications that may use dozens of containers, with ownership distributed across multiple teams. For example, if your organization or team uses a monorepo, each team may have their own “local” Compose file to run a subset of the application. They then need to rely on other teams to provide a reference Compose file that defines the expected way to run their own subset. Complexity moves from the code in to the infrastructure and the configuration file. -For example, if your organization or team uses a monorepo, each team may have their own “local” Compose file to run a subset of the application. They then need to rely on other teams to provide a reference Compose file that defines the expected way to run their own subset. Complexity moves from the code in to the infrastructure and the configuration file. +The quickest way to work with multiple Compose files is to [merge](merge.md) Compose files using the `-f` flag in the command line to list out your desired Compose files. However, [merging rules](merge.md#merging-rules) means this can soon get quite complicated. -Docker Compose provides three ways to manage this complexity when working with multiple Compose files. Depending on your project's needs, you can: +Docker Compose provides two other options to manage this complexity when working with multiple Compose files. Depending on your project's needs, you can: - [Extend a Compose file](extends.md) by referring to another Compose file and selecting the bits you want to use in your own application, with the ability to override some attributes. -- [Merge a set of Compose files](merge.md) together to create a composite Compose file. -- [Include other Compose files](include.md) directly in to your Compose file. \ No newline at end of file +- [Include other Compose files](include.md) directly in your Compose file. + diff --git a/content/compose/multiple-compose-files/merge.md b/content/compose/multiple-compose-files/merge.md index cd1f7d40a6..7808055994 100644 --- a/content/compose/multiple-compose-files/merge.md +++ b/content/compose/multiple-compose-files/merge.md @@ -16,11 +16,55 @@ If a service is defined in both files, Compose merges the configurations using the rules described below and in the [Compose Specification](../compose-file/13-merge.md). +## How to merge multiple Compose files + To use multiple override files, or an override file with a different name, you -can use the `-f` option to specify the list of files. Compose merges files in -the order they're specified on the command line. See the -[`docker compose` command reference](../reference/index.md) for more information -about using `-f`. +can either use the pre-defined [COMPOSE_FILE](../environment-variables/envvars.md#compose_file) environment variable, or use the `-f` option to specify the list of files. + +Compose merges files in +the order they're specified on the command line. Subsequent files may merge, override, or +add to their predecessors. + +For example: + +```console +$ docker compose -f compose.yml -f compose.admin.yml run backup_db +``` + +The `compose.yml` file might specify a `webapp` service. + +```yaml +webapp: + image: examples/web + ports: + - "8000:8000" + volumes: + - "/data" +``` + +The `compose.admin.yml` may also specify this same service: + +```yaml +webapp: + environment: + - DEBUG=1 +``` + +Any matching +fields override the previous file. New values, add to the `webapp` service +configuration: + +```yaml +webapp: + image: examples/web + ports: + - "8000:8000" + volumes: + - "/data" + environment: + - DEBUG=1 + - ANOTHER_VARIABLE=value +``` > **Important** > @@ -33,6 +77,55 @@ confusing, so to keep paths easier to understand, all paths must be defined relative to the base file. { .important } +### Additional information + +- Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yml` and a `compose.override.yml` file. You must supply at least the `compose.yml` file. If both files exist on the same directory level, Compose combines them into a single configuration. + +- When you use multiple Compose files, all paths in the files are relative to the first configuration file specified with `-f`. You can use the `--project-directory` option to override this base path. + +- You can use a `-f` with `-` (dash) as the filename to read the configuration from `stdin`. For example: + ```console + $ docker compose -f - <}} - 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 @@ -73,6 +71,10 @@ In the example, `compose.yml` file above, this starts the services `backend`, ### Start multiple 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. + Multiple profiles can be specified by passing multiple `--profile` flags or a comma-separated list for the `COMPOSE_PROFILES` environment variable: @@ -84,6 +86,8 @@ $ docker compose --profile frontend --profile debug up $ COMPOSE_PROFILES=frontend,debug docker compose up ``` +If you want to enable all profiles at the same time, you can run `docker compose --profile "*"`. + ## Auto-starting profiles and dependency resolution When a service with assigned `profiles` is explicitly targeted on the command @@ -154,7 +158,7 @@ $ docker compose up -d # by implicitly enabling profiles `dev` $ docker compose up -d mock-backend -# This fails because profiles "dev" is disabled +# This fails because profiles "dev" is not enabled $ docker compose up phpmyadmin ``` diff --git a/content/compose/project-name.md b/content/compose/project-name.md new file mode 100644 index 0000000000..e49cd84f34 --- /dev/null +++ b/content/compose/project-name.md @@ -0,0 +1,42 @@ +--- +title: Specify a project name +description: Understand the different ways you can set a project name in Compose and what the precedence is. +keywords: name, compose, project, -p flag, name top-level element +--- + +In Compose, the default project name is derived from the base name of the project directory. However, you have the flexibility to set a custom project name. + +This page offers examples of scenarios where custom project names can be helpful, outlines the various methods to set a project name, and provides the order of precedence for each approach. + +> **Note** +> +> The default project directory is the base directory of the Compose file. A custom value can also be set +> for it using the [`--project-directory` command line option](reference/_index.md). + +## Example use cases + +Compose uses a project name to isolate environments from each other. There are multiple contexts where a project name is useful: + +- On a development host: Create multiple copies of a single environment, useful for running stable copies for each feature branch of a project. +- On a CI server: Prevent interference between builds by setting the project name to a unique build number. +- On a shared or development host: Avoid interference between different projects that might share the same service names. + +## Set a project name + +Project names must contain only lowercase letters, decimal digits, dashes, and +underscores, and must begin with a lowercase letter or decimal digit. If the +base name of the project directory or current directory violates this +constraint, alternative mechanisms are available. + +The precedence order for each method, from highest to lowest, is as follows: + +1. The `-p` command line flag. +2. The [COMPOSE_PROJECT_NAME environment variable](environment-variables/envvars.md). +3. The [top-level `name:` attribute](compose-file/04-version-and-name.md) in your Compose file. Or the last `name:` if you [specify multiple Compose files](multiple-compose-files/merge.md) in the command line with the `-f` flag. +4. The base name of the project directory containing your Compose file. Or the base name of the first Compose file if you if you [specify multiple Compose files](multiple-compose-files/merge.md) in the command line with the `-f` flag. +5. The base name of the current directory if no Compose file is specified. + +## What's next? + +- Read up on [working with multiple Compose files](multiple-compose-files/_index.md). +- Explore some [sample apps](samples-for-compose.md). \ No newline at end of file diff --git a/content/compose/reference/_index.md b/content/compose/reference/_index.md index 44a319cca4..f905e5cebe 100644 --- a/content/compose/reference/_index.md +++ b/content/compose/reference/_index.md @@ -15,7 +15,7 @@ This page provides usage information for the `docker compose` command. You can also see this information by running `docker compose --help` from the command line. -```none +```text Usage: docker compose [OPTIONS] COMMAND Define and run multi-container applications with Docker. @@ -23,15 +23,18 @@ Define and run multi-container applications with Docker. Options: --ansi string Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto") --compatibility Run compose in backward compatibility mode + --dry-run Execute command in dry run mode --env-file stringArray Specify an alternate environment file -f, --file stringArray Compose configuration files --parallel int Control max parallelism, -1 for unlimited (default -1) --profile stringArray Specify a profile to enable + --progress string Set type of progress output (auto, tty, plain, quiet) (default "auto") --project-directory string Specify an alternate working directory (default: the path of the, first specified, Compose file) -p, --project-name string Project name Commands: + attach Attach local standard input, output, and error streams to a service's running container. build Build or rebuild services config Parse, resolve and render compose file in canonical format cp Copy files/folders between a service container and the local filesystem @@ -51,12 +54,16 @@ Commands: restart Restart service containers rm Removes stopped service containers run Run a one-off command on a service. + scale Scale services start Start services + stats Display a live stream of container(s) resource usage statistics stop Stop services top Display the running processes unpause Unpause services up Create and start containers version Show the Docker Compose version information + wait Block until the first service container stops + watch Watch build context for service and rebuild/refresh containers when files are updated Run 'docker compose COMMAND --help' for more information on a command. ``` @@ -64,159 +71,11 @@ Run 'docker compose COMMAND --help' for more information on a command. You can use Docker Compose binary, `docker compose [-f ...] [options] [COMMAND] [ARGS...]`, to build and manage multiple services in Docker containers. -## Use `-f` to specify name and path of one or more Compose files +## Useful resources -Use the `-f` flag to specify the location of a Compose configuration file. - -### Specifying multiple Compose files - -You can supply multiple `-f` configuration files. When you supply multiple -files, Compose combines them into a single configuration. Compose builds the -configuration in the order you supply the files. Subsequent files override and -add to their predecessors. - -For example, consider this command line: - -```console -$ docker compose -f compose.yml -f compose.admin.yml run backup_db -``` - -The `compose.yml` file might specify a `webapp` service. - -```yaml -webapp: - image: examples/web - ports: - - "8000:8000" - volumes: - - "/data" -``` - -If the `compose.admin.yml` also specifies this same service, any matching -fields override the previous file. New values, add to the `webapp` service -configuration. - -```yaml -webapp: - build: . - environment: - - DEBUG=1 -``` - -When you use multiple Compose files, all paths in the files are relative to the -first configuration file specified with `-f`. You can use the -`--project-directory` option to override this base path. - -Use a `-f` with `-` (dash) as the filename to read the configuration from -`stdin`. When `stdin` is used all paths in the configuration are -relative to the current working directory. - -The `-f` flag is optional. If you don't provide this flag on the command line, -Compose traverses the working directory and its parent directories looking for a -`compose.yml` and a `compose.override.yml` file. You must supply -at least the `compose.yml` file. If both files are present on the same -directory level, Compose combines the two files into a single configuration. - -The configuration in the `compose.override.yml` file is applied over and -in addition to the values in the `compose.yml` file. - -### Specifying a path to a single Compose file - -You can use the `-f` flag to specify a path to a Compose file that is not -located in the current directory, either from the command line or by setting up -a [COMPOSE_FILE environment variable](../environment-variables/envvars.md#compose_file) in your shell or -in an environment file. - -For an example of using the `-f` option at the command line, suppose you are -running the [Compose Rails sample](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/README.md), and -have a `compose.yml` file in a directory called `sandbox/rails`. You can -use a command like [docker compose pull](../../engine/reference/commandline/compose_pull.md) to get the -postgres image for the `db` service from anywhere by using the `-f` flag as -follows: `docker compose -f ~/sandbox/rails/compose.yml pull db` - -Here's the full example: - -```console -$ docker compose -f ~/sandbox/rails/compose.yml pull db -Pulling db (postgres:latest)... -latest: Pulling from library/postgres -ef0380f84d05: Pull complete -50cf91dc1db8: Pull complete -d3add4cd115c: Pull complete -467830d8a616: Pull complete -089b9db7dc57: Pull complete -6fba0a36935c: Pull complete -81ef0e73c953: Pull complete -338a6c4894dc: Pull complete -15853f32f67c: Pull complete -044c83d92898: Pull complete -17301519f133: Pull complete -dcca70822752: Pull complete -cecf11b8ccf3: Pull complete -Digest: sha256:1364924c753d5ff7e2260cd34dc4ba05ebd40ee8193391220be0f9901d4e1651 -Status: Downloaded newer image for postgres:latest -``` - -## Use `-p` to specify a project name - -Each configuration has a project name which Compose can set in different ways. The level of precedence (from highest to lowest) for each method is as follows: - -1. The `-p` command line flag -2. The [COMPOSE_PROJECT_NAME environment variable][] -3. The top level `name:` variable from the config file (or the last `name:` from - a series of config files specified using `-f`) -4. The `basename` of the project directory containing the config file (or - containing the first config file specified using `-f`) -5. The `basename` of the current directory if no config file is specified - -[COMPOSE_PROJECT_NAME environment variable]: ../environment-variables/envvars.md#compose_project_name - -Project names must contain only lowercase letters, decimal digits, dashes, and -underscores, and must begin with a lowercase letter or decimal digit. If the -`basename` of the project directory or current directory violates this -constraint, you must use one of the other mechanisms. - -### Have multiple isolated environments on a single host - -Compose uses a project name to isolate environments from each other. You can make use of this project name in several different contexts: - -* On a dev host, to create multiple copies of a single environment, such as when you want to run a stable copy for each feature branch of a project -* On a CI server, to keep builds from interfering with each other, you can set - the project name to a unique build number -* On a shared host or dev host, to prevent different projects, which may use the - same service names, from interfering with each other - -The default project name is the base name of the project directory. You can set -a custom project name by using the -[`-p` command line option](reference/index.md) or the -[`COMPOSE_PROJECT_NAME` environment variable](../environment-variables/envvars.md#compose_project_name). - -The default project directory is the base directory of the Compose file. A custom value -for it can be defined with the `--project-directory` command line option. - - -## 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](../environment-variables/envvars.md#compose_profiles). - -## Set up environment variables - -You can set [environment variables](../environment-variables/envvars.md) for various -`docker compose` options, including the `-f` and `-p` flags. - -For example, the [COMPOSE_FILE environment variable](../environment-variables/envvars.md#compose_file) -relates to the `-f` flag, and `COMPOSE_PROJECT_NAME` -[environment variable](../environment-variables/envvars.md#compose_project_name) relates to the `-p` flag. - -Also, you can set some of these variables in an [environment file](../environment-variables/env-file.md). - -## Where to go next - -* [CLI environment variables](../environment-variables/envvars.md) -* [Declare default environment variables in file](../environment-variables/env-file.md) \ No newline at end of file +- [How Compose works](../compose-application-model.md) +- [Try Compose](../gettingstarted.md) +- [Specify a project name](../project-name.md) +- [Using environment variables](../environment-variables/_index.md) +- [Working with multiple Compose files](../multiple-compose-files/_index.md) +- [Compose Specification](../compose-file/_index.md) \ No newline at end of file diff --git a/data/toc.yaml b/data/toc.yaml index adc05a6721..d2a0cd22dc 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -351,8 +351,6 @@ Reference: section: - path: /compose/reference/ title: overview - - path: /compose/environment-variables/envvars/ - title: environment variables - path: /engine/reference/commandline/compose_alpha/ title: docker compose alpha - path: /engine/reference/commandline/compose_alpha_dry-run/ @@ -1921,7 +1919,7 @@ Manuals: title: Why use Compose? - path: /compose/intro/history/ title: History and development of Compose - - sectiontitle: Install Docker Compose + - sectiontitle: Install section: - path: /compose/install/ title: Overview @@ -1935,6 +1933,8 @@ Manuals: title: How Compose works - path: /compose/gettingstarted/ title: Try Compose + - path: /compose/project-name/ + title: Specify a project name - sectiontitle: Environment variables section: - path: /compose/environment-variables/ @@ -1949,32 +1949,34 @@ Manuals: title: Set or change pre-defined environment variables - path: /compose/environment-variables/best-practices/ title: Best practices - - path: /compose/profiles/ - title: Using service profiles + - sectiontitle: Use... + section: + - path: /compose/profiles/ + title: ...service profiles + - path: /compose/file-watch/ + title: ...Compose Watch + - path: /compose/production/ + title: ...Compose in production + - path: /compose/use-secrets/ + title: ...secrets in Compose - sectiontitle: Working with multiple Compose files section: - path: /compose/multiple-compose-files/ title: Overview - - path: /compose/multiple-compose-files/extends/ - title: Extend - path: /compose/multiple-compose-files/merge/ title: Merge + - path: /compose/multiple-compose-files/extends/ + title: Extend - path: /compose/multiple-compose-files/include/ title: Include - - path: /compose/gpu-support/ - title: GPU support in Compose - - path: /compose/networking/ - title: Networking in Compose - - path: /compose/file-watch/ - title: Use Compose Watch - - path: /compose/production/ - title: Using Compose in production - - path: /compose/use-secrets/ - title: Using secrets in Compose - path: /compose/startup-order/ title: Control startup order + - path: /compose/gpu-support/ + title: GPU support + - path: /compose/networking/ + title: Networking - path: /compose/samples-for-compose/ - title: Sample apps with Compose + title: Sample apps - path: /compose/feedback/ title: Give feedback - path: /compose/migrate/