Hub Options

There are extra options that can be added to your jupyterhub_config.py file. (See here for how to add config on The Littlest JupyterHub.)

Named Server display

Options to remove ‘Named Server’ functionality for users on their home page. You can remove the named server section and/or the new bottom section where servers started to act as dashboards are hidden.

Please note it will still be possible for users to create named servers if they know the direct API URLs.

c.JupyterHub.template_vars = {
    'cds_hide_user_named_servers': False,
    'cds_hide_user_dashboard_servers': False
    }

Dashboard server name

To change the server name of your published dashboards:

c.CDSDashboardsConfig.server_name_template = 'dash-{urlname}-{date}-{time}'

This template variable can use {urlname} (the URL-safe version of the dashboard name), {date} (current date in YYmmdd format), and {time} (current date in HHMMSS format).

The default is ‘dash-{urlname}’. The key advantage of the default (which does not use date/time) is that updated dashboards will replace old versions of the dashboard which keeping the URL the same. There is a higher risk of clashing with other servers (e.g. if the user decides to name one of their Jupyter servers similarly).

Using e.g. ‘{urlname}-{date}-{time}’ will mean older dashboard servers ‘expire’ when replaced, which may be important to your use case. If using DockerSpawner, it is easier to match urlname-date-time against the commit of the docker image used to create the dashboard server.

Presentation Types

By default, all supported presentation frameworks will be available for new dashboards. Voilà (for user-friendly display of Jupyter notebooks), Streamlit, and Plotly Dash are the supported frameworks for dashboards.

To change the available set - for example, to remove streamlit and plotlydash as a possible selection for your users on the New Dashboard page, add the following to your jupyterhub_config.py:

c.CDSDashboardsConfig.presentation_types = ['voila']

Or

c.CDSDashboardsConfig.presentation_types = ['streamlit', 'plotlydash']

to allow streamlit and plotlydash, but not voila.

The default is to allow all built-in types:

c.CDSDashboardsConfig.presentation_types = ['voila', 'streamlit', 'plotlydash', 'bokeh', 'rshiny']

Default User Access to Dashboards

Control whether ‘All Users’ or ‘Selected Users’ is selected by default on the ‘New Dashboard’ page.

By default, ‘All Users’ will be selected.

To change this, in your jupyterhub_config.py file:

c.CDSDashboardsConfig.default_allow_all = False

Now the ‘New Dashboard’ page will have ‘Selected Users’ highlighted by default. If the dashboard creator does not change this, and does not specify any user names in the list, then no-one apart from themselves will have access to the dashboard.

File Source

If you don’t want users to be able to enter a git repo as a source for dashboard files, add the following to your jupyterhub_config.py file:

c.CDSDashboardsConfig.show_source_git = False

This will remove the git repo selection in the new/edit dashboard page, forcing all dashboards to be based on files from the Jupyter Tree.

The default value is true.

Conda Environments

To allow users to select a Conda environment in which the dashboard should run, you can provide a list of Conda env names in your jupyterhub_config.py file:

c.CDSDashboardsConfig.conda_envs = ['env1', 'env2', 'myenv', 'anotherenv']

This will add a dropdown to the new/edit dashboard page showing these selections. The singleuser server (i.e. jhsingle-native-proxy) will actively attempt to switch to the named conda env.

For the conda env activation to work, conda must be available on the path. Locating the named Conda env is done by iterating through the list of envs supplied e.g. by conda env list and matching by the name of the right-most folder, returning whichever Conda env path it matches first.

