Unable to install sphinx with pip (sphinx-builder) / path issues (worked before)

[SchindlerTo]

Bug description

Setup:
We point to a docker file as the image in .gitpod.yml. Starting gitpod, the image is built and a startup task is done (visible in the terminal). This startup task installs some packages, most notably sphinx (https://www.sphinx-doc.org/en/master/). Sphinx documentation is built by "sphinx-builder", which is installed by pip install sphinx.

Problem:
After the startup and installation, "sphinx-builder" is not present in the gitpod container path. Everything works when starting the same container (that is pointed to in the gitpod.yml) locally. Additionally, this already worked in gitpod and we did not change our setup (Dockerfile or gitpod.yml for months).

Pip gives the following warnings:

  WARNING: The script normalizer is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script pygmentize is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script pybabel is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The scripts sphinx-apidoc, sphinx-autogen, sphinx-build and sphinx-quickstart are installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script livereload is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script sphinx-autobuild is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script breathe-apidoc is installed in '/home/gitpod/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed Jinja2-3.0.3 MarkupSafe-2.0.1 Pygments-2.10.0 alabaster-0.7.12 babel-2.9.1 breathe-4.31.0 certifi-2021.10.8 charset-normalizer-2.0.9 colorama-0.4.4 docutils-0.17.1 idna-3.3 imagesize-1.3.0 livereload-2.6.3 packaging-21.3 pyparsing-3.0.6 pytz-2021.3 requests-2.26.0 six-1.16.0 snowballstemmer-2.2.0 sphinx-4.3.1 sphinx-autobuild-2021.3.14 sphinx-copybutton-0.4.0 sphinx-issues-1.2.0 sphinx-rtd-theme-1.0.0 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-2.0.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-mermaid-0.7.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.5 sphinxcontrib-tikz-0.4.15 sphinxcontrib.yt-0.2.2 tornado-6.1 urllib3-1.26.7

The issue seems to be related to the way the startup tasks are run and it seems to have changed in the last weeks.
Any input is appreciated :)

Steps to reproduce

• https://gitpod.io/#https://bitbucket.org/ultrazohm/ultrazohm_sw
• In Terminal:

cd docs
make docs
make html

make docs fails since it does not find "sphinx-builder". Expected behavior is that make docs runs and make html runs without any warnings.

Workspace affected

No response

Expected behavior

No response

Example repository

No response

Anything else?

No response

[quental96]

Maybe linked to 7078 or 7077?

I think a solution for you may be to revert to an older docker image that used to work for you.

It seems like they have recently changed the way that workspaces are handled, especially for Python... And without even informing the users. Maybe they should think about creating a better more communicative changelog with instructions on how to prepare.

[SchindlerTo]

Seems like this is related, thanks for the hint :)

One note thought: Our gitpod.yml file does not explicitly depend on workspace-full, we use a custom docker file that is based on python 3.9.7, i.e.:

image:
  file: .devcontainer/Dockerfile

However, that's where I'm not completely sure how gitpod works. It seems like we are not following following
https://www.gitpod.io/docs/config-docker strictly, since our Dockerfile does not use the workspace-full as the base image.

[tiamot]

I have the same problem.

I had a project in gitlab that was working fine in gitpod, then I decided to try prebuilt workspaces.
Once I created a prebuild using gitpod.io/#prebuild/ I started seeing this error:
WARNING: The script flask is installed in '/home/gitpod/.local/bin' which is not on PATH.
My .gitpod.yml has the following lines:

  - init: pip3 install -r requirements.txt
    command: flask run

So when my .gitpod.yml now tries to run the command flask run, it can't find it because it's not in the PATH. It also doesn't appear to be in /home/gitpod/.local/bin either.

[tiamot]

Here is the fix (thank you @lechien73, see: #7064 (comment)):

Problem & Solution Walkthrough

• Create a new repo (e.g. test-for-prebuild) in gitlab with a readme (or github or bitbucket, etc)
• Launch gitpod
• Initialize gitpod with gp init
• Edit .gitpod.yml

tasks:
  - init: pip install pip_install_test

• Commit your changes and sync

The library is installed in new workspaces

• Manually stop the workspace and restart it
• From the terminal:

gitpod /workspace/test-for-prebuild $ pip freeze | grep pip-install-test
pip-install-test==0.5

We can see from the pip freeze, that the library pip-install-test is indeed available in this new workspace. 👍🏼

Turning on prebuild breaks something

• Manually stop the workspace
• Launch a prebuild by prefixing the repo path with gitpod.io/#prebuild/
• From the terminal:

gitpod /workspace/test-for-prebuild $ pip freeze | grep pip-install-test

We can see from the pip freeze, that the library pip-install-test is not available in this workspace. 👎🏼

Fix the problem with a custom docker image

By default gitpod uses the gitpod/workspace-full docker image, so for this example I will use that image as the base, but you can use any image you like.

• Manually stop the workspace and restart it
• Edit .gitpod.yml add these lines to the top

Image:
  file: .gitpod.Dockerfile

• Create the file .gitpod.Dockerfile

FROM gitpod/workspace-full 
ENV PYTHONUSERBASE=/workspace/.pip-modules
ENV PATH=$PYTHONUSERBASE/bin:$PATH
ENV PIP_USER=yes

• Commit your changes and sync

Final Test

• Manually stop the workspace and restart it
• From the terminal:

gitpod /workspace/test-for-prebuild $ pip freeze | grep pip-install-test
pip-install-test==0.5

We can see from the pip freeze, that the library pip-install-test is indeed available in this new workspace. 👍🏼

[SchindlerTo]

Due to couchbase-examples/python-quickstart#4 I looked into this again but I am still not able to figure it out.
Our setup uses an image that is based on python:3.9.7 and just installs a bunch of "unrelated" stuff (unrelated to gitpod).
To follow the proposed solution, we would have to change this image (that has no dependency on gitpod workspace base/full). This which may or may not break other things as the image is not only used in gitpod and just directly using this image unchanged was the killer feature for me.
At the same time, I'm not sure why adding this to our image changes anything since our image did not change. As far as I followed the related images, the breaking change was related to the workspace image (full/base) of gitpod.

Any input this appreciated. :)

[SchindlerTo]

Ok so I added the following to our Dockerfile which fixes the issue in gitpod, just as @tiamot recommended 👍 Thanks for the solution! Adidtionally, it seems like the addition of these env variables does not interfere with our other uses of the container :)

Our gitpod file:

image:
  file: .devcontainer/Dockerfile

# List the ports you want to expose and what to do when they are served. See https://www.gitpod.io/docs/config-ports/
ports:
  - port: 3000
    onOpen: open-preview

# List the start up tasks. You can start them in parallel in multiple terminals. See https://www.gitpod.io/docs/config-start-tasks/
tasks:
  - name: Docs dependencies
    init: pip install -r docs/requirements.txt
vscode:
  extensions:

.devcontainer/Dockerfile:

FROM docker.io/library/python:3.9.7

# [Optional] Uncomment this section to install additional OS packages.
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
     && apt-get -y install --no-install-recommends build-essential \
# Install unrelated packages
...
# Set env variables for gitpod
ENV PYTHONUSERBASE=/workspace/.pip-modules
ENV PATH=$PYTHONUSERBASE/bin:$PATH
ENV PIP_USER=yes