What is the purpose of -p, --project-name option in docker-compose command

Question

What is the purpose of -p or --project-name option in docker-compose command?

What is the use case for it?

I am a newbie and havent yet started docker networking. Is --project-name used there in docker networking?

When I add docker support in Visual Studio 2019, Visual Studio runs some docker compose command which look like below. In each of them, there is a -p option. I am curious about that.

docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi config
docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi build
docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi up -d --no-build --force-recreate --remove-orphans

I have seen the docker docs here and also this, but could not get much from there.

Answer 1

If you run docker-compose multiple times, it uses the project name to keep one directory's containers, networks, and volumes separate from another's. Compose doesn't keep any filesystem state or run a background daemon, so metadata on the containers is the only way to keep track of this.

Say you have three Compose projects, and project-a/docker-compose.yml, project-b/docker-compose.yml, and project-c/docker-compose.yml all have a service named db:. Because their project names are different, Compose knows that it shouldn't reuse one db container for another project, it knows which container should be destroyed by docker-compose down, and so on.

A docker-compose -p option is required if you want to run multiple copies of the same Compose stack in the same directory. Otherwise the directory name is used as the default project name, and they'd conflict with each other. That's probably what Visual Studio is thinking about.

If you look at docker ps, docker network ls, and docker volume ls output you will see the name included in object names, project-a_db_1. If you use the detailed inspect forms of these commands you will see some Compose-related labels, and these are what Compose actually looks for.

Answer 2

By default, Compose bases the project name on basename of the directory compose commands are run from. The project name can be overridden either by passing a -p / --project-name option for each command or setting the COMPOSE_PROJECT_NAME environment variable.

Use case is basically to maintain different projects with this. For e.g.:- You can use same docker-compose.yml to have 2 different projects.

In the command which you mentioned

docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi config
docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi build
docker-compose  -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\docker-compose.override.yml" -f "D:\Trials\Docker\VsDokWeb\DokWeb3\obj\Docker\docker-compose.vs.debug.g.yml" -p dockercompose5511081461456614166 --no-ansi up -d --no-build --force-recreate --remove-orphans

If you see, it's manipulating the same project and that's why -p is given.