Jupyter Tunneling

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.

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.

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.
  
  

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

jupyter-notebook --no-browser --ip=$HOSTNAME
  
  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
jupyter-notebook --no-browser --ip=$HOSTNAME
  
  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.
  
  

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://c300:8889/tree?token=43e8be6174d89151786a8ab0140c4fb57a5502ccda0a73a0
http://127.0.0.1:8889/tree?token=43e8be6174d89151786a8ab0140c4fb57a5502ccda0a73a0
This means your Jupyter session's port number is 8889 and host name is c300.

On your local PC/laptop, if you are using Linux or MacOS, open a terminal and type:
ssh -f -N -L port:hostname: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 8889:c300:8889 thanghn90@schooner.oscer.ou.edu
Enter your OSCER password if prompted.
This command opens a "tunnel" from port 8889 of my local PC/laptop, through SSH port (22) of OSCER login node (schooner.oscer.ou.edu), authenticated with my OSCER account, into port 8889 of compute node c300 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:

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

Under the Local Clients section (left), type:

• The port number of your Jupyter session (e.g. 8889) 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 name of your Jupyter session (e.g. c300) into the Remote Server, and
• The port number of your Jupyter session (e.g. 8889) into the Remote Port.
   

Then click the Save button.

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

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.

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:8889/tree?token=43e8be6174d89151786a8ab0140c4fb57a5502ccda0a73a0

Some tips when running Jupyter Lab / Notebook:

• While typing code, hit the Tab key on your keyboard to show a dropdown list of code suggestion.
  

• While typing arguments for a function, hit Shift+Tab to bring up the function's docstring (i.e. a brief description of the function and its arguments) if there is any.

• To enable dark mode in Jupyter Lab, simply go to Settings --> Jupyter Lab Theme --> select Jupyter Lab Dark.
  

• To enable dark theme in Jupyter Notebook, you first need to install jupyterthemes package via pip, then change Jupyter Notebook theme via jt -t onedork command.
  
  

To close a Jupyter tunnel in Linux or MacOS, type in a terminal on your local PC/laptop:
ps aux |grep port:hostname
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 8889:c300
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 8889:c300:8889 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