Skip to content

Add detailed project name requirements, mechanisms #16915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aevesdocker merged 2 commits into from
Mar 22, 2023
Merged

Add detailed project name requirements, mechanisms #16915

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9ce29a8
Add detailed project name requirements, mechanisms
mbland Mar 3, 2023
a5ca186
Revert _data/compose-cli/docker_compose.yaml
mbland Mar 21, 2023
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions _data/compose-cli/docker_compose.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@glours glours Mar 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is generated from the upstream docker/compose repository, I opened a PR to report those changes directly in the reference documentation
Copy link
Contributor Author

@mbland mbland Mar 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Many Compose subcommands can be run without a Compose file by passing
the project name.
Expand Down
16 changes: 15 additions & 1 deletion compose/environment-variables/envvars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
20 changes: 17 additions & 3 deletions compose/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down