Jupyter on Euler and Leonhard Open
- 1 Introduction
- 2 Installation
- 3 Running the script
- 4 Troubleshooting
Jupyter notebooks and Jupyter Lab are becoming more widely used among the scientific community at ETH. We therefore developed a script that you can run on your local computer to start Jupyter notebooks or Jupyter lab on Euler. The shell script starts a Jupyter in a batch job on Euler and connects your local browser with it.
The script runs on Linux, macOS and Windows (using WSL/WSL2 or git bash).
Please note, that with this script we are addressing beginners that start to use Jupyter notebooks on the cluster. It is not addressing advanced users that need a wide range of additional features going beyond simple Jupyter notebooks. Advanced users can take the script and adapt it, such that it can be used with other Python versions (centrally installed, or local installations) and add support for GPU, adding new kernels etc.
Please note, that the script uses the old software stack on Euler and can in its current state not be used with tools from the new software stack.
Download the repository with the commnad
Mac OS X:
After downloading the script from gitlab.ethz.ch, you need to change its permissions to make it executable cd Jupyter-on-Euler-or-Leonhard-Open/ chmod 755 start_jupyter_nb.sh
In order to use this script, users need to make sure, that they have set up SSH keys for passwordless access to the cluster:
Please make sure that xdg-open is installed. This package is used to automatically start your default browser. You can install it with the following command:
yum install xdg-utils
apt-get install xdg-utils
Further more, the script requires that there is a Python installation available, which is usually included in the Linux distribution or Mac OS.
Download and setup
The script is available on the Gitlab instance of ETH Zurich:
Download the repository with the command
Mac OS X:
After downloading the script from gitlab.ethz.ch, you need to change its permissions to make it executable
chmod 755 start_jupyter_nb.sh
Using SSH keys with non-default names
Since the reopening of Euler and Leonhard Open after the cyber attack in May 2020, we recommend to the cluster users to use SSH keys. We recommend to use different keys for Euler and Leonhard Open, with according names
In order to use this keys with the jupyter script, then there are two options. You can configure your ssh client to use this option automatically by adding the following lines in the $HOME/.ssh/config file on your local computer:
Host euler.ethz.ch IdentityFile ~/.ssh/id_ed25519_euler
Both options work and are equivalent.
Installing additional Python packages locally
When starting a Jupyter notebook with this script, then it will use a central Python installation:
- New software stack: module load gcc/6.3.0 python/3.8.5
- Old software stack: module load new gcc/4.8.2 python/3.6.1
Therefore you can only use packages that are centrally installed out-of-the-box. But you have the option to install additional packages locally in your home directory, which can afterwards be used.
For installing a Python package from inside a Jupyter notebook, you would need to run the following command:
!pip install --user package_name
This will install package_name into $HOME/.local, as described on our wiki page about Python:
Running the script
The start_jupyer_nb.sh script needs to be executed on your local computer. Please find below the list of options that can be used with the script:
$ ./start_jupyter_nb.sh -h ./start_jupyter_nb.sh: Script to start jupyter notebook/lab on Euler from a local computer Usage: start_jupyter_nb.sh [options] Options: -u | --username USERNAME ETH username for SSH connection to Euler -n | --numcores NUM_CPU Number of CPU cores to be used on the cluster -W | --runtime RUN_TIME Run time limit for jupyter notebook/lab in hours and minutes HH:MM -m | --memory MEM_PER_CORE Memory limit in MB per core Optional arguments: -c | --config CONFIG_FILE Configuration file for specifying options -e | --environment ENV Python virtual environment -g | --numgpu NUM_GPU Number of GPUs to be used on the cluster -h | --help Display help for this script and quit -i | --interval INTERVAL Time interval for checking if the job on the cluster already started -k | --key SSH_KEY_PATH Path to SSH key with non-standard name -l | --lab Start jupyter lab instead of a jupyter notebook -s | --softwarestack SOFTWARE_STACK Software stack to be used (old, new) -v | --version Display version of the script and exit -w | --workdir WORKING_DIR Working directory for the jupyter notebook/lab Examlples: ./start_jupyter_nb.sh -u sfux -n 4 -W 04:00 -m 2048 -w /cluster/scratch/sfux ./start_jupyter_nb.sh --username sfux --numcores 2 --runtime 01:30 --memory 2048 --softwarestack new ./start_jupyter_nb.sh -c $HOME/.jnb_config Format of configuration file: JNB_USERNAME="" # ETH username for SSH connection to Euler JNB_NUM_CPU=1 # Number of CPU cores to be used on the cluster JNB_NUM_GPU=0 # Number of GPUs to be used on the cluster JNB_RUN_TIME="01:00" # Run time limit for jupyter notebook/lab in hours and minutes HH:MM JNB_MEM_PER_CPU_CORE=1024 # Memory limit in MB per core JNB_WAITING_INTERVAL=60 # Time interval to check if the job on the cluster already started JNB_SSH_KEY_PATH="" # Path to SSH key with non-standard name JNB_SOFTWARE_STACK="new" # Software stack to be used (old, new) JNB_WORKING_DIR="" # Working directory for jupyter notebook/lab JNB_ENV="" # Path to virtual environment JNB_JLAB="" # "lab" -> start jupyter lab; "" -> start jupyter notebook
Reconnect to a Jupyter notebook
When running the script, it creates a local file called reconnect_info in the installation directory, which contains all information regarding the used ports, the remote IP address, the command for the SSH tunnel and the URL for the browser. This information should be sufficient to reconnect to a Jupyter notebook if connection was lost.
Terminate the Jupyter session
Please note that when you finish working with the jupyter notebook, you need to click on the "Quit" or "Logout" button in your Browser. "Quit" will stop the batch job running on Euler, "Logout" will just log you out from the session but not stop the batch job (in this case you need to login to the cluster, identify the job with bjobs and then kill it with the bkill command, using the jobid as parameter). Afterwards you also need to clean up the SSH tunnel that is running in the background.
samfux@bullvalene:~/Jupyter-on-Euler-or-Leonhard-Open$ ps -u | grep -m1 -- "-L" | grep -- "-N" samfux 8729 0.0 0.0 59404 6636 pts/5 S 13:46 0:00 ssh firstname.lastname@example.org -L 51339:10.205.4.122:8888 -N samfux@bullvalene:~/jupyter-on-Euler-or-Leonhard-Open$ kill 8729
If the script does not work, then we recommend to check the logs. There is on one hand the file $HOME/jnbinfo which contains logs, and on the other hand there is the lsf.o* logfile of the job that was running the jupyter notebook.
Mismatch of software stacks
In many cases it turns out that there are issues when the software stack used in the script does not match the default software stack that you have set. You can check which software stack is set as default by running the command
The script has an option (-s/--softwarestack) for which you can specify either "old" or "new". Please either adapt the software stack that you are requesting for the script or change the default setting for the software stack that you use on the cluster.
Conflict with locally installed Python packages
When the jnbinfo contains a Python error with a backtrace, then it could be that some of the Python packages that you installed locally in $HOME/.local are conflicting with the centrally provided Jupyter installation.