JupyterHub

JupyterHub is a popular open-source platform for interactive computing that allows users to create and share documents containing live code, equations, visualizations, and narrative text. It is widely used in data science, machine learning, and scientific computing.

JupyterHub Service Status

JupyterHub is operational

JupyterHub on Euler¶

JupyterHub on Euler provides a convenient web-based interface to several interactive tools:

JupyterLab – for interactive Python, R, and Julia development
Code Server – Visual Studio Code in your browser
RStudio – for R development
Tensorboard – for monitoring machine learning experiments

These services allow you to access Euler's computational resources for interactive development, testing, and data analysis directly from your browser.

Not for long-term jobs

JupyterHub is intended for interactive development and debugging only. Please do not use it for long-running or production jobs. For such workloads, submit your jobs through the Slurm queue system.

GPU nodes

GPU nodes often experience high I/O and network load, which can cause session startup delays or failures. If you require GPU resources and cannot start a session, consider submitting your job as a batch script to the queue instead.

ETH network access

The JupyterHub service can only be accessed from within the ETH network. If you are working remotely, you will need to establish a VPN connection to the ETH network.

Registration

If you are a new user, you will need to log in to the Euler cluster at least once using SSH to verify your ETH account and accept the cluster's usage rules. This is a prerequisite for using JupyterHub.

Starting a Session¶

To begin, navigate to https://jupyter.euler.hpc.ethz.ch and log in using your ETH credentials. After signing in, you can select the amount of computational resources (such as CPU cores and memory) for your session. Only request multiple cores if your workload can benefit from parallel processing. Click Start to launch your session—this submits a batch job, so it may take a few moments before JupyterLab opens in your browser.

The JupyterHub service on Euler uses the module system, giving you access to hundreds of preinstalled packages in your Python environment.

For a detailed introduction to JupyterLab, see the official tutorial:
https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html

Stopping your session¶

Always stop your session when you are finished to free up cluster resources.

Simply closing your browser or stopping the kernel does not terminate your batch job; resources will continue to be used. To properly end your session:

In JupyterLab, open the File menu and select Hub Control Panel.
Click the Stop my server button.
You can now close your browser window.

If you do not see the Hub Control Panel menu (for example, when using Tensorboard or other services), you can manually access the control panel by editing the URL:
Replace everything after /user (including /user) with /hub/home.

How to open the hub control panel

Debugging¶

Before opening a ticket, please check the logs of your jupyterlab. They are available in the following directory $HOME/jupyterhub-logs/. If you are not able to debug it yourself, please add this file to the ticket.

Installing a Jupyterhub extension¶

It is possible to extend the basic functionality of JupyterLab with extensions. We provide some preinstalled extensions for the users, but there are probably still some useful extensions missing. You can not directly use the extension manager from JupyterLab as this would required write permission in the central installation directory of JupyterLab which users don't have. There is no easy way to configure JupyterLab to store the extensions in a user-writable directory. For some extensions it is possible to install them with pip:

For example if you wish to install jupyterlab-slurm, you will need to run the following commands:

module load REQUIRED_MODULES
pip3 install --user jupyterlab_slurm
jupyter labextension enable  jupyterlab_slurm

where REQUIRED_MODULES are the ones required by Jupyterlab. In order to have the current configuration, please look at the top of your log files ($HOME/jupyterhub-logs).

If an extension for JupyterLab is useful for many users, then you can also ask cluster-support if the extension can be installed centrally.

Disabling a Jupyterhub extension¶

If you are unhappy with an extension, you can disable it with:

jupyter labextension disable my-extension

Other services¶

By using a proxy on the server, we can provide other services within jupyterhub.

Feel free to copy the settings of Jupyter (in its logs) / tensorboard / VS Code into ~/.config/euler/jupyterhub/jupyterlabrc to create your own web services.

Tensorboard¶

Tensorboard can be selected when starting the server in the option Software. Unfortunately, Tensorboard does not provide any authentication method, therefore anyone can access your tensorboard if they know where you run it and on which port.

Code-server¶

Code-server can be selected when starting the server in the option Software. If you need to load some modules before starting VS code, you can create the file ~/.config/euler/jupyterhub/config_vs_code (bash script).

If you wish to see how we start a code-server session, the code is available in /cluster/software/others/services/jupyterhub/scripts/code-server.sh.

RStudio¶

RStudio can be selected when starting the server in the option Software. To start a RStudio session, you will need to have access to Apptainer. If you need to load some modules before starting RStudio, you can create the file ~/.config/euler/jupyterhub/config_r_studio (bash script).

Credentials¶

The credentials are provided in ~/.rstudio/.password.

Installing a package¶

You will need to setup the proxy before installing anything:

Sys.setenv(https_proxy="http://proxy.service.consul:3128")
Sys.setenv(http_proxy="http://proxy.service.consul:3128")

Using custom virtual environments¶

By default, JupyterHub loads python/3.11.6 from stack/2024-05 (and other additional modules). You can see the loaded modules by opening a terminal tab in JupyterHub and typing module list.

However, when working with Python, there is often a need to create and customize your own Python virtual environments (venv) that can include (or exclude) centrally installed packages. This section provides you with steps to use a custom virtual environment and/or a different Python version with the JupyterHub service.

Step 1: Load modules and create your virtual environment¶

Connect to the cluster via SSH, load the desired Python module, and create your custom virtual environment:

module load stack/2024-06 gcc/12.2.0 python/3.11.6
python -m venv env
source env/bin/activate
pip install <...your python packages...>

Required Packages

Make sure that the following packages are installed in your environment:

pip install jupyter ipykernel

Step 2: Create and register a Jupyter kernel¶

Register your virtual environment as a Jupyter kernel:

python -m ipykernel install --user --name env --display-name "Python (env)"

Replace the strings following --name and --display-name flags with something that makes sense in your context.

Step 3: Create the jupyterlabrc configuration file¶

Create or edit the configuration file at:

/cluster/home/<your_username>/.config/euler/jupyterhub/jupyterlabrc

File Location

Do not add any suffixes like .txt or .dat to the filename. The path must be exactly as shown above - JupyterHub will not search for any other location on the cluster.

Step 4: Add commands to the jupyterlabrc file¶

Add the commands that you would typically type in a terminal when you want to use your virtual environment. For the example above, it would look like:

module load stack/2024-06 gcc/12.2.0 python/3.11.6 eth_proxy hdf5/1.14.3
source env/bin/activate

Recommended Modules

Add the eth_proxy module to allow JupyterHub to have internet access (this is not enabled by default)
Include hdf5 as it's a commonly used library in Python and pre-loading it can avoid confusing errors

Step 5: Start JupyterHub and Select Your Kernel¶

Start JupyterHub in your browser at https://jupyter.euler.hpc.ethz.ch
When JupyterHub starts, it will source the configuration file you created/modified
When starting a new Jupyter notebook, select the kernel from the top right of the notebook tab
The kernel name should match what you created with the --display-name flag in Step 2

Troubleshooting Configuration

If there is a typo in the jupyterlabrc file or any other error, you can find the error logs in /cluster/home/<your_username>/jupyterhub-logs/ and adjust the configuration accordingly.

Step 6: Verify Your Setup¶

You can verify that everything is working correctly by:

Check loaded modules: Open a terminal tab in JupyterHub and run module list
Check installed packages: Run pip list - this should reflect exactly what you installed in your virtual environment
Test package imports: You should be able to import and use the packages you installed within your Jupyter notebook

Known issues¶

Currently, the plugins cannot be installed directly from the UI. Please use the command line to install them

FAQ¶

If it is the first time that you are using Euler, you will need to connect first with SSH. Please read this page for more information on how to do it.

My server is too slow to start¶

We rely on the Slurm batch system to provide the JupyterLab instances. So it could be either due to a low amount of available resources in Euler or that your priority is too low (already used too much resources or too many jobs running at the same time).

My server has been killed before starting¶

JupyterHub relies on a timeout system to manage the starting jobs (currently around 10 minutes). If your job takes more time than that to start, it will be automatically killed. If you are unable to get one after multiple tries, please check your queue by using ssh and running squeue on Euler.

My server has been killed even if my job had still plenty of remaining time¶

Jupyterhub regularly checks jobs for activity. If you do not use your notebook / lab for too long, jupyterhub will kill your notebook. We will not change this behavior as it improves the fair usage of the cluster for everyone.

My Jupyter kernel died and I cannot restart a new one¶

This could be due to a lack of memory. Please check your logs ($HOME/jupyterhub-logs) to see if you have a OOM message from slurm. You can also check the memory usage with myjobs -j JOB_ID. If you reach something above 90-95%, it could indicate a memory issue. To fix this, you just need to request more RAM when starting a jupyterlab.

I cannot request resources for more than 24h¶

This service aims at cluster beginners and therefore we chose to only allow short sessions up to 24 hours. For running longer jobs for more than 24h, we recommend to submit them directly to the queue and to not use JupyterLab for that.

Jupyter build recommended but fails¶

JupyterLab is trying to build all its files within the system directories which is of course not allowed. No worries about this issue, we will try to keep up to date the JupyterLab, but we will not do it with every minor releases of a plugin.

My job with N GPUs is not starting¶

GPUs are only available to shareholders that purchased GPU resources in Euler. Please ensure that you indeed have access to GPUs on Euler before submitting a ticket to cluster support.

I lost all my Jupyter settings when migrating from the script to the hub¶

With the JupyterHub, we are using the directory ~/.jupyterlab and not ~/.jupyter to store all the configurations. Replacing the content of the new directory by the old one should be sufficient.

I want to load a cluster module / I want to activate a virtualenv / Jupyterlab is missing some features¶

You can add your own instruction by writing your own bash script in ~/.config/euler/jupyterhub/jupyterlabrc. If you don't use Jupyter, some equivalent files are provided. See the other services

This script will be sourced (. ~/.config/euler/jupyterhub/jupyterlabrc) before starting any service. So you can load some modules, update some environment variables, replace jupyterlab by another service (advanced usage: see how tensorboard is done), ...

I wish to use custom arguments to jupyterhub-singleuser¶

A few environment variables can be defined in your ~/.config/euler/jupyterhub/jupyterlabrc file:

- JUPYTER_DIR: Available directory for the users
- JUPYTER_HOME: Default directory
- JUPYTER_EXTRA_ARGS: any additional argument (e.g. '--debug')

I can't install a Julia package¶

If you get a permission denied when installing a Julia package, you will need first to activate a local directory:

```julia using Pkg Pkg.activate(".") Pkg.add("PACKAGE_NAME")