``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 <https://github.com/ResearchComputing/jupyterhub-options-spawner>`_ 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:

.. code:: bash

    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)