.. _jupyterlab:

JupyterHub 
===========

.. note::
    - Support: https://skao.slack.com/archives/C03AQH37K8S
    - Code Repository: TBC
    - External JupyterHub installation instructions: https://z2jh.jupyter.org/en/stable/jupyterhub/installation.html

Pre-requisites
--------------

- A Kubernetes cluster
- The Kubernetes cluster must have a suitable ``StorageClass`` configured to enable persistent storage
- Similarly, a suitable Ingress controller is needed to enable external traffic to access the JupyterHub server
- A client configured on the SKA IAM deployment to issue and validate access tokens for the service 

.. _iam-jupyterlab-services:

IAM Configuration
^^^^^^^^^^^^^^^^^

For this service, the scopes required are:

- ```email``` 
- ```offline_access``` 
- ```openid``` 
- ```profile```

Follow the next instructions to create and manage the :doc:`/services/dependent/iam-client/iam-client`, including these scopes.

.. note::

   Once saved, note the ``Client Name``, ``Client Secret``, and ``Redirect URIs``; these will be needed to configure the JupyterHub authentication and the YAML files. 
   For more information, visit: `IAM Client Registration <https://indigo-iam.github.io/v/v1.9.0/docs/tasks/user/client-registration/>`_.

JupyterHub Service
------------------

Helm Deployment
^^^^^^^^^^^^^^^

Create a `values.yaml` with the following fields; a description of the key configuration settings follows:

.. code-block:: yaml

   hub:
      config:
         Authenticator:
            enable_auth_state: true
            allow_all: true
         GenericOAuthenticator:
            login_service: "<Name of the Login Service that will appear within the Login Screen>"
            client_id: <CLIENT_ID>
            client_secret: <CLIENT_SECRET>
            oauth_callback_url: <REDIRECT_URI>
            authorize_url: https://ska-iam.stfc.ac.uk/authorize
            token_url: https://ska-iam.stfc.ac.uk/token
            userdata_url: https://ska-iam.stfc.ac.uk/userinfo
            scope:
            - openid
            - profile
            - email
            - offline_access
            userdata_token_method: GET
            userdata_params: {'state': 'state'}
            username_key: preferred_username
         JupyterHub:
            authenticator_class: generic-oauth

      extraConfig:
         logoConfig: |
               import urllib.request
               urllib.request.urlretrieve("<LOGO_URL>", "logo.png")
               c.JupyterHub.logo_file = '/srv/jupyterhub/logo.png'

      baseUrl: /<SERVICE_BASE_URL>/

      db:
         pvc:
            storageClassName: <STORAGE_CLASS>

   singleuser:
      memory:
         limit: 1G
         guarantee: 1G

      cpu:
         limit: 0.5
         guarantee: 0.5

      storage:
         dynamic:
            storageClass: <STORAGE_CLASS>
         capacity: 1Gi

      # Defines the default image
      defaultUrl: "/lab"
      extraEnv:
         JUPYTERHUB_SINGLEUSER_APP: "jupyter_server.serverapp.ServerApp"
      image:
         name: jupyter/minimal-notebook
         tag: latest
      profileList:
         - display_name: "Minimal environment"
            description: "A Python environment."
            default: true
         - display_name: "Data science environment"
            description: "Python, R and Julia environments."
            kubespawner_override:
            image: jupyter/datascience-notebook:latest

The following `values.yaml` variables will need to be modified for each deployment:

   - ``<CLIENT_ID>``: The ID for the SKA IAM client created above
   - ``<CLIENT_SECRET>``: The corresponding client secret generated by SKA IAM
   - ``<REDIRECT_URI>``: This will be the hostname of the service; if your Jupyter service will be hosted at `https://example.com/jupyter/` the callback URL will be `https://example.com/jupyter/hub/oauth_callback`. This must match (one of) the *Redirect URIs* set above when configuring the IAM client
   - ``<LOGO_URL>``: *This is optional*. The specified logo will appear in the left corner. You will need a URL for the logo in ``png`` or ``jpg`` format.
   - ``<SERVICE_BASE_URL>``: If the JupyterHub service is to be hosted at a subdirectory URL, (e.g. example.com/jupyterhub), change the <SERVICE_BASE_URL> to reflect this; in this example, it would be: ``/jupyterhub/``
   - ``<STORAGE_CLASS>``: Include the name of the ``StorageClass`` of your Kubernetes cluster

Once the ``values.yaml`` has been updated, the Helm package manager can be used to install JupyterHub. Helm typically requires a release name and a chart identifier; the chart releases for JupyterHub can be found at: https://hub.jupyter.org/helm-chart/.

The following commands will add and update the JupyterHub Helm repository:

.. code-block:: bash

   helm repo add jupyterhub https://hub.jupyter.org/helm-chart/
   helm repo update

Then, to install JupyterHub with Helm, use the following command. The ``jupyterhub-release`` can be changed to a more appropriate name, as can the specified ``Namespace``:

.. code-block:: bash

      helm upgrade --cleanup-on-fail \
         --install jupyterhub-release jupyterhub/jupyterhub \
         --namespace jhub-srcnet-01 \
         --create-namespace \
         --values values.yaml

To install another version or to fix the deployment to a concrete version, use ``--version``:

.. code-block:: bash

      helm upgrade --cleanup-on-fail \
         --install jhub-release jupyterhub/jupyterhub --version 3.3.8 \
         --namespace jhub-srcnet-01 \
         --create-namespace \
         --values values.yaml

Use ``helm list -A`` to view see the current installed charts with their versions.