Computing : Environment Variables

Problem

Let's say, you want to build a container to run a Jupyter notebook, which listens on a port to point a browser to.

If you hard-code the port into your container, you can only start one instance, which will block the port and no other instance can listen there as well.

Solution

You control the port with an environment variable from outside the container.

Apptainer/Singularity will create an environment variable within the container, when you export it before on the host with a "SINGULARITYENV_" or "APPTAINERENV_" prefix (on updated systems the APPTAINERENV_ environment variables are prefered).

So, for example

host> export SINGULARITYENV_NOTEBOOK_PORT=34567

host> export APPTAINERENV_NOTEBOOK_PORT=34567

will become available in the container as

container > echo ${NOTEBOOK_PORT}
container > 34567

So, instead of hard-coding the port, you can let your Jupyter notebook check for this environment variable.

Dockerfile

If you build your container with Docker for later use with Apptainer/Singularity, the default command to start could look in the Dockerfile like

CMD ["jupyter", "notebook", "--port", "${NOTEBOOK_PORT}", "--no-browser"]

Apptainer/Singularity Recipe

If you build directly a Apptainer/Singularity image, your run or start section in the Apptainer/Singularity recipe could like

%runscript
jupyter notebook --ip=0.0.0.0 --NotebookApp.token='${NOTEBOOK_TOKEN}' --port=${NOTEBOOK_PORT}

Caveat

Your container's default program will only run properly with the env var set before and will probably fail without.

Addendum

Defining a default environment variable with a default value in the container and overwrite it later on with SINGULARITYENV_ is unfortunately not straight forward as pre-defined environment variables cannot be overwritten (which is reasonable as to secure well-defined container behaviour). However, the constraint can be circumvented with a bit of tuning.