Add project-name option to compose schema

[aiordache]

Many docker-compose users have asked to have the option of defining the project name via a project-name field in the compose file, linked issue: docker/compose#745
docker/compose#745 (comment)

Can we add this property to the compose schema? What is your advice on this topic?

[aiordache]

@ndeloof @chris-crone @nebuk89 @EricHripko need your advice on this issue.

[chris-crone]

I'm +1 for this

[EricHripko]

I absolutely ❤️ this idea because it's benefits both users and tooling built on top of Compose spec:

• Users get to pick meaningful non-PWD-based names for their projects
• CI systems have a file-based (plays nicely with future profiles Proposal: profiles #97 and today's overrides) way to change project name, thereby isolating a Compose setup.
• Compose integrations (e.g., VSC Remote - Containers and PyCharm Remote Interpreters come to mind) are now more powerful and configurable, as project name can be specified to isolate your local development Compose setup from your local testing Compose setup

IMO, the latter is especially useful for inexperienced users since integrations might create additional services to go into the local setup. This confuses such users when they attempt to use plain Compose tooling and get orphan warnings.

[chris-crone]

Summarizing the notes from the community meeting last week:

• General consensus was that this is not worse than what we currently have (using current working directory's name)
• Possible concerns:
  • compose up could overwrite a different stack with the same project name
  • compose down could delete an unexpected stack
  • Cannot compose up the same stack multiple times on the same machine
• Possible mitigation:
  • Use working directory label on stack objects to ensure that up/down doesn't only rely on project name
• Other possible ways forward:
  • Use a separate file for project name

[ndeloof]

Cannot compose up the same stack multiple times on the same machine

just override the name by --project-name

[ndeloof]

Use a separate file for project name

that's also a valid option. For flexibility and backward compatibility docker-compose could write such a file if it didn't existed on docker-compose up based on legacy project-naming mechanism. Doing so, subsequent commands would target the expected resources.

[minhduc9699]

+1 for this

[EricHripko]

Could you elaborate on this @chris-crone?

Use working directory label on stack objects to ensure that up/down doesn't only rely on project name

Is the suggested mitigation to generate object names with directory + project name + object name? Or is this talking about attaching some extra metadata to the object?

[chris-crone]

@EricHripko it would be extra metadata, something like what docker-compose does already with the working_dir label:

{
  "com.docker.compose.config-hash": "a375f76b8a46f1bf01defb6c99802412e441049b8263a4537e5c1087b4684bf3",
  "com.docker.compose.container-number": "1",
  "com.docker.compose.oneoff": "False",
  "com.docker.compose.project": "compose",
  "com.docker.compose.project.config_files": "docker-compose.yml",
  "com.docker.compose.project.working_dir": "/private/tmp/compose",
  "com.docker.compose.service": "one",
  "com.docker.compose.version": "1.27.4",
  "maintainer": "NGINX Docker Maintainers <docker-maint@nginx.com>"
}

[acran]

@chris-crone when adding the (absolute) project path to object identifiers what would be the expected behavior in the following case:

• user clones a project
• user compose ups the project
• user moves the project folder to another path (keeping the basename)
• user does a compose down

I would argue, the user expects the running services to be stopped by this (as it is the current behavior). Also not knowing why this doesn't work the user would have "no" clean way to stop the already running services using docker-compose. So this may be confusing for users?

But this - again - is not specific to this proposal but a problem we already have/would add by adding the current path to the object identifiers.

[rijnhard]

for these

compose up could overwrite a different stack with the same project name
compose down could delete an unexpected stack
Cannot compose up the same stack multiple times on the same machine

These are already issues if you use a standard directory structure like <project>/docker and allowing project-name to be configurable would solve those issues for those use cases.

I think this is really for local development, I really can't think of other use cases.

I really wouldn't want to mix the parent directory into that, but would be fine with that behaviour being configurable, but it feels like its getting pretty clunky pretty quickly.

Maybe either-or, or changing the parent dir to use, this is about the smoothest I can think of without introducing another configuration option.

version: "3"
project-name: "my_custom_project" | "." [default] | "../" # use parent dir

[acran]

and to add my 2¢:

regarding docker/compose#745 (comment)

• For consistency with --project-name, COMPOSE_PROJECT_NAME should definitely override project_name:.
• But: Making COMPOSE_PROJECT_NAME take precedence over project_name: makes it possible to accidentally use the wrong project name due to the environment variable being set; this can be hard to debug. Maybe a warning message can be issues in this case?

Since the error-proneness of COMPOSE_PROJECT_NAME when working with multiple projects was one of the main motivations for this / docker/compose#745 maybe it would be best to give a project_name config precedence over COMPOSE_PROJECT_NAME?

Because this would solve the issue but at the same time would allow the user to opt-in to COMPOSE_PROJECT_NAME using variable substitution:

# use $COMPOSE_PROJECT_NAME if set or fallback to static project name
project_name: ${COMPOSE_PROJECT_NAME:-my_custom_project}

[EricHripko]

@chris-crone, looks like a very reasonable approach 👍 Is the suggestion to use this label as a filter for selecting stack objects or as just a verification mechanism?

@acran, "changing project path" workflow seems like something that wouldn't happen very often and it could possibly be solved in tooling? Compose implementations could error out with "path mismatch" message, but have a flag to override this behaviour. What do you think?

@rijnhard I agree with your general sentiment that "parent directory" approach isn't ideal 🙈

[acran]

"changing project path" workflow seems like something that wouldn't happen very often
But I think it still happens often enough that we need to provide a sane UX for that case.

Compose implementations could error out with "path mismatch" message, but have a flag to override this behaviour.
So current behavior + the absolute path as an additional label; services are still matched by workdir basename/project name but if the absolute path differs the tool will exit with an error message / require a flag to ignore/override the checked path?

👍 this would make it transparent to the user what is happening, why and how to solve this

[wibed]

additionally I would propose to automatically import project_name into any containers built from given docker-compose file
so one would not need to drill args from .env (or compose if change is made) down to a dockerfile

[acran]

@wibed can you explain this with an example use case?
Up to now my understanding would be that the project name is only used by docker-compose to manage the services etc. and therefore I would strongly oppose that containers should change their behavior based on the project name. Because this would mean without an explicit project_name or COMPOSE_PROJECT_NAME simply renaming the project directory could result in different behavior which I'd find very confusing from a user perspective.

[wibed]

@acran au contraire: renaming the project should result in a new container and not reference a build with a discarded purpose

[acran]

@wibed yes, it should rename the container/allow multiple separate instances of the same project with different names.

But: I don't think these containers should have different behavior based on the project name. Rather this should be controlled by environment variables or configuration files.

[chris-crone]

@thaJeztah raised to me that he still thinks adding it to the compose.yaml isn't a good idea but needs the time to write down a better proposal. As he's the author of the original issue it'd definitely be good to wait for his input!

[wibed]

@acran could you elaborate what you meant with "different behaviour" further?

[acran]

@wibed I was referring to

additionally I would propose to automatically import project_name into any containers built from given docker-compose file

I understand "import project_name into containers" as making the current project_name available to the process within the container somehow, e.g. via an additional environment variable. However the containers then use this information it will have an impact on their behavior. Imagine for example an entrypoint script like this:

if [ "$COMPOSE_PROJECT_NAME" = myapp_prod ]; then
  ./myapp --prod
else 
  ./myapp --dev
fi

With such an application simply changing the name of the directory containing the docker-compose.yml would lead to a massively different behavior of the service - i.e. here: running in production mode vs in dev mode.
This of course first requires respective code to be put into the containers by the developers. But I would find it to be a very unexpected and non-transparent effect simply renaming the directory name would have here.

And even using the project_name only as a log prefix or something could impact the application - think: what when the project_name/log prefix is much longer than the app can handle?

So, however you want to import the project_name into the container I would consider it then to be part of the run-time environment, for that we already have an established mechanism and to avoid confusion and unexpected behavior for the users I would keep it that way.

But maybe you meant it a completely other way or see another way of implementing. That's why I asked if you can provide an example use case in case there is something I don't quite understand correctly right now^^

[abdennour]

so far, this is how i am calculating project name:

func projectName(file string) (pn string) {
	pn = os.Getenv("COMPOSE_PROJECT_NAME")
	if pn != "" {
		return pn
	}
	fileAbs, err := filepath.Abs(file)
	if err != nil {
		log.Fatal(err)
	}
	dir := filepath.Dir(fileAbs)
	return filepath.Base(dir)
}

i would prefer that this module provides it out of the box

[ndeloof]

@abdennour it does: https://github.com/compose-spec/compose-go/blob/b6c7aa633e9103114a99707c80184c5b8cbbb35f/cli/options.go#L341-L349

[abdennour]

@ndeloof but it's not exposed. Right?

[glours]

Fixed by #206