Add detailed project name requirements, mechanisms

mbland · mbland · commit 9ce29a8aeca7 · 2023-03-19T17:52:12.000-04:00
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 <mbland@acm.org>
diff --git 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
@@ -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
@@ -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
 
