Jupyter

How to run Jupyter on a compute node through an SSH tunnel.

This page describes a standard pattern to run Jupyter on a compute node and reach it safely through an SSH tunnel.

Why This Requires a Compute Node

Jupyter notebooks and JupyterLab are interactive services and must not be started on the login node.

The correct workflow is:

  1. connect to the login node
  2. request a SLURM allocation on a compute node
  3. start Jupyter inside that allocation
  4. open an SSH tunnel from your local machine through the login node to the compute node
  5. connect with a browser to http://127.0.0.1:PORT

Start an Interactive Allocation

For a lightweight notebook session on the CPU partition, request one CPU:

srun --partition=cpu --ntasks=1 --cpus-per-task=1 --time=02:00:00 --mem=8G --pty bash

When the shell starts, verify that you are on a compute node:

hostname

Keep this shell open. Jupyter will run there.

Load the Required Environment

Load the Python environment you need.

Example:

module purge
module load apptainer-jupyter

Start Jupyter on the Compute Node

Choose a free port, for example 8888, and bind the service to localhost:

jupyter lab --no-browser --ip=0.0.0.0 --port=8888

If you prefer the classic notebook interface:

jupyter notebook --no-browser --ip=0.0.0.0 --port=8888

Jupyter will print a URL containing a token. Keep that token: you will need it in the browser.

Create the SSH Tunnel

Assume:

  • your username is your_username
  • the login node is nowwhat.stat.unipd.it
  • the compute node hostname returned by hostname is wn01
  • Jupyter is listening on port 8888

From your local machine, create the tunnel:

ssh -N -L 8888:wn01:8888 your_username@nowwhat.stat.unipd.it

The tunnel path is:

your laptop -> login-nowwhat -> wn01:8888

In this setup:

  • the browser connects to 127.0.0.1:8888 on your machine
  • SSH forwards that traffic through the login node
  • the final destination is port 8888 on the compute node where Jupyter is running

Leave this SSH command running while you use Jupyter.

Open Jupyter in the Browser

Open the URL printed by Jupyter, or use:

http://127.0.0.1:8888

Then authenticate with the token shown in the Jupyter output.

Important Notes

  • do not start Jupyter on the login node
  • the SSH tunnel must be opened from your local machine, not from the compute node
  • if the SLURM allocation ends, the notebook server and the tunnel become invalid
  • if port 8888 is already in use, choose another local and remote port consistently

Minimal Session Checklist

  1. ssh your_username@nowwhat.stat.unipd.it
  2. srun --partition=cpu --ntasks=1 --cpus-per-task=1 --time=02:00:00 --mem=8G --pty bash
  3. hostname
  4. module purge && module load apptainer-jupyter
  5. jupyter lab --no-browser --ip=0.0.0.0 --port=8888
  6. from your local machine, run ssh -N -L 8888:wn01:8888 your_username@nowwhat.stat.unipd.it
  7. open the local URL and use the Jupyter token