Differences

This shows you the differences between two versions of the page.

--- doku:jupyterhub [2021/09/27 13:23] – [start a server] goldenberg
+++ doku:jupyterhub [2023/04/03 08:23] – [BYOI: Bring your own (Singularity) Image] katrin
@@ Line 1: / Line 1: @@
-====== Jupyterhub ======
+====== JupyterHub ======
-The VSC offers a jupyterhub available for all VSC users at [[https://vsc.ac.at/jupyterhub/hub/login]]
+The VSC offers a JupyterHub service available for all VSC users at [[https://jupyterhub.vsc.ac.at]]
 Login works with any cluster user (both VSC3 and VSC4) and uses the OTP like on the cluster. A VPN connection is not needed.
-===== start a server =====
+Also make sure to checkout the [[doku:jupyterhub#FAQ|FAQ]] to see if your question was already answered.
+===== Important Information: Resource Allocation =====
+The started Jupyter Server instance runs on a separate hardware partition ('jupyter') in each cluster in order to not interfere with the regular operation of VSC.
+Since the machines in this partition are shared between all users it is important to be aware of the memory requirements of the processing you are doing.
+In order to help the Jupyter users the VSC Team recently added a Memory Resources Monitor plugin to the JupyterLab IDE. It is displayed in the right upper corner of the JupyterLab IDE and shows the current memory consumption of the Jupyter Server instance.
+If your job goes out of memory it will affect your job as well as other users running on the same node. This is a hardware/system limitation of how slurm and linux work together. So make sure to have the right amount of memory selected for your purposes.
+<box 80% round orange|Important> Always make sure to select the right amount of memory suited to your requirements.</box>
+===== Start a new Jupyter server =====
 choose a profile:
-  * VSC4 Singularity Image - a singularity image running on VSC4 (this is the default)
+  * VSC-4 Singularity Image (this is the default)
-  * VSC3 Singularity Image - a singularity image running on VSC3+
+  * VSC-4 python venv
-  * VSC3 GPU nodes - a singularity image with CUDA support running on GPU nodes of VSC3+ (currently only GTX1080)
+  * VSC-4 conda python env
-  * VSC4 direct - a python virtual environment running directly on VSC4
+  * VSC-3 Singularity Image
-  * If you are participating in a course, there is most likely only a fixed profile available
+  * VSC-3 GTX1080 GPU Singularity Image
+  * VSC-3 A40 GPU Singularity Image
+  * If you are participating in a training, there is most likely only a single fixed profile or special training profiles available
-**Note:** You need a VSC4 user for the VSC4 profiles and a VSC3 user for the VSC3+ profiles
+**Note:** You need a VSC4 user for the VSC4 profiles and a VSC3 user for the VSC3 profiles. You also need to have logged into the respective cluster via SSH at least once after getting a username.
 In all profiles, you can choose the IDE, either Jupyter Notebook or the more modern Jupyter Lab (which is the default)
 For all the singularity profiles, you can choose between a predefined image (default) or a custom image:
-  * Predefined image gives a dropdown list of different singularity images. Each image shows a short description, a version, an author and a link to the image. The GPU option only has one predefined image.
+  * Predefined image gives a dropdown list of different singularity images. Each image shows a short description, a version, an author and a link to the image. The GPU option only has one predefined image. See also some examples [[https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html|here]]
-  * Custom image shows a line where the complete path to the image has to be entered. Note that the image has to reside on the cluster already. Web-upload is not possible.
+  * Custom image shows a line where the complete path to the image has to be entered. Note that the image has to reside on the cluster already. Web-upload is not possible at the moment.
-**Note:** course profiles do not allow for customization.
+**Note:** training profiles usually do not allow for customization.
-Independent of the profile you can choose the number of CPUs, size of the RAM, the maximum running time.
+Independent of the profile you can choose the number of CPUs, size of the RAM and the maximum running time.
 After everything is selected, press start - your server will start and show you the JupyterLab interface or the simpler Notebook interface. In both cases, there is a list of all files in your home directory, which includes previously created notebooks.
-===== JupyterLab =====
+==== Working with JupterLab IDE ====
 Simply click on the desired notebook in your list - it will open in the main panel.
@@ Line 36: / Line 55: @@
 It is possible to log out of the system and leave the server running with File -> Log Out. Keep in mind that this also keeps the selected resources blocked for other users.
-To stop the server, user File -> Hub Control Panel and choose 'Stop My Server'.
+To stop the server, user //File// -> //Hub Control Panel//
+On the page that opens click the button labelled 'Stop My Server'.
-===== Jupyter Notebook =====
-Simply click on the desired notebook in your list - it will be opened in a new tab.
+==== Working with Jupyter Notebook IDE ====
+If you have chosen to work with the Jupyter Notebook IDE, simply click on the desired notebook in your list - it will be opened in a new tab.
 On first use, no notebook is present yet. To create one (or to create new ones), click on 'new' in the upper right area above the file list and choose the appropriate type. The new notebook will start in a new browser tab. It will show up as untitled in the file list, and can be renamed by selecting the checkbox to the left of the name and choose 'rename' at the top.
@@ Line 49: / Line 70: @@
 To stop the server, click on 'Control Panel' at the top right and choose 'Stop My Server'.
+===== BYOI: Bring your own (Apptainer/Singularity) Image =====
+It is possible to use a custom apptainer/singularity image with our JupyterHub profiles.
+==== Necessary Packages ====
+To get your custom image to run in our JupyterHub environment it is necessary to add the following packages into your image
+<code>
+# This package pulls in all the necessary dependencies to start a jupyter server
+jupyterhub==3.1.1
+# This package provides functionality needed to run in the slurm environment of VSC (e.g. `batchspawner-singleuser` script).
+git+https://github.com/katringoogoo/batchspawner.git@1.2.0+auth_fix
+</code>
+In addition we usually also install the following jupyterlab extensions in our images but they are not strictly necessary and just provide extended functionality like memory monitoring for the user:
+  * jupyterlab-system-monitor
+  * jupyterlab-git
+  * jupyterlab-widgets
+**An up 2 date list of packages can always be found in our repo: [[https://gitlab.tuwien.ac.at/vsc/jupyterhub/jupyterhub-docker-stacks/-/blob/main/tools/requirements.txt|requirements.txt]]**
+==== Via Docker Container ====
+A good starting point for your own container are the official JupyterHub Docker Stacks Images @ [[https://github.com/jupyter/docker-stacks|Docker-Stacks]]. If you take these as a basis make sure you use the right version for the current version of our JupyterHub
+In order to be able to use the image with JupyterHub you also have to convert it to a **singularity image** (or build it as a singularity image in the first place) and place it into a folder that is accessible from the VSC compute nodes.
+Building a singularity image from e.g. a docker container can easily be done with the `singularity build` command. See the singularity documentation for examples: [[https://apptainer.org/user-docs/3.8/build_a_container.html|Build a (singularity) container]]
+==== Run hooks from /usr/local/bin/before-notebook.d ====
+If your image needs to run hooks before startup (e.g. the pyspark image depends on this [[https://github.com/jupyter/docker-stacks/blob/master/pyspark-notebook/Dockerfile|PySpark Dockerfile]]), the docker stack images provide a folderfor such startup scripts `/usr/local/bin/before-notebook.d`.
+Unfortunately the batchspawner package does not source them so we are using a custom startscript in our images called `vsc-singleuser.sh`. All it does is to run the hooks from `/usr/local/bin/before-notebook.d` before executing the `batchspawner-singleuser` script.
+The script can be found at [[https://gitlab.tuwien.ac.at/vsc/vsc-jupyterhub-notebooks/-/blob/main/tools/vsc-singleuser.sh|vsc-singleuser.sh]].
+Note: Contact us to get read rights to the repository.
+===== FAQ =====
+  * **My Server instance is stuck and I get a timeout when I try to reload the window. Going to the VSC jupyterhub website also results in a timeout.**
+In order to to control the running instance, navigate directly to the following URL: [[https://jupyterhub.vsc.ac.at/hub/home]]. From there you can click 'Stop My Server' to stop the running instance (if there is any).