Change default port from 5000, as it sometimes is in use

[nhoening]

MacOs uses 5000 for the Airplay Receiver, for instance, which leads to unexpected errors.

The 5000 port is the default Flask port. It being in use on Mac is of course off-putting. Can you add a warning about that in the docker-compose part of the docs?

For a real solution, I agree we could simply make FlexMeasures use a more unique port number, but we'd have to discuss that in a new issue.

Originally posted by @nhoening in https://github.com/FlexMeasures/flexmeasures/issues/592#issuecomment-1445224503

We first need to choose a new port number. Here we can check which ones seem to be taken by popular applications/services. I suggest 6135 - made from f=6,l=13,e=5. I'm open to objections.

For the implementation, let's update the Dockerfile, docker-compose.yaml, and also check the documentation for necessary changes.

Other candidates:

• utils/tests/test_entity_address_utils.py
• data/scripts/_test_simulation.py

This issue might affect custom scripts which expect the 5000 port, so we need an upgrade warning next to the changelog entry.

[Flix6x]

Shouldn't we also discuss alternatives to changing the default port, ones that have less impact on production systems? For example, if unavailable, we could fall back to the next available one and log a warning.

[nhoening]

I find that technologically difficult. For instance, it needs to happen in Docker Compose somehow, somewhere.

And why do you want to stay with a port that is quite crowded?

[Flix6x]

Still exploring the issue before making/supporting a decision. The underlying issue is that the port used by FlexMeasures may be in use, right? Possible remedies:

1. Setting a less often used port as a new default
2. Falling back to some free port
3. Allowing developers to set their preferred port explicitly (FLASK_RUN_PORT?)
4. ...

I find that technologically difficult. For instance, it needs to happen in Docker Compose somehow, somewhere.

I read that you can use port 0 to let the kernel assign a free port. But that would solve only part of the challenge.

And why do you want to stay with a port that is quite crowded?

I'm being conservative with changes that may affect production systems, to minimize the required maintenance effort for FlexMeasures hosts. It's also the default port for Flask development, so new users may expect it to run there.

[nhoening]

I want to minimize the hurdles for new users, of which there are many more than current production systems we don't know about. This is a slightly tricky hurdle, I believe, in the sense that it's not easy to spot in our own code, to give a proper warning and helpful hint for resolution. I still opt for option 1.

[Flix6x]

What is the impact on production systems, actually? For example, do hosts actually need to change something in their configuration if we change the default port?

[nhoening]

It might be that someone runs FlexMeasures and their production setup expects it to be at port 5000. So maybe there are other systems they have which contact it at that port. So basically, if we update the default port, they have two options:

• Re-route this port to 5000 in their setup
• Update their setup to use the new port.

We would of course add a prominent warning about this in the release notes.

[Flix6x]

I tried option 3 (setting FLASK_RUN_PORT) and this seems to work well. For Docker users, we need to adapt our docker-compose.yaml as follows:

ports:
  - ${FLASK_RUN_PORT:-5000}:5000

which keeps the default to 5000 in case the environment variable is not set.

And also, in our docker-compose.yaml:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:${FLASK_RUN_PORT:-5000}/api/v3_0/health/ready"]

Users can then run FlexMeasures on any port they like, using:

FLASK_RUN_PORT=6135 docker-compose up

Or alternatively, by adding the port setting to their .env file. If their environment file is named differently (e.g. .my-env), they can reference it like this:

docker compose --env-file .my-env up

[nhoening]

The big problem is not if it can be set to some custom value, but how to ensure that people who run it for the first time on their MacBook will know that this problem can be easily overcome.

[Flix6x]

Isn't at this point all that's left to do update the warning (or the code snippet itself) here?

[nhoening]

It also can be a problem if you run FlexMeasures in any other way.

[Flix6x]

Let's make it more concrete if we can. Which cases, and where in the docs would someone get stuck?

[nhoening]

Let's make it more concrete if we can. Which cases, and where in the docs would someone get stuck?

• The from-scratch tutorial which now has a note about this for Docker users, but would still need a note for the "On your PC" part (to use FLASK_RUN_PORT)
• The docker compose tutorial (which you mentioned)
• The tutorial for hosters to run FlexMeasures on Docker. The one for deploying on a server is not mentioning ports.
• For developers who run locally. Probably FLASK_RUN_PORT works here.