Controls-docs/engineering-guide/puppet/profiles/jupyterhub.rst

profile::jupyterhub

This module configures the node for running a jupyterhub service able to spawn singleuser servers on cluster nodes via SLURM

The jupyterhub software itself will not be installed by this module. It is expected to be found in an existing environment usually installed separately by conda and centrally served on a distributed file system (There is a reference installation in the environment module anaconda/2019.03 within the jupyterhub_dev_py36 conda environment)

Supported jupyterhub versions: jupyterhub-0.96 or the current (as of 2019-05) development version 1.0.0b1. The development version is preferred due to recent fixes that enable a clean shutdown on a batch cluster.

Optional customization of User selectable options

This installation uses the optionsSpawner plugin to offer user selectable customizations on the spawning web page. By default, a simple dialog with selectable partitions and runtime is offered. If a more extended customization page is required, the administrator can create the file /etc/jupyterhub/optionsspawner_config.py and put additional options inside. The jupyterhub main configuration file /etc/jupyterhub/jupyterhub_config.py will check whether the file exists and load it. In this way we can keep the puppet module more generic.

Some adaptions may require deeper changes to the configuration file and adaption of the puppet code

Parameters

Name	Type	Default
admin_users	Array	hiera('jupyterhub::admin_users')
api_port	Integer	hiera('jupyterhub::api_port', 8080)
env_setup	String	hiera('jupyterhub::env_setup')
group_whitelist	Array	hiera('jupyterhub::group_whitelist')
hub_port	Integer	hiera('jupyterhub::hub_port', 8000)
hub_version	String	hiera('jupyterhub::hub_version')
partitions	Hash	hiera('jupyterhub::partitions')
tls_cert	String	hiera('jupyterhub::tls_cert')
tls_key	String	hiera('jupyterhub::tls_key')

admin_users

A list of user names. These users will get access to the jupyterhub administration web pages.

Example:

jupyterhub::admin_users:
  - 'feichtinger'
  - 'caubet_m'
  - 'bliven_s'
  - 'loktionova_n'

api_port

Port number of the port on which the jupyterhub API will be listening (internally used by jupyterhub for control communications)

env_setup

Lines to be inserted into the bash scripts for defining the jupyterhub environment for both the server and the spawned client sessions (it is important that the server and the singleserver client host both run the same jupyterhub and spawner codes)

Example:

export PMODULES_VERSION=1.0.0rc4
source /opt/psi/config/profile.bash
module use unstable &> /dev/null
module load anaconda/2019.03 &> /dev/null
conda activate jupyterhub_dev

group_whitelist

A list of unix groups that will be granted access to this jupyterhub.

Example:

jupyterhub::group_whitelist:
  - 'svc-cluster_merlin5'

hub_port

The main port to which clients will connect.

hub_version

Version String of jupyterhub. Currently either '0.96' or '1.0.0b2' is supported. Recommended: '1.0.0b2'.

partitions

SLURM partitions to be offered in the default option selection. Should be a mapping of partition names to descriptive strings.

Example:

jupyterhub::partitions:
  'test' : 'Test nodes'
  'merlin' : 'merlin standard'
  'gpu' : 'GPU nodes'

tls_cert

String (PEM Format) of the web server certificate

tls_key

Eyaml encoded string of the web server certificate key (PEM format)