How To: Run JupyterHub on a single VM enabling Notebooks persistence (sys-admin nomination required)

Prerequisites

Make sure you are registered to the IAM system for INFN-CLOUD https://iam.cloud.infn.it, as described in the Getting Started guide. Only registered users can login into the INFN-CLOUD dashboard https://my.cloud.infn.it.

Access to the INFN-CLOUD dashboard enables users to instantiate a JupyterHub service on a single VM, providing Notebooks with data persistence.

Important

This solution requires the instantiation of a JupytherHub service on top of a newly created virtual machine (VM). You will have complete control, administration rights, on the respective service and VM becoming a service administrator.

Please read the INFN Cloud AUP in order to understand the responsabilities you have in managing this service.

How to deploy and access the Jupyterhub service

Step 1 - Connecting and authenticating to the INFN-CLOUD dashboard

Connect to the INFN-CLOUD dashboard (https://my.cloud.infn.it/):

Fig 1: INFN-CLOUD welcome dashboard

Fig 1: INFN-CLOUD welcome dashboard

You need to authenticate with the credentials used for the IAM account (https://iam.cloud.infn.it/login).

INFN-CLOUD IAM login

Fig2: INFN-CLOUD IAM login

Step 2 - Select and Configure the JupyterHub service

After logging into the dashboard, select the “Jupyter with persistence for Notebooks” card in the service catalog and click on the Configure button. First of all you are asked to select under which project, among those you belong to, your application should be deployed.

dashboard

After that you will have to configure your deployment. The deployment definition window consists of three tabs: “General”, “Authorizations” and “Advanced”. Before continuing please fill the first mandatory field - the “Deployment description”. You will not be able to submit your deployemnt without it!

Deployment description

“General” TAB

In this tab, all fields have default values but can be changed if desired. You can fill the following fields:

  • num_cpus

    • Number of virtual CPUs for the VM that will host the Jupyter service. The default value is 2.
  • mem_size

    • Amount of memory for the VM in GB. The default value is 4.
  • enable_monitoring

    It is disabled by default.

  • jupyter_images

  • jupyterlab_collaborative

    • enable the new collaborative editing feature that allows collaboration in real-time between multiple users. It is disabled by default. See JupyterLab documentation for more information
  • jupyterlab_collaborative_image

    • “dodasts/snj-base-jlabc:v1.0.5-snj” is the default image for JupyterLab collaborative feature.
  • ports

    • List of additional ports to be opened. By default, and you don’t need to specify them, the deployment will have the following TCP ports accessible: 22 (ssh to the host VM), 3000 (for grafana dashboard), 8888 (for JupyterHub), 8889 (for jupyter collaborative)
General tab

Note

Please be aware that this solution is only available for the Ubuntu 20.04 operating system.

“Authorization” TAB

You can decide to authorize INFN Cloud user groups by filling:

  • iam_groups
    • user groups that are allowed to access jupyterhub services.
  • iam_admin_groups
    • user groups that are allowed to administrate jupyterhub.

Note

INFN Cloud (https://iam.cloud.infn.it) is the IAM identity provider.

Authorization tab

“Advanced” TAB

Advanced Tab

Advanced parameters can be configured here:

  • Configure Scheduling

    • Automatic (Default)
      • The system will choose the most suitable cloud provider for the deployment
    • Manual
    • A resource provider can be selected from the list of available cloud sites
List of available cloud resources providers Tab

The following extra parameters can be set as well:

  • Deployment creation timeout (minutes)
    • If specified the deployment will fail when the timeout is reached
  • Do not delete the deployment in case of failure
  • Send a confirmation email when complete

Step 3 - Submitting the deployment

After submitting your application (green button), you are redirected to the list of your deployments from where you can follow the evolution of the new deployment.

Step 3

Step 4 - Access your application

On successful completion (“CREATE_COMPLETE”),

  • an e-mail is send to notify you on the status of the deployment, completed or failed
Deployment notification e-mail
  • you can check your deployment outputs by clicking on the “Details” button and then on the “Output values” Tab.
Deployment details
Step 4

Use the reported IP address to connect to the services you deployed.