Skip to main content
Skip table of contents

Plugin Settings

Site-wide admin privileges are required to access this functionality.


To access the JupyterHub plugin settings, follow these steps:

  1. Navigate to Administer → Plugin Settings.

  2. Locate the JupyterHub tab group within your plugin settings.

  3. Click on the Setup tab to access the JupyterHub Setup panel.

Within the JupyterHub Setup panel, you can:

  • Select the Edit action to view the JupyterHub Setup dialog, where you can configure preferences for the plugin.

The JupyterHub setup dialog offers detailed descriptions for each setting. Below are additional insights and comments for some key settings. Feel free to tailor these preferences to meet your specific requirements and configurations.

Preference

Value Examples

Comments

JupyterHub Host URL

http://localhost

http://localhost:8081

https://xnat.myorg.com

https://your.xnat.org

The JupyterHub Host URL is used by XNAT to construct links to a user's Jupyter notebook server. This is typically the same as your XNAT site URL but could be different depending on your XNAT deployment, how you have configured JupyterHub, and how you have configured your reverse proxy.

Include the protocol (http or https), hostname, and port number (if necessary).

Exclude any trailing /jupyterhub path. JupyterHub will provide the path to the user's notebook server.

JupyterHub API URL

http://172.17.0.1/jupyterhub/hub/api 

The URL for the JupyterHub API. Used by XNAT to communicate with JupyterHub.

This is the default. Works for linux test environments.


http://host.docker.internal/jupyterhub/hub/api

Used for running locally on a Mac.


https://your.xnat.org/jupyterhub/hub/api

Used when your XNAT is web accessible

JupyterHub Token

super-secret-token

XNAT is an externally managed JupyterHub Service. This XNAT service has the privileges needed to start and stop Jupyter servers for XNAT users. This API token will be provided by XNAT when it needs to communicate with JupyterHub. You need to generate this token and also supply it to JupyterHub as an environment variable during the deployment process.

Start Timeout

180

600

This setting defines the timeout period, in seconds, before XNAT considers a user's Jupyter server startup as failed. If the startup process exceeds this duration, XNAT assumes that the server initialization was unsuccessful. Depending on your hardware and Docker Swarm setup, you may need to adjust this timeout accordingly. Although our tests indicate that start times are typically under 60 seconds, individual start times may vary and could potentially be longer. To ensure successful server startup, it may be necessary to increase the timeout duration. Customize this setting based on your specific environment and requirements to allow sufficient time for server initialization.

Inactivity Timeout

60

0

This setting allows for the automatic shutdown of idle Jupyter servers after a specified period of inactivity, measured in minutes. Jupyter servers that remain unused for the defined duration will be terminated. Please note that the activity times recorded by JupyterHub are approximate, typically accurate within a few minutes. To prevent any automatic shutdown of inactive servers, set the value to 0.

Max Server Lifetime

48

0

This setting determines the timeout period, in hours, before a Jupyter server is automatically shut down, regardless of activity. If set to 0, no timeout will be enforced, allowing long-running servers to remain active indefinitely. By specifying a non-zero value, you can ensure that Jupyter servers are automatically terminated after a certain period of inactivity, freeing up resources and promoting efficient server allocation. Adjust this setting according to your specific requirements.

Max Servers Per User

1

The maximum number of servers an authorized user can have running at once on JupyterHub. At least one server per user is required.

Workspace Path

/data/xnat/workspaces

This directory serves as a storage location for user's notebooks and other data, allowing for persistence of user data between sessions. It ensures that users can access their notebooks and retain any additional data they have created or modified during their interactions with Jupyter. By specifying a workspace path, user data can be readily available for future sessions.

Path Translation XNAT Archive Prefix

/data/xnat/archive

See the Deployment page for more details on path translation. If using Docker, this is where the archive has been mounted into the XNAT container.

Path Translation Docker Archive Prefix

/home/andy/xnat-docker-compose/xnat-data/archive

See the Deployment page for more details on path translation. If using Docker, this is where the archive lives on the Docker host.

Path Translation User Workspace Prefix

/data/xnat/workspaces

See the Deployment page for more details on path translation. If using Docker, this is where the user workspaces directory has been mounted into the XNAT container.

Path Translation Docker User Workspace Prefix

/home/andy/xnat-docker-compose/xnat-data/workspaces

See the Deployment page for more details on path translation. If using Docker, this is where the user workspaces directory lives on the Docker host.

Core plugin settings can be set using environment variables in your XNAT deployment. The below table lists each preference alongside its corresponding environment variable:

Preference

Env Variable

JupyterHub Host URL

JH_XNAT_JUPYTERHUB_HOST_URL

JupyterHub API URL

JH_XNAT_JUPYTERHUB_API_URL

JupyterHub Token

JH_XNAT_SERVICE_TOKEN

Workspace Path

JH_XNAT_WORKSPACE_PATH

Path Translation XNAT Archive Prefix

JH_XNAT_PT_ARCHIVE_PREFIX

Path Translation Docker Archive Prefix

JH_XNAT_PT_ARCHIVE_DOCKER_PREFIX

Path Translation User Workspace Prefix

JH_XNAT_PT_WORKSPACE_PREFIX

Path Translation Docker User Workspace Prefix

JH_XNAT_PT_WORKSPACE_DOCKER_PREFIX


References

[1] JupyterHub Services

[2] Path Translation

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.