From 62d5fcdba5f6eb94117e72dadf5c39289a7f4f70 Mon Sep 17 00:00:00 2001 From: Mike Bland Date: Fri, 3 Mar 2023 15:04:09 -0500 Subject: [PATCH] Add detailed project name requirements, mechanisms These changes reflect current `docker compose` behavior regarding acceptable project names. compose-spec/compose-go#261 changed `docker compose` behavior to require normalized project names as input, instead of normalizing project names automatically. This landed in compose-spec/compose-go v1.2.5 and docker/compose v2.5.1. compose-spec/compose-spec#314 updated the compose spec, and compose-spec/compose-go#362 added information to the error message specifying the correct project name format. 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 c3ee6f33c33f..779d514e0a3a 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 cb3655934421..77b687eeeb12 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 d08ee0281e0a..8d97b012e7a3 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