Should I use docker-compose up or run?

Question

As mentioned in docker-compose run (2015)

The command passed by run overrides the command defined in the service configuration.
For example, if the web service configuration is started with bash, then docker-compose run web python app.py overrides it with python app.py.

The second difference is the docker-compose run command does not create any of the ports specified in the service configuration.
This prevents the port collisions with already open ports. If you do want the service's ports created and mapped to the host, specify the --service-ports flag:

$ docker-compose run --service-ports web python manage.py shell

So unless you have those specific needs (overriding a command or running only one container on different ports), docker-compose up (even for one container) is enough.

Can you help explain why or when you would not want the ports to be created? That is why or when they might conflict with already open ports

Simply because docker-compose run is made to run one-off commands for your services.
That means that, if you already did a docker-compose up, all your containers are already running on their specified ports from docker-compose.yml.
Doing a docker-compose run at this stage (to execute a one-off command), if it was respecting the same port, would fail immediately. Hence the default non-creation of those ports.

---

Another use case (in Compose environment variables reference):

To see what environment variables are available to a service, run docker-compose run SERVICE env.

---

Most recent (2019+) version of those commands are on docker/docker.github.io:

• docker compose run
• docker compose up

I'd like to point out that if you're using Python with the pdb debugger:

import pdb; pdb.set_trace()

It will not drop to the shell if you execute your script using:

docker-compose up

However if you use run, it will drop down to the debugger as expected:

docker-compose run

There is an answer from docker docs.

Typically, you want docker-compose up. Use up to start or restart all the services defined in a docker-compose.yml. In the default “attached” mode, you see all the logs from all the containers. In “detached” mode (-d), Compose exits after starting the containers, but the containers continue to run in the background.

The docker-compose run command is for running “one-off” or “adhoc” tasks. It requires the service name you want to run and only starts containers for services that the running service depends on. Use run to run tests or perform an administrative task such as removing or adding data to a data volume container. The run command acts like docker run -ti in that it opens an interactive terminal to the container and returns an exit status matching the exit status of the process in the container.