You may provide the empty string as one of the conda_envs (['', 'env1', 'env2]). This will display as a ‘Default / None’ option. This option will be equivalent to the default behavior which runs the dashboard in whichever ‘singleuser server’ environment it finds itself in (which may or may not be a Conda env at all). (In cdsdashboards v0.4.3 and earlier there was always a ‘Default / None’ option.)

It may be possible for env names to be duplicated (but within different prefix paths), in which case only the first match can ever be activated.

You may use a full path to a Conda env instead of just the name. This may be necessary in some configurations, especially if your Conda envs are defined with a prefix instead of named in a central location.

It is now also possible to provide a callable to conda_envs that returns a list whenever called. This allows you to change the contents dynamically, e.g. pulling the list of conda envs from an API.

c.CDSDashboardsConfig.allow_custom_conda_env = True

This will allow the dashboard creator to type any arbitrary Conda env name (including a full path if desired). If c.CDSDashboardsConfig.conda_envs is also set, these options will be available as suggestions in a list (depending on browser support).

If you have trouble making your Conda envs available to dashboards, please get in touch since more work may be required to cater for relatively common but non-standard Conda installations.

Note that Jupyter notebooks (ipynb files) may already contain the details of the Conda env in which they were created - since the different Conda ‘kernels’ are already available to Jupyter if registered using ipykernel. Therefore, Voilà may already be capable of switching to the desired Conda env (kernel) when it runs the notebook, and thus you may not need to specify Conda envs through c.CDSDashboardsConfig.conda_envs at all in order for everything to work if Voilà is the only relevant dashboard framework type.

See also Conda Kernels or Packages not found.

Allow or Block Users from Spawning/Dashboards

The settings c.CDSDashboardsConfig.spawn_allow_group and c.CDSDashboardsConfig.spawn_block_group can be used to restrict which users can start Jupyter servers or create their own dashboards by adding users to a JupyterHub Group. This is useful if you have non-technical users in JupyterHub who want to use others’ dashboards, but who should not be allowed to create their own.

Please see Restrict which Users can Spawn Servers and Dashboards.

User Info API

The experimental API for User Info brings three relevant settings to jupyterhub_config.

The setting c.CDSDashboardsConfig.include_auth_state (default False) causes the User Info API to include auth_state about the current user. Note this can contain sensitive information such as credentials, e.g. GitHub tokens if you are using GitHub as a login authenticator.

In addition, c.CDSDashboardsConfig.include_servers and c.CDSDashboardsConfig.include_servers_state (both default False) can add further information about the user’s servers and their state.

Spawner User Options Form

Your spawner may be configured to (usually) present options to the user before starting their Jupyter server, for example to specify memory size or a Docker image to use. When dashboard servers are started, by default they just attempt to spawn using the default options for the spawner.

If you want the dashboard creator to be able to choose these spawner options, set in your jupyterhub_config:

c.CDSDashboardsConfig.spawn_default_options = False

Doing this will ensure the dashboard creator can choose these options when they access the dashboard (and in the future if it is stopped and needs restarting). However, if the dashboard server is stopped or deleted, then other users will not be able to access the dashboard until the creator starts it again (and chooses spawner options for it).

Jupyter Start Path Regex

Restrict dashboard creators to entering start paths that match a specified regular expression (applies only to dashboards from a Jupyter Tree, not from Git Repo source).

Example: c.CDSDashboardsConfig.jupyter_startpath_regex = "^shared/"

This can be used to ensure dashboards must always be created from a particular folder (‘shared’ in this case). This functionality can be useful when combined with spawn_as_viewer, below.

Default value is a blank string, meaning no regex match is required.

Spawn As Viewer

Default behavior (spawn_as_viewer = False) runs each dashboard under the user who created it, and all viewers access the dashboard server directly, as hosted by the creator.

If you set c.CDSDashboardsConfig.spawn_as_viewer = True in the jupyterhub_config, the behavior will be different: each time a viewer tries to access the dashboard (through the Dashboards page in JupyterHub), a copy of the dashboard will be created in the name of the viewer, and that will be run if it doesn’t already exist. So each viewer can only access the version of the dashboard being run as themselves. These copies are not normally listed as dashboards in their own right (in the Dashboards page) but may appear in the Servers list.

Of course, running multiple copies of the dashboard may use up more resources (and have a slower startup time for a new viewer) compared to just running one copy centrally in the name of the creator. However, some setups find this approach to be more secure or predictable for resource allocation.