virtual environment on Debian 12

[marcelomgarcia]

❤️ Thank you for your contribution!

Description

Please describe briefly your pull request.

When installing InvenioDRM on Debian 12, the command to install the command line tool fails because the virtual environment is missing. The error message is:

$ pip install invenio-cli
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
(...)
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

To fix this issue, manually create a virtual environment first:

$ python -m venv venv --prompt invenioDRM
$ source venv/bin/activate

After creating and activating the virtual environment, the installation completes successfully.

This PR adds a note to the documentation to help other users encountering this common issue on Debian 12 and other systems with PEP 668 enforcement.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've targeted the master branch.
• If this documentation change impacts the current release of InvenioRDM, I will backport it to the production branch following approval or indicate to a maintainer that it should be backported.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.

[fenekku]

Thanks for that! Adjust to what makes sense and I can get that in.

[fenekku]

Slight modification to emphasize PEP 668 as the root reason here.

Suggested change

	When installing on Debian 12 with Python 3.11, one has to create the virtual environment first with the `venv` module. For example: ```python -m venv venv --prompt invenioDRM.```
	When installing on an environment adhering to [PEP 668](https://peps.python.org/pep-0668/), e.g., Debian 12 with Python 3.11, one has to create the virtual environment first. For example, with the `venv` module: `python -m venv .venv --prompt invenioDRM`.

It must be said too that invenio-cli is not necessarily meant to be installed in the same virtualenv as the application. It's an independent tool that can be used to create other instances on the same machine for instance. This is why pip install -U or pipx or (probably will be the recommended default in next version of InvenioRDM like @carlinmack mentioned) uv tool install invenio-cli are good avenues. But Python environments are tricky so a generic pip install was the default recommendation.

[tmorrell]

I wonder if we want to recommend pip install invenio-cli --break-system-packages as well. We've been using this on Ubuntu and it's been fine. It's kind of annoying to force people to have to activate a virtualenvironment every time they want to do anything, and there aren't pins on invenio-cli so it's not likely to actually break system packages.

Longer term switching to uv as the recommendation probably will make the most sense.

[fenekku]

Yeah, I can see us adding a line to that note:

"or pip install invenio-cli --break-system-packages without virtual environment if comfortable with installing in your system packages."

invenio-cli is even probably installed in the containers by some folks so that's even less problematic.

[marcelomgarcia]

Hmm, maybe I created more confusion than I intended. I think that people installing InvenioRDM have a good technical level, and they will be able to figure out what to do. Considering that the future is 'uv,' then we probably should not waste time with 'pip.' If you agree I will cancel/remove this pull request. Sorry for the noise.

[fenekku]

No worries. If you've encountered it, others certainly have. I will leave this open until tomorrow, to see if anyone has a stronger desire for one avenue or the other. If not, I may apply my and Tom's comments if I have time, else I will close this.