F Bartusch at 12:39, 20 August 2025

2025-08-20T12:39:45Z

← Older revision		Revision as of 14:39, 20 August 2025
Line 65:		Line 65:
	# Don't change these settings		# Don't change these settings
	#SBATCH --nodes=1		#SBATCH --nodes=1
	#SBATCH --partition=~~compute~~		#SBATCH --partition=interactive
	#SBATCH --job-name=minimal-notebook-7.4.1		#SBATCH --job-name=minimal-notebook-7.4.1
	#PBS -j oe		#PBS -j oe

F Bartusch: Remove typo

2025-08-19T12:24:03Z

Remove typo

← Older revision		Revision as of 14:24, 19 August 2025
Line 148:		Line 148:
	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	$ cd ~		$ cd ~
	$ ln -s /pfs/10/work/ $HOME/~~workv~~		$ ln -s /pfs/10/work/ $HOME/work
	$ ln -s /pfs/10/project $HOME/project		$ ln -s /pfs/10/project $HOME/project
	</syntaxhighlight>		</syntaxhighlight>

F Bartusch at 15:11, 7 May 2025

2025-05-07T15:11:44Z

← Older revision		Revision as of 17:11, 7 May 2025
Line 81:		Line 81:
	$ jobid=$(sbatch --parsable binac2-minimal-notebook.slurm)		$ jobid=$(sbatch --parsable binac2-minimal-notebook.slurm)
	</syntaxhighlight>		</syntaxhighlight>

			{\|style="background:#deffee; width:100%;"
			\|style="padding:5px; background:#cef2e0; text-align:left"\|
			[[Image:Attention.svg\|center\|25px]]
			\|style="padding:5px; background:#cef2e0; text-align:left"\|
			Depending on the current load on BinAC 2 and the resources you requested in your job script, it may take some time for the job to start.
			\|}

	== Create SSH tunnel ==		== Create SSH tunnel ==

F Bartusch: Created page with "{{Softwarepage|devel/jupyterlab}} {| width=700px class="wikitable" |- ! Description !! Content |- | module load | devel/jupyterlab |- | License | [https://github.com/jupyterlab/jupyterlab/blob/main/LICENSE JupyterLab License] |- | Links | [https://jupyter.org/ Homepage] |- | Graphical Interface | Yes |} = Description = JupyterLab is a web-based interactive development environment for notebooks, code, and data. Currently, BinAC 2 provides the following [https://ju..."

2025-05-07T15:05:42Z

Created page with "{{Softwarepage|devel/jupyterlab}} {| width=700px class="wikitable" |- ! Description !! Content |- | module load | devel/jupyterlab |- | License | [https://github.com/jupyterlab/jupyterlab/blob/main/LICENSE JupyterLab License] |- | Links | [https://jupyter.org/ Homepage] |- | Graphical Interface | Yes |} = Description = JupyterLab is a web-based interactive development environment for notebooks, code, and data. Currently, BinAC 2 provides the following [https://ju..."

New page

{{Softwarepage|devel/jupyterlab}}

