Jupyter notebook / Jupyterlab is an Open OnDemand app that launches Jupyter notebook or Jupyterlab as an interactive session on a compute node.
It is designed for researchers who need a web-based interactive development environment for notebooks, code, and data. Its flexible interface allows users to configure and arrange workflows in data science, scientific computing, computational journalism, and machine learning.
For how to create a Sandbox app, see the Developing your own app using Open OnDemand documentation.
Note
This section is intended for sys-admins, developers, and power users.
Jupyter notebook / Jupyterlab is an Open OnDemand app that launches Jupyter notebook or Jupyterlab as an interactive web server session on HPC clusters.
It is designed for researchers who need a web-based interactive development environment for notebooks, code, and data. Its flexible interface allows users to configure and arrange workflows in data science, scientific computing, computational journalism, and machine learning.
- Upstream project: Jupyter
This app uses the Batch Connect basic template with Slurm.
- Batch Connect template:
basic - Scheduler: Slurm
- Launches Jupyter via web server on compute nodes
- Supports GPU and CPU execution
- Configurable partition, memory, CPU cores, GPU cards, and wall time via the launch form
- Additional Slurm options pass-through (long format)
- Reservation support and optional Slurm account
- Email notification on job start
- Module-based
- Jupyterlab / Jupyter Notebook toggle
- Centralized, read-only virtual environment (using Python 3.12 in this repo at time of writing)
- environment has jupyterlab, notebook and nb_conda_kernels installed in it, e.g.:
# python3.12 -mvenv /n/sw/jupyterlab/jupyterlab-4.5.0
# . /n/sw/jupyterlab/jupyterlab-4.5.0
(jupyterlab-4.5.0) # pip install --no-cache-dir jupyterlab==4.5.0 notebook==7.5.0 git+https://github.com/anaconda/nb_conda_kernels@2.5.2
The CONDA_EXE environment varible must be set to the path of a conda executable in template/script.sh.erb.
nb_conda_kernels will use the conda executable directly to search for additional kernels installed in the users' conda environments, but otherwise the conda environment containing the conda executable will not be used.
- Open OnDemand v3.0+
- Slurm job scheduler
Please see the References section below for instructions on how to install the software that is launched by this app.
# Batch Connect / Passenger apps:
cd /var/www/ood/apps/sys
git clone https://github.com/fasrc/ood-jupyter.git
cd ood-jupyter
Edit form.yml.erb and update these values for your cluster (in order as they
appear at the bottom of form.yml.erb):
| Attribute | Description | FASRC settings | Change to |
|---|---|---|---|
cluster |
Target cluster ID | odyssey3 |
Your cluster name |
bc_queue |
Default scheduler partition | user-defined; default shared |
Your preferred partition |
jupyterlab_switch |
Start Jupterlab instead of Notebook | 1 |
Your preference |
custom_memory_per_node |
Memory per node (GB) | user-defined; default: 4 |
Your preferred memory allocation |
custom_num_cores |
Number of cores | user-defined; default 1 |
Your preferred default number of cores |
custom_num_gpus |
Number of GPUs | user-defined; default 0 |
Your preferred default number of GPUs |
custom_time |
Maximum wall time (HH:MM:SS) | user-defined; default 04:00:00 |
Your preferred default time |
working_folder |
Optional Override default (homedir) location to launch Jupyter Server in | user-defined | |
envscript |
Optional Script to run before starting Jupyter | user-defined | |
modules |
Optional Additional modules to load before starting Jupyter | user-defined | |
custom_reservation |
Optional Slurm reservation --reservation |
user-defined | |
extra_slurm |
Optional Extra slurm option (long-format) | user-defined | Remove if using aother scheduler |
bc_account |
Optional Alternate slurm account to charge instead of user's primary group | user-defined | Remove if using aother scheduler |
custom_email_address |
Optional email address for status notificationl used along with bc_email_on_started |
user-defined | |
bc_email_on_started |
Optional sends email to custom_email_address when job starts |
user-defined |
Edit manifest.yml and update these values for your organization:
| Attribute | Change to |
|---|---|
description |
Your cluster and your documentation |
No OOD restart is needed (Batch Connect apps are detected automatically). Visit your OOD dashboard and look for Jupyter under Interactive Apps > Web Apps.
- Check the job's
output.login~/.ondemand/data/sys/YOUR-APP/ - Verify the module loads correctly:
module load software/1.0
The module name in form.yml doesn't match your system. Run module spider software to find the correct name and update the modules attribute.
The app may need more time to start. Increase the connection timeout or check that the compute node can open the required port.
This problem is common when there is a conda initialize section in the user's .bashrc file located in their home directory. The conda initialize section was added when, at some point, the user ran the command conda init. Instead of using conda init, we recommend source activate environment_name.
To solve this problem, delete or comment out the conda initialize section of your .bashrc and create a new Jupyter notebook VDI session.
If this problem occurs, you may see an error, jupyter: command not found, in the session's output.log.
To solve this problem, delete the line auto_activate_base: false in the file ~/.condarc.
| Site | Operating System* | OOD Version | Scheduler | Status |
|---|---|---|---|---|
| FASRC | Rocky 8.10 | 3.1 | Slurm 25.11 | Tested |
| FASRC | Rocky 8.10 | 4.0 | Slurm 25.11 | Tested |
| FASRC | Rocky 8.10 | 4.1 | Slurm 25.11 | Tested |
Note
*Operating system of compute nodes
To verify your installation:
- Launch the app from the OOD dashboard with default settings
- Confirm the application loads in the browser
- Multi-node jobs are not supported
- Only tested on RHEL 8; may not work on other distributions
Contributions are welcome. To contribute:
- Fork this repository
- Create a feature branch (
git checkout -b feature/my-improvement) - Submit a pull request with a description of your changes
For bugs or feature requests, open an issue.
This app is part of the OOD Appverse. Join the Appverse Affinity Group to connect with other contributors.
- Jupyter— the application launched by this OOD app
- Open OnDemand — the HPC portal framework
This work is supported by FASRC at Harvard Univesity.