Skip Navigation

Jupyter Tunneling

Skip Side Navigation

!!! CAUTION !!! Please do NOT run python command directly in the SSH terminal!

By doing so, you are running a potentionally intensive computing task on OSCER login machines. Intensive computing tasks had a tendency to crash the login machines, thus preventing all other 1000+ OSCER users from logging in! Please make sure to read the Python Basic Setup instruction to understand how to properly set up a Python environment and submit a Python batch job on the supercomputer.

If you have trouble following the instruction below, feel free to join OSCER weekly zoom help sessions.

Jupyter Tunneling Setup

OSCER has a dedicated OnDemand server to help researchers run python code on Jupyter Lab or Jupyter Notebook. If you need to run Jupyter Lab/Notebook with your own customized python environment, we highly recommend running your python code on a VS Code Jupyter notebook. VS Code has become increasingly user-friendly and feature-rich when it comes to Python code development, with plenty of community support and online examples you can follow.

However, if you still prefer the traditional Jupyter Lab / Notebook, you will need to submit a Jupyter server batch job and connect to your Jupyter session via SSH tunneling. The steps are as below:

  1. Setting up a python environment for Jupyter.
  2. Creating a Jupyter batch script and submitting it.
  3. Identifying the port and host address of the jupyter session.
  4. Connecting to the jupyter session via SSH tunneling.
  5. Improving Jupyter coding experience.
  6. Closing a Jupyter tunnel.

1. Setting Up a Python Environment for Jupyter

To set up an environment for a Jupyter batch job submission, we need to load your python environment and install jupyter and notebook packages if you have not done already.

  • If you use conda/miniconda/mamba base environment, you're all set after logging in to OSCER.

    If you set up a different conda environment, such as picrust2, as mentioned in our Mamba (Conda) instruction, the safest way that guarantees your job would run without any error related to the conda environment setup is to activate your conda environment AT THE END of your terminal configuration file (~/.bashrc for bash shell, or ~/.zshrc for zsh shell, or ~/.cshrc for csh shell, or ~/.tcshrc for tcsh shell - you get the idea).
    That is, use a text editing program like vi or nano to edit your terminal configuration file:
    nano ~/.bashrc

    Then add this line to the END of it:
    mamba activate your_conda_environment

    For example, to load picrust2 conda environment, type this line at the end of your terminal configuration file:
    mamba activate picrust2

    Your terminal should now started with (picrust2) whenever you log in. Please log out and log back in for it to take effect.

    If you set up a "vanilla" python virtual environment WITHOUT conda/miniconda/mamba, as in our Python Basic Setup instruction, please load the corresponding Python module and activate your python virtual environment. For example, to load Python/3.10.8-GCCcore-12.2.0 and activate test_env environment, type:
    module load Python/3.10.8-GCCcore-12.2.0
    source ~/test/test_env/bin/activate


  • Next, if you have not installed jupyter and notebook packages, type:
    pip install jupyter notebook

    You only need to install jupyter and notebook packages ONCE.

2. Creating a Jupyter Batch Script and Submitting It

Depending on the python environment you use with Jupyter:

  • If you use conda/miniconda/mamba, please make sure to modify your terminal configuration file as mentioned in step 1 above. Then, follow the example batch script below. This script will execute a Jupyter NOTEBOOK server job on partition debug, requesting 1 CPU, 1GB memory, and 30 minutes of run time: #!/bin/bash
    #
    #SBATCH --partition=debug
    #SBATCH --output=jupyter_%J_stdout.txt
    #SBATCH --error=jupyter_%J_stderr.txt
    #SBATCH --ntasks=1
    #SBATCH --mem=1G
    #SBATCH --time=00:30:00

    echo Hostname short: $(hostname -s)

    export RANDOM_PORT=$(shuf -i 8900-9900 -n 1)
    echo Random port:
    echo $RANDOM_PORT

    echo Host IP Address:
    export HOST_IP_ADDRESS=$(getent ahosts $(hostname -s)|egrep -v ::|grep RAW|cut -d " " -f 1)
    echo $HOST_IP_ADDRESS
    jupyter-notebook --no-browser --port=$RANDOM_PORT --ip $HOST_IP_ADDRESS


    If you use a python virtual environment WITHOUT conda/miniconda/mamba, follow the example batch script below. This script will load Python/3.10.8-GCCcore-12.2.0 and activate test_env environment, then execute a Jupyter NOTEBOOK server job on partition debug, requesting 1 CPU, 1GB memory, and 30 minutes of run time:
    #!/bin/bash
    #
    #SBATCH --partition=debug
    #SBATCH --output=jupyter_%J_stdout.txt
    #SBATCH --error=jupyter_%J_stderr.txt
    #SBATCH --ntasks=1
    #SBATCH --mem=1G
    #SBATCH --time=00:30:00

    module load Python/3.10.8-GCCcore-12.2.0
    source ~/test/test_env/bin/activate

    echo Hostname short: $(hostname -s)

    export RANDOM_PORT=$(shuf -i 8900-9900 -n 1)
    echo Random port:
    echo $RANDOM_PORT

    echo Host IP Address:
    export HOST_IP_ADDRESS=$(getent ahosts $(hostname -s)|egrep -v ::|grep RAW|cut -d " " -f 1)
    echo $HOST_IP_ADDRESS
    jupyter-notebook --no-browser --port=$RANDOM_PORT --ip $HOST_IP_ADDRESS


    You can replace jupyter-notebook command with jupyter-lab to start a Jupyter LAB session instead of a Jupyter NOTEBOOK session.

    Then save the batch script to a file, e.g. jupyter.sbatch.

  • To submit a Jupyter server batch job, type:
    sbatch your_jupyter_batch_script_name

    Such as:
    sbatch jupyter.sbatch

    You should see a terminal output like:
    Submitted batch job 16110538

    That 16110538 is your Jupyter server job_ID. You will need this number to identify the port and address for your Jupyter session in the next step.