{| width=700px class="wikitable"
|-
! Description !! Content
|-
| module load
| devel/jupyterlab
|-
| License
| [https://github.com/jupyterlab/jupyterlab/blob/main/LICENSE JupyterLab License]
|-
| Links
| [https://jupyter.org/ Homepage]
|-
| Graphical Interface
| Yes
|}

= Description =

JupyterLab is a web-based interactive development environment for notebooks, code, and data.

Currently, BinAC 2 provides the following [https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#jupyter-minimal-notebook JupyterLab Docker images] via Apptainer:

* <syntaxhighlight inline>minimal-notebook</syntaxhighlight>
* <syntaxhighlight inline>r-notebook</syntaxhighlight>
* <syntaxhighlight inline>julia-notebook</syntaxhighlight>
* <syntaxhighlight inline>scipy-notebook</syntaxhighlight>

= Usage =

This guide is valid for <syntaxhighlight inline>minimal-notebook</syntaxhighlight>. You can also follow it for the other notebook flavors — just replace <syntaxhighlight inline>minimal-notebook</syntaxhighlight> with one of the other notebooks listed above.

You will start a job on the cluster as usual, create an SSH tunnel, and connect to the running JupyterLab instance via your browser.

== Start JupyterLab ==

The module <syntaxhighlight inline>devel/jupyterlab</syntaxhighlight> provides a job script for starting a JupyterLab instance on BinAC 2. Load the module and copy the template job script into your workspace:

<syntaxhighlight>
$ module load devel/jupyterlab

</syntaxhighlight>

Upon loading the module, you can list the available template job scripts and copy the one you need into your workspace:

<syntaxhighlight>
$ ls $JUPYTERLAB_EXA_DIR
binac2-julia-notebook.slurm binac2-minimal-notebook.slurm binac2-r-notebook.slurm binac2-scipy-notebook.slurm

$ cp $JUPYTERLAB_EXA_DIR/binac2-minimal-notebook.slurm <your workspace>
</syntaxhighlight>

The job script is very simple; you only need to adjust the hardware resources according to your needs:

<syntaxhighlight lang="bash" line>
#!/bin/bash

# Adjust these values as needed
#SBATCH --cpus-per-task=1
#SBATCH --mem=2gb
#SBATCH --time=6:00:00

# Don't change these settings
#SBATCH --nodes=1
#SBATCH --partition=compute
#SBATCH --job-name=minimal-notebook-7.4.1
#PBS -j oe

# Load Jupyterlab module
module load devel/jupyterlab/7.4.1

# Start jupyterlab
$ ${JUPYTERLAB_BIN_DIR}/minimal-notebook.sh
</syntaxhighlight>

Now submit the job to SLURM. This command will store the job ID in the variable <syntaxhighlight inline>jobid</syntaxhighlight>

<syntaxhighlight>
$ jobid=$(sbatch --parsable binac2-minimal-notebook.slurm)
</syntaxhighlight>

== Create SSH tunnel ==

The compute node on which JupyterLab is running is not directly reachable from your local workstation. Therefore, you need to create an SSH tunnel from your workstation to the compute node via the BinAC 2 login node.

The job's standard output file (<syntaxhighlight inline>slurm-${jobid}.out</syntaxhighlight>) contains all the information you need. Please note that details such as the IP address, port number, and access URL will differ in your case.

<syntaxhighlight lang="bash">
$ cat slurm-${jobid}.out
</syntaxhighlight>

[[File:Binac2_jupyterlab_connection_details.png | 800px | center | JupyterLab connection info]]

=== Linux Users ===

Copy the <syntaxhighlight inline>ssh -N -L ... </syntaxhighlight> command and execute it in a shell on your workstation. After successful authentication, the SSH tunnel will be ready to use. The ssh command does not return any output. If there are no error messages, everything should be fine:

[[File:Binac2_jupyterlab_ssh_tunnel_linux.png | 800px | center | SSH tunnel creation with Linux]]

=== Windows Users ===

If you are using Windows, you will need to create the SSH tunnel using an SSH client of your choice (e.g. MobaXTerm, PuTTY, etc.). Her, we will show how to create an SSH tunnel with MobaXTerm.

Select <syntaxhighlight inline>Tunneling</syntaxhighlight> in the top ribbon. Then click <syntaxhighlight inline>New SSH tunnel</syntaxhighlight>.
Configure the SSH tunnel with the correct values taken from the SSH tunnel information provided above.
For the example in this tutorial it looks as follows:

[[File:Binac2_jupyterlab_mobaxterm.png | 800px | center | SSH tunnel creation with MobaXTerm]]

== Access JupyterLab ==

JupyterLab is now running on a BinAC 2 compute node, and you have created an SSH tunnel from your workstation to that compute node. Open a browser and paste the URL with the access token into the address bar:

[[File:Binac2_jupyterlab_browser_url.png | 800px | center | JupyterLab URL in browser ]]

Your browser should now display the JupyterLab interface:

[[File:Binac2_jupyterlab_browser_lab.png | 800px | center ]]

== Shut Down JupyterLab ==

You can shut down JupyterLab via <syntaxhighlight inline>File -> Shut Down</syntaxhighlight>.
Please note that this will also terminate your compute job on BinAC 2!

[[ File:Binac2_jupyterlab_browser_shutdown.png | 800px | center | JupyterLab user interface]]

== Tips & Tricks ==

=== Managing Notebooks ===

JupyterLab's root directory will be your home directory. Since your home directory is backed up daily, you may want to store your notebooks there.
It may also be a good idea to place your notebooks under proper version control using Git.

=== Access <syntaxhighlight inline>work</syntaxhighlight> and <syntaxhighlight inline>project</syntaxhighlight> ===

The notebooks will always be able to access your data stored in <syntaxhighlight inline>work</syntaxhighlight> and <syntaxhighlight inline>project</syntaxhighlight>. However, the file browser shows the content in your home directory and you won’t be able to access <syntaxhighlight inline>work</syntaxhighlight> and <syntaxhighlight inline>project</syntaxhighlight> initially.
You can create symbolic links in your home directory to work and project, making these two partitions available in JupyterLab's file browser.

<syntaxhighlight lang="bash">
$ cd ~
$ ln -s /pfs/10/work/ $HOME/workv
$ ln -s /pfs/10/project $HOME/project
</syntaxhighlight>

Through that link in your home directory you can navigate to your research data in Jupyterlab's file browser.
Here is an example how I linked to my directory:

[[ File:Binac2_jupyterlab_link.png | 800px | center | Access work and project storage in JupyterLab file browser ]]

=== Managing Kernels ===

Depending on the notebook you started, the available kernels will differ.
The Python notebook, for example, only has one Python kernel, whereas the R notebook has only one R kernel, and so on.
Given the nearly endless combinations of programming languages and packages they provide, we suggest creating your own kernels if needed.
The kernels are stored in your hone directory on BinAC 2: <syntaxhighlight inline>$HOME/.local/share/jupyter/kernels/</syntaxhighlight>
You cannot install new kernels directly from within JupyterLab; this must be done from the command line in your usual BinAC 2 shell session.

=== Add a new Kernel ===

We will show you how to create new kernels for Python and R.

==== Python ====

<syntaxhighlight lang="bash">
module load devel/miniforge
conda create --name kernel_env python=3.13 pandas numpy matplotlib ipykernel # 1
conda activate kernel_env # 2
python -m ipykernel install --user --name pandas --display-name="Python 3.13 (pandas)" # 3
# Installed kernelspec pandas in $HOME/.local/share/jupyter/kernels/pandas
</syntaxhighlight>

The first command creates a new Conda environment called <syntaxhighlight inline>kernel_env</syntaxhighlight> and installs a specific Python packages , along with a few additional Python packages.
It's important that you also install <syntaxhighlight inline>ipykernel</syntaxhighlight>, as we will need it later to create the JupyterLab kernel.
The second command activates the <syntaxhighlight inline>kernel_env</syntaxhighlight> Conda environment.
The third command creates the new JupyterLab kernel.

[[ File:Binac2_jupyterlab_new_kernel.png | 800px | center | New Python kernel in JupyterLab]]

==== R ====

The instructions for creating new R kernels are slightly different.

<syntaxhighlight lang="bash">
module load devel/miniforge
conda create --name r_kernel_env r-base=4.4.3 jupyter r-irkernel
conda activate r_kernel_env
R
# In the R-Session
install.packages(...)
IRkernel::installspec(name = 'ir44', displayname = 'R 4.4.3')
</syntaxhighlight>

The first command creates a new Conda environment called <syntaxhighlight inline>r_kernel_env</syntaxhighlight> and installs a specific R version.
It's important to also install <syntaxhighlight inline>r-irkernel</syntaxhighlight>, as we will need it later to create the JupyterLab kernel.
The second command activates the <syntaxhighlight inline>r_kernel_env</syntaxhighlight> Conda environment and open an R session.
In this session, you can install any R packages you need for your kernel.
Finally, create the new kernel with the <syntaxhighlight inline>installspec</syntaxhighlight> command.

=== Remove a Kernel ===

To remove a kernel from JupyterLab, simply delete the corresponding directory at <syntaxhighlight inline>$HOME/.local/share/jupyter/kernels/</syntaxhighlight>:

<syntaxhighlight lang="bash">
# Remove the JupyterLab kernel installed in the previous example
rm -rf $HOME/.local/share/jupyter/kernels/pandas
</syntaxhighlight>

Also, remove the corresponding Conda environment if you do not need it any more:

<syntaxhighlight lang="bash">
conda env remove --name kernel_env
</syntaxhighlight>

BinAC2/Software/Jupyterlab - Revision history

F Bartusch at 12:39, 20 August 2025

F Bartusch: Remove typo

F Bartusch at 15:11, 7 May 2025