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.

Source Servers

The following options are currently only used by the DockerSpawner.

DockerSpawner users have extra functionality available whereby the dashboard creator can select a ‘source server’ to clone (docker commit). The dashboard server will be built out of that image, meaning any extra packages installed in the source server will be available. Likewise, if your home folder is built into the container rather than mounted as a volume, the source files will be copied into the new dashboard server.

Unless different servers are likely to have different files or packages installed, it probably won’t make much difference which server is selected as the source anyway - most JupyterHubs will share the user’s home file system across the different servers, so the Dashboard will be able to locate your notebooks and files. Most JupyterHubs maintain a central Docker image that contains all required packages, so users rarely install packages into their own server exclusively.

In your jupyterhub_config.py file:

c.CDSDashboardsConfig.show_source_servers = True
c.CDSDashboardsConfig.require_source_server = True

If show_source_servers is True, the create/edit Dashboard page will allow the dashboard creator to select a source server to clone. If require_source_server is False, there will also be a ‘No Server’ option to maintain the default behavior of starting a new dashboard server based on the usual Jupyter server configuration. If require_source_server is True, there will be no such option and a source server must be selected (your ‘Default Server’ will be available, along with any non-dashboard named servers).

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.

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).

Mailing List for Updates

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