3. Identifying The Port and Host Address of The Jupyter Session

After submitting a Jupyter server job on the supercomputer, you can monitor its status by typing:
watch squeue -j job_ID

such as:
watch squeue -j 16110538

When the job's status ST turn to R, it means it's running.

If you follow the example batch scripts in the above step 2, there should be two text files generated after your Jupyter job is running:
jupyter_job_ID_stdout.txt (such as jupyter_16110538_stdout.txt), which stores the screen output of your job, and
jupyter_job_ID_stderr.txt (such as jupyter_16110538_stderr.txt), which stores the error messages of your job.
Strangely enough, Jupyter server's port number and host address is actually written out in the error messages of your Jupyter job. Therefore, you will need to follow the error message text file to identify the port and host address of your Jupyter session, by typing:
tail -f jupyter_job_ID_stderr.txt

Such as:
tail -f jupyter_16110538_stderr.txt


You should get a message like this:
Or copy and paste one of these URLs:
http://10.251.86.43:9830/lab?token=684a13d8516689549560402c8c3eb9e8cc81a6d6caa09e64
http://127.0.0.1:9830/lab?token=684a13d8516689549560402c8c3eb9e8cc81a6d6caa09e64

This means your Jupyter session's port number is 9830 and host ip address is 10.251.86.43.

4. Connecting to The Jupyter Session via SSH Tunneling

On your local PC/laptop, if you are using Linux or MacOS, open a terminal and type:
ssh -f -N -L port:host_ip_address:port your_oscer_username@schooner.oscer.ou.edu

For example, using my username and my Jupyter session's information, I need to type:
ssh -f -N -L 9830:10.251.86.43:9830 thanghn90@schooner.oscer.ou.edu

Enter your OSCER password if prompted.
This command opens a "tunnel" from port 9830 of my local PC/laptop, through SSH port (22) of OSCER login node (schooner.oscer.ou.edu), authenticated with my OSCER account, into port 9830 of compute node 10.251.86.43 on partition debug.

On Windows, we recommend using MobaXterm for SSH tunneling purpose. If you haven't installed MobaXterm, please see the MobaXterm section of our Access OSCER Systems instruction. Open MobaXterm and click on the Tunneling button:

mo ba x term tunneling button

Click on the New SSH Tunnel butotn at the bottom left corner of the MobaSSHTunnel dialog.

mo ba x term tunneling new tunnel

Under the Local Clients section (left), type:

  • The port number of your Jupyter session (e.g. 9830) into the Forwarded Port.
     

Under the SSH Server section (bottom right), type:

  • schooner.oscer.ou.edu into the SSH Server,
  • Your OSCER user name into the SSH Login, and
  • 22 into the SSH Port.
     

Under the Remote Server section(top right), type:

  • The host ip address of your Jupyter session (e.g. 10.251.86.43) into the Remote Server, and
  • The port number of your Jupyter session (e.g. 9830) into the Remote Port.
     

Then click the Save button.

mo ba x term tunneling set up

Then, click the Play (▶) button to start the tunneling. Enter your OSCER password if prompted.  

mo ba x term tunneling start

It may take a minute for the tunneling to be started. Once the tunneling is started, you should see the Play (▶) button greyed out, and the Stop (■) button brighten up.

mo ba x term tunneling running

After the Jupyter tunnel is created, for both Windows, Linux, and MacOS, you can now open an internet browser in your local PC/laptop and enter the last http address you got in step 3 when following the error messages of your Jupyter server job. For example:
http://127.0.0.1:9830/lab?token=684a13d8516689549560402c8c3eb9e8cc81a6d6caa09e64

mo ba x term tunneling successful

5. Improving Jupyter Coding Experience

Some tips when running Jupyter Lab / Notebook:

jupiter code auto completion
jupiter doc string
jupiter lab dark theme

6. Closing a Jupyter Tunnel

To close a Jupyter tunnel in Linux or MacOS, type in a terminal on your local PC/laptop:
ps aux |grep port:host_ip_address

with port as the port number of your Jupyter session and hostname as the host name of your Jupyter session. For example:
ps aux |grep 9830:10.251.86.43

Then find the process ID associated with the "ssh -f -N -L" command, and kill that process ID by typing:
kill -9 process_ID

For example, my ssh -f -N -L command is associated with process ID 18418:
thang 18418 0.0 0.0 41488 684 ? Ss 17:27 0:00
ssh -f -N -L 9830:10.251.86.43:9830 thanghn90@schooner.oscer.ou.edu

I will need to type:
kill -9 18418

to close my Jupyter tunnel.

To close a Jupyter tunnel in Windows, click the Stop (■) button in the MobaSSHTunnel dialog. You can also close MobaXterm and all SSH tunnels will be automatically closed.

If your Jupyter server job is still running, you MUST cancel it by typing in OSCER terminal:
scancel job_ID

where job_ID is your Jupyter server job ID, such as:
scancel 16110538