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.