Administrator Guide for configuring Notebooks Hub

Default Environments on fresh install

On API startup, Notebooks Hub seeds a standard Environments catalog for the first configured hub admin in HUB_ADMIN_EMAILS. This registers the environments in MongoDB, writes Lua modulefiles, and grants the default organization #member viewer access so the Environments tab is populated for all org users.

On Helm, the bundled catalog matches the default Quick Launch launchers:

python-data-science/0.1.8
R/0.1.1

Both are clusterOnly. Compose skips them because it has no conda installer for them, and an Environment whose prefix does not exist breaks launches (for example, RStudio restarts in a loop when R/0.1.1 is selected).

Compose seeds default-env/0.1.0 instead (composeOnly). Helm installs skip that entry because there is no Helm conda installer for it. On Compose, run launch-notebooks-hub.sh -m conda to install its conda prefix.

Setting	Purpose
`SEED_DEFAULT_ENVIRONMENTS=true`	Enable automatic seeding (default)
`SEED_DEFAULT_ENVIRONMENTS=false`	Disable automatic seeding
`DEFAULT_ENVIRONMENTS_PATH`	Optional path to a custom JSON environment list

Bundled defaults live in packages/API/config/default-environments.json. Seeding is idempotent: restarting the API does not create duplicate name/version/owner rows. Only environments owned by the hub admin are reused, matching the owner email without regard to case; the seed does not adopt another user’s private module. Helm false values are honored (seedDefaultEnvironments: false).

Lua modulefiles are written under the hub-admin owner path used by JupyterHub. The seed does not write /opt/modules/shared/modulefiles/... so Helm conda installer jobs can still use that path as their “already installed” sentinel. Conda package installation remains those installers.

Environment seed runs before Quick Launch seed so launcher templates can resolve module IDs.

Default Quick Launch templates on fresh install

On API startup, Notebooks Hub can automatically seed default Quick Launch templates (JupyterLab, RStudio, and VSCode) for the first configured hub admin in HUB_ADMIN_EMAILS.

Setting	Purpose
`SEED_DEFAULT_QUICKLAUNCH=true`	Enable automatic seeding (default)
`SEED_DEFAULT_QUICKLAUNCH=false`	Disable automatic seeding
`DEFAULT_QUICKLAUNCH_TEMPLATES_PATH`	Optional path to a custom JSON template list
`DEFAULT_QUICKLAUNCH_HARDWARE`	Optional hardware override for seeded templates

Bundled defaults live in packages/API/config/default-quicklaunch-templates.json and omit hardware so each deployment uses DEFAULT_QUICKLAUNCH_HARDWARE, API_DEFAULT_HARDWARE_OPTION, or the first entry in HARDWARE_OPTION_NAMES. Seeding is idempotent: restarting the API does not create duplicate templates.

Adding Launchers and Examples

To populate Launcher and Examples tab, the Administator needs to make POST API calls to /templates

Below are examples of the JSON body for each type of template.

Launchers

{
    "name": "JupyterLab",
    "description": "JupyterLab Launcher",
    "type": "quicklaunch",
    "applicationType": "jupyterlab",
    "modules": [
        "python-data-science/0.1.8"
    ],
    "hardware": "cpuMedium",
    "creator": "admin@org.com",
    "public": false
}

{
    "name": "RStudio",
    "description": "RStudio Launcher",
    "type": "quicklaunch",
    "applicationType": "rstudio",
    "modules": [
        "R/0.1.1"
    ],
    "hardware": "cpuMedium",
    "creator": "admin@org.com",
    "public": false
}

{
	"name": "VSCode",
	"type": "quicklaunch",
	"description": "VSCode Launcher",
	"applicationType": "vscode",
	"modules": [
        "python-data-science/0.1.8"
    ],
	"hardware": "cpuMedium",
	"creator": "admin@org.com",
	"public": false
}

Examples

{{
    "name": "Stable Diffusion",
    "description": "Stable Diffusion is a deep learning, text-to-image model used to generate detailed images conditioned on text descriptions. This dashboard provides simple UI for Stable Diffusion",
    "type": "featured",
    "applicationType": "voila",
    "modules": ["python-data-science/0.1.8"],
    "hardware": "dedicatedGpuLarge",
    "creator": "admin@org.com",
    "public": false,
    "filePath": "shared/notebooks/stable_diffusion/StableDiffusion.ipynb"
}