Skip to content

Open OnDemand for Teaching with JupyterLab

On this page, we want to introduce to you some useful features if you want to use Open OnDemand for teaching in combination with JupyterLab.

Note

Open OnDemand uses compute resources from ZIH systems.

Please be aware of the following notes:

  • ZIH systems operate at a lower availability level than your usual Enterprise Cloud VM. There can always be downtimes, e.g. of the filesystems or the batch system.
  • Scheduled downtimes are announced by e-mail. Please plan your courses accordingly.
  • Access to HPC resources is handled through projects. See your course as a project. Projects need to be registered beforehand (more info on the page Access).
  • Don't forget to add your users (e.g. students or tutors) to your project.
  • It might be a good idea to request a reservation of part of the compute resources for your project/course to avoid unnecessary waiting times in the batch system queue.

Saving Settings

In Open OnDemand, you can save your selections in any interactive application launcher form. To do this, fill out the form, then check the 'Save settings' box. This will open a popup that prompts you to choose a template name. Enter a name, then click 'Save'.

Sharing Saved Settings

Your saved job templates are part of the settings located in a file in your home directory at

$HOME/.config/ondemand/settings.yml

(This file also records when you have clicked to dismiss announcement banners in OOD). Here they appear as a list under 'batch_connect_templates', with sub-lists per app. To share a list of presets with other users, you can simply share this file. To install the presets, the other user simply places it in the same location relative to their $HOME. This will replace any settings they had saved previously, so they may want to back up or merge any settings.yml file already present. A tool for importing and exporting presets is available under Interactive Apps -> Settings Manager. Users may use the tool to import presets or delete them from their settings file, delete them, export backups to other locations in /home or share copies to other locations in /projects.

Useful Settings for Instructors

We have added some settings to our JupyterLab application to assist with preparing instruction materials. By configuring saved settings presets that use these features and sharing them, instructors may easily distribute notebooks to students.

Working Directory

When the working directory form field is set to a directory that does not exist, our script will try to create it. The path may be relative to the $HOME variable, so that a directory is created for each user who launches the preset. The JupyterLab process is launched in this directory, with the same directory as the notebook root.

Git repository

If a git repository is specified here (as a .git link), then Open OnDemand will attempt to clone it in the working directory if it is not already present before starting JupyterLab. If a directory with the same name already exists, nothing will be done.

Git branch

This option can be used in combination with the one above to clone a specific branch. If it is specified, and if a directory exists under the working directory with the expected name of the cloned repository, then the chosen branch will be checked out before JupyterLab launches.

Notebook

With or without a cloned repository, this setting allows users to open JupyterLab to a specific .ipynb file. The path to this file is relative to the working directory (not the root of any cloned repository).

With these options, in combination with others, a template can be configured to launch JupyterLab with any preferred settings and open a .ipynb file in any branch of a git repository.

Create a Shared Python Environment

To provide a consistent Python environment, you can allocate a shared workspace and prepare a Python virtual environment in it. Then use a custom Jupyter Kernel to use this environment in JupyterHub. Please note the following:

  • Set the correct permissions to the workspace and all relevant subdirectories and files via chmod.

  • Install all relevant Python packages in the shared Python virtual environment (either pip or conda). Note that standard environments (as production or test) are not available in that case.

Set up your shared Python virtual environment for JupyterLab.

Hint

For working with conda virtual environments, it may be necessary to configure your shell as described in Python virtual environments.

marie@compute$ module load Python #Load default Python
[...]
marie@compute$ ws_allocate -F scratch python_virtual_environment_teaching 1
Info: creating workspace.
/scratch/ws/1/python_virtual_environment_teaching
[...]
marie@compute$ virtualenv --system-site-packages /scratch/ws/1/python_virtual_environment_teaching/env #Create virtual environment
[...]
marie@compute$ source /scratch/ws/1/python_virtual_environment_teaching/env/bin/activate    #Activate virtual environment. Example output: (envtest) bash-4.2$
marie@compute$ pip install ipykernel
Collecting ipykernel
[...]
Successfully installed ... ipykernel-5.1.0 ipython-7.5.0 ...
marie@compute$ pip install --upgrade pip
marie@compute$ python -m ipykernel install --user --name my-teaching-kernel --display-name="my teaching kernel"
Installed kernelspec my-teaching-kernel in .../.local/share/jupyter/kernels/my-teaching-kernel
marie@compute$ pip install [...] #Now install additional packages for your notebooks
marie@compute$ deactivate
marie@compute$ chmod g+rx /scratch/ws/1/python_virtual_environment_teaching -R #Make the environment accesible for others

marie@compute$ module load Anaconda3 #Load Anaconda
[...]
marie@compute$ ws_allocate -F scratch conda_virtual_environment_teaching 1
Info: creating workspace.
/scratch/ws/1/conda_virtual_environment_teaching
[...]
marie@compute$ conda create --prefix /scratch/ws/1/conda_virtual_environment_teaching/conda-env python=3.8 #create virtual environment with Python version 3.8
[...]
marie@compute$ conda activate /scratch/ws/1/conda_virtual_environment_teaching/conda-env #activate conda-env virtual environment
marie@compute$ conda install ipykernel
[...]
marie@compute$ python -m ipykernel install --user --name my-teaching-kernel --display-name="my teaching kernel"
Installed kernelspec my-teaching-kernel in .../.local/share/jupyter/kernels/my-teaching-kernel
marie@compute$ conda install [...] # now install additional packages for your notebooks
marie@compute$ conda deactivate
marie@compute$ chmod g+rx /scratch/ws/1/conda_virtual_environment_teaching -R #Make the environment accesible for others

Now, users have to install the kernel in order to use the shared Python virtual environment in JupyterHub:

marie@compute$ module load Python #Load default Python
[...]
marie@compute$ source /scratch/ws/1/python_virtual_environment_teaching/env/bin/activate #Activate virtual environment. Example output: (envtest) bash-4.2$
marie@compute$ python -m ipykernel install --user --name my-teaching-kernel --display-name="my teaching kernel"
Installed kernelspec my-teaching-kernel in .../.local/share/jupyter/kernels/my-teaching-kernel
marie@compute$ deactivate

marie@compute$ module load Anaconda3 #Load Anaconda
[...]
marie@compute$ conda activate /scratch/ws/1/conda_virtual_environment_teaching
marie@compute$ python -m ipykernel install --user --name my-teaching-kernel --display-name="my teaching kernel"
Installed kernelspec my-teaching-kernel in .../.local/share/jupyter/kernels/my-teaching-kernel
marie@compute$ conda deactivate

After spawning the Notebook, you can select the kernel with the created Python virtual environment.

Hint

You can also execute the commands for installing the kernel from the Jupyter as described in Open OnDemand Teaching Example. Then users do not have to use the command line interface after the preparation.

The following pages link to this page: