From 9ce29a8aeca715d7f62788de83a5d1f881a4600f Mon Sep 17 00:00:00 2001 From: Mike Bland Date: Fri, 3 Mar 2023 15:04:09 -0500 Subject: [PATCH 1/2] Add detailed project name requirements, mechanisms These changes reflect updated `docker compose` behavior regarding acceptable project names. compose-spec/compose-go#261 changed `docker compose` behavior to require normalized project names as input when using `-p`. Previously `docker compose` normalized project names automatically, leading to errors for some users after the change landed in compose-spec/compose-go v1.2.5 and docker/compose v2.5.1. compose-spec/compose-spec#314 updated the compose spec, effectively enforcing the same constraint for the `name:` config file property. compose-spec/compose-go#362 added information to the error message specifying the correct project name format. compose-spec/compose-go#364 added enforcement of the new project name requirements for all project name mechanisms (`-p`, `name:`, `COMPOSE_PROJECT_NAME`, project dir, working dir). Local development URLs: - http://localhost:4000/compose/reference/#use--p-to-specify-a-project-name - http://localhost:4000/compose/environment-variables/envvars/#compose_project_name - http://localhost:4000/engine/reference/commandline/compose/#use--p-to-specify-a-project-name Production URLs: - https://docs.docker.com/compose/reference/#use--p-to-specify-a-project-name - https://docs.docker.com/compose/environment-variables/envvars/#compose_project_name - https://docs.docker.com/engine/reference/commandline/compose/#use--p-to-specify-a-project-name Signed-off-by: Mike Bland --- _data/compose-cli/docker_compose.yaml | 18 +++++++++++++++--- compose/environment-variables/envvars.md | 16 +++++++++++++++- compose/reference/index.md | 20 +++++++++++++++++--- 3 files changed, 47 insertions(+), 7 deletions(-) diff --git a/_data/compose-cli/docker_compose.yaml b/_data/compose-cli/docker_compose.yaml index c3ee6f33c33..779d514e0a3 100644 --- a/_data/compose-cli/docker_compose.yaml +++ b/_data/compose-cli/docker_compose.yaml @@ -63,9 +63,21 @@ long: |- ### Use `-p` to specify a project name - 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. - Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable. + Each configuration has a project name. Compose sets the project name using + the following mechanisms, in order of precedence: + + - The `-p` command line flag + - The `COMPOSE_PROJECT_NAME` environment variable + - The top level `name:` variable from the config file (or the last `name:` + from a series of config files specified using `-f`) + - The `basename` of the project directory containing the config file (or + containing the first config file specified using `-f`) + - The `basename` of the current directory if no config file is specified + + 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. Many Compose subcommands can be run without a Compose file by passing the project name. diff --git a/compose/environment-variables/envvars.md b/compose/environment-variables/envvars.md index cb365593442..77b687eeeb1 100644 --- a/compose/environment-variables/envvars.md +++ b/compose/environment-variables/envvars.md @@ -43,7 +43,21 @@ the container's name on startup. For example, if your project name is `myapp` and it includes two services `db` and `web`, then Compose starts containers named `myapp-db-1` and `myapp-web-1` respectively. -It defaults to the `basename` of the project directory. +Compose sets the project name using the following mechanisms, in order of +precedence: + +- The `-p` command line flag +- `COMPOSE_PROJECT_NAME` +- The top level `name:` variable from the config file (or the last `name:` from + a series of config files specified using `-f`) +- The `basename` of the project directory containing the config file (or + containing the first config file specified using `-f`) +- The `basename` of the current directory if no config file is specified + +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. See also the [command-line options overview](../reference/index.md#command-options-overview-and-help) and [using `-p` to specify a project name](../reference/index.md#use--p-to-specify-a-project-name). diff --git a/compose/reference/index.md b/compose/reference/index.md index d08ee0281e0..8d97b012e7a 100644 --- a/compose/reference/index.md +++ b/compose/reference/index.md @@ -185,9 +185,23 @@ Status: Downloaded newer image for postgres:latest ## Use `-p` to specify a project name -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](../environment-variables/envvars.md#compose_project_name). +Each configuration has a project name. Compose sets the project name using the +following mechanisms, in order of precedence: + +- The `-p` command line flag +- The [COMPOSE_PROJECT_NAME environment variable][] +- The top level `name:` variable from the config file (or the last `name:` from + a series of config files specified using `-f`) +- The `basename` of the project directory containing the config file (or + containing the first config file specified using `-f`) +- 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. ## Use `--profile` to specify one or more active profiles From a5ca1863b50df9c863703e60b434cc2a2a33a9ad Mon Sep 17 00:00:00 2001 From: Mike Bland Date: Tue, 21 Mar 2023 13:04:24 -0400 Subject: [PATCH 2/2] Revert _data/compose-cli/docker_compose.yaml This reverts part of commit 9ce29a8aeca715d7f62788de83a5d1f881a4600f. As @glours noted in the review of #16915, this content comes from the upstream docker/compose repo. He's opened docker/compose#10390 to apply the update there instead. Signed-off-by: Mike Bland --- _data/compose-cli/docker_compose.yaml | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/_data/compose-cli/docker_compose.yaml b/_data/compose-cli/docker_compose.yaml index 779d514e0a3..c3ee6f33c33 100644 --- a/_data/compose-cli/docker_compose.yaml +++ b/_data/compose-cli/docker_compose.yaml @@ -63,21 +63,9 @@ long: |- ### Use `-p` to specify a project name - Each configuration has a project name. Compose sets the project name using - the following mechanisms, in order of precedence: - - - The `-p` command line flag - - The `COMPOSE_PROJECT_NAME` environment variable - - The top level `name:` variable from the config file (or the last `name:` - from a series of config files specified using `-f`) - - The `basename` of the project directory containing the config file (or - containing the first config file specified using `-f`) - - The `basename` of the current directory if no config file is specified - - 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. + 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. + Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable. Many Compose subcommands can be run without a Compose file by passing the project name.