DockerSpawner

JupyterHub provides a range of spawners (method of starting new Jupyter environments for individual users). One such package is called DockerSpawner and that creates new Jupyter environments for each user in a separate Docker container.

Please ensure DockerSpawner is working for your JupyterHub.

Installing cdsdashboards

Install the cdsdashboards package in the JupyterHub Python environment:

pip install cdsdashboards
# or
conda install -c conda-forge cdsdashboards

Generic Changes to jupyterhub_config.py

c.JupyterHub.spawner_class = 'cdsdashboards.hubextension.spawners.variabledocker.VariableDockerSpawner'

c.JupyterHub.allow_named_servers = True

c.DockerSpawner.name_template = "{prefix}-{username}-{servername}"

c.DockerSpawner.image = 'ideonate/containds-allr-datascience:0.4.1'

The changes above are mostly for guidance - you may want to use your own Docker image, but it should follow the guidelines listed later in this document.

Instead of the original DockerSpawner, you actually need to use a slightly enhanced version of that spawner called VariableDockerSpawner - that is set by assigning to c.JupyterHub.spawner_class as above. Corresponding alternatives are available for the other spawners provided in the dockerspawner package if you are using those instead.

The allow_named_servers option is a standard JupyterHub option where every user gets more than just their single ‘My Server’ Jupyter environment. They can add extra environments by specifying a name. ContainDS Dashboards makes use of this by running the presentation servers as named servers - they are really servers just like the original Jupyter notebook servers, but running Voilà or another system instead.

For ‘named servers’ to run correctly with DockerSpawner, you need to specify a name_template based on both username and servername - the example above is fine.

Enabling Dashboards in jupyterhub_config.py

The following options in your config file will install the extension. Please note if you have existing customisations you may need to merge these with your existing settings.

from cdsdashboards.app import CDS_TEMPLATE_PATHS
from cdsdashboards.hubextension import cds_extra_handlers

c.JupyterHub.template_paths = CDS_TEMPLATE_PATHS
c.JupyterHub.extra_handlers = cds_extra_handlers

c.CDSDashboardsConfig.builder_class = 'cdsdashboards.builder.dockerbuilder.DockerBuilder'

If you are using The Littlest JupyterHub, you can copy any new settings into a new file called /opt/tljh/config/jupyterhub_config.d/cdsdashboards_config.py.

Docker Image Requirements

The image you use for the single-user server should have jhsingle-native-proxy installed plus any other helper scripts required. These are fairly small, so the easiest thing is to pip install cdsdashboards[user] or conda install -c conda-forge cdsdashboards-singleuser to install every ContainDS Dashboards component.

It also needs Voilà, Streamlit, or whichever frameworks you want to use.

Please see docker-singleuser-images for an example, or use the ones created for you already:

Containing Voilà, Streamlit, Plotly Dash, and Bokeh/Panel as presentation types:

Using Voilà as the presentation type:

Using R Shiny or Voilà as the presentation type:

Using all built-in presentation types - Voilà, Streamlit, Plotly Dash, and Bokeh/Panel, and R Shiny:

These are based on the similarly-named Jupyter Docker Stacks images, just with extra support for ContainDS Dashboards. The ContainDS Dockerfile versions are on GitHub here.

The image should contain a start.sh script on the path (all those listed here do), otherwise the cmd to be run must be configured differently.

Options

Extra options to control behavior of Dashboards are available - see Customization.

DockerSpawner users (compared to users of LocalProcessSpawner or KubeSpawner etc) have extra functionality available whereby the dashboard creator can select a ‘source server’ to clone. The dashboard will be built out of that image, meaning any extra packages installed in the server will be available. (Source Servers)

Please sign up to the ContainDS email list to receive notifications about updates to the project including new features and security advice.

Sponsorship

If you are using ContainDS Dashboards in production please consider subscribing to a support plan.

This will back future development of the project and is a great way to satisfy your business stakeholders that you are adopting sustainable and supported software.

It also helps you reach your corporate social responsibility goals since our open source software is used by academic and non-profit organizations.

More Sponsorship details are on GitHub.