General Remarks

Usage terms and conditions

User can use and work with Jupyter Notebooks or Labs on our cluster systems under the condition that all LRZ policy rules are followed (specifically that user-specific approved access permissions are not violated), and that care is taken for respect with respect to other users (e.g. on shared systems like the login nodes) and efficient usage of LRZ resources (on compute nodes). This includes that you care for closing the server again when you don't need it anymore.

Jupyter Setup Workflow

We do not provide a central Jupyter installation as users have as divergent requirements for kernels, versions, packages, etc. as is case for the conda requirements. Users can install Jupyter most conveniently using conda (either self-provided, or by usage of LRZ module provided anaconda or miniconda).

Jupyter notebook or lab servers can run on login nodes, or on compute nodes. To connect to them from a browser on the local PC or laptop, one needs to setup a SSH tunnel. (also → general introductory tutorial to SSH)

On SuperMUC-NG, where firewall settings prevent direct download from the internet, please follow the procedure described on FAQ: Python and R on SuperMUC-NG by using conda .

Installation of Jupyter Notebook or Lab via Conda (example step-by-step guide)

Login to a login node of our LRZ cluster systems, where you have access permissions.

> module load miniconda3
> conda init bash                                         # this changes your ~/.bashrc; we recommend to fill this into ~/.profile, or into a script file sourced at each usage
> source ~/.bashrc                                        # see comment above; this sets up the conda environment (needs to be done each time before activating an environment)
(base) > conda create -n my_jupyter python=3.9 jupyter    # one can install further packages later using "conda install" in that created environment
...                                                       # this step requires some time 
(base) > conda activate my_jupyter
(my_jupyter) >

The source ~/.bashrc and conda activate ... (setting up the conda environement) steps must be executed in the following each time before you want to start a Jupyter notebook server. (Please consult Google or use a Cheat Sheet for conda command reference!)

Installation of Jupyter Notebook or Lab via pip (example step-by-step guide)

Login to a login node of our LRZ cluster systems, where you have access permissions.

> module load python/3.8.8-extended                       # or any reasonable python module
> pip install jupyter --user                              # needs to be done only once

Running a Jupyter Notebook Session on a Login node (example step-by-step guide)

(my_jupyter) > jupyter-notebook --no-browser --port=12345                                                 # with pip installed does not require a conda environment
[I 11:39:25.472 NotebookApp] Serving notebooks from local directory: /dss/dsshome1/00/XXXXXX
[I 11:39:25.472 NotebookApp] Jupyter Notebook 6.4.3 is running at:
[I 11:39:25.472 NotebookApp] http://localhost:12345/?token=02b190304b708d277f16450179d660e56983f2c86344cc9e
[I 11:39:25.472 NotebookApp]  or http://127.0.0.1:12345/?token=02b190304b708d277f16450179d660e56983f2c86344cc9e
[I 11:39:25.472 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 11:39:25.717 NotebookApp] 
    
    To access the notebook, open this file in a browser:
        file:///dss/dsshome1/00/XXXXXX/.local/share/jupyter/runtime/nbserver-45933-open.html
    Or copy and paste one of these URLs:
        http://localhost:12345/?token=02b190304b708d277f16450179d660e56983f2c86344cc9e
     or http://127.0.0.1:12345/?token=02b190304b708d277f16450179d660e56983f2c86344cc9e

After that point, you have to setup the SSH tunnel from your local PC/Laptop via -L12345:localhost:12345 (we've chosen the ports to be the same locally and remotely for convenience - we recommend you to do the same). If a port is already occupied locally or remotely, please just choose another one.

After creation of the tunnel, you should be able to open one of the last two URLs in a browser on your local (warning) PC/Laptop, and work within the Jupyter notebook.

Once you finished your work (save your work self-responsibly!!), you can close the browser tab, and stop the Jupyter server via Ctrl+C.
(The SSH tunnel is removed as soon as the SSH connection is interrupted.)

Troubleshooting and other Issues

For running a Jupyter notebook on a compute node, we recommend to first test this in the interactive queue.

(base) cm2login1:~> salloc
(base) i22r07c05s10:~> conda activate my_jupyter
ip addr ib0
Command "ib0" is unknown, try "ip address help".
(base) i22r07c05s10:~> ip addr 
[...]
4: ib0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 2044 qdisc pfifo_fast state UP group default qlen 8192       # <- infiniband NIC
    ...
    inet 10.7.3.51/17 brd 10.7.127.255 scope global ib0                                                    # <- IPv4 address
[...]
(my_jupyter) i22r07c05s10:~> jupyter-notebook --no-browser --port=12346 --ip=10.7.3.51                     # <- use same IP
[I 11:51:31.490 NotebookApp] Serving notebooks from local directory: /dss/dsshome1/00/XXXXXX
[I 11:51:31.490 NotebookApp] Jupyter Notebook 6.4.3 is running at:
[I 11:51:31.490 NotebookApp] http://localhost:12346/?token=bae8c598f843f03f3b953595148c043fa8e8bbe8576cf272
[I 11:51:31.490 NotebookApp]  or http://127.0.0.1:12346/?token=bae8c598f843f03f3b953595148c043fa8e8bbe8576cf272
[I 11:51:31.490 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 11:51:31.761 NotebookApp] 
    
    To access the notebook, open this file in a browser:
        file:///dss/dsshome1/00/XXXXXXX/.local/share/jupyter/runtime/nbserver-31929-open.html
    Or copy and paste one of these URLs:
        http://10.7.3.51:12346/?token=bae8c598f843f03f3b953595148c043fa8e8bbe8576cf272
     or http://127.0.0.1:12346/?token=bae8c598f843f03f3b953595148c043fa8e8bbe8576cf272

At this point, you need to create again the SSH tunnel via -L 12346:i22r07c05s10ib:12346 (this time to the compute node). "ib" must be added to the compute node's hostname on CoolMUC, "opa" must be added on SuperMUC-NG.

After creating the tunnel, click on the last link to locally open it in your browser. The rest is the same as above.


If you managed to run a Jupyter notebook in this way, you can also start a Jupyter notebook in a non-interactive batch job, and connect to it through a SSH tunnel. The connection info to the compute node (node name) must be extracted from the Slurm output. Some difficulty might it make to extract the correct IP address automatically. ifconfig ib0 2>/dev/null | grep inet | awk '{print $2}' might be of help.
Please go sure to not just block the compute node with idling in a non-intensive interactive session! Most probably, in such a case, you don't need a compute node or a Jupyter notebook session!


  • No labels