Plugin Settings
Site-wide admin privileges are required to access this functionality.
To access the JupyterHub plugin settings, follow these steps:
Navigate to Administer → Plugin Settings.
Locate the JupyterHub tab group within your plugin settings.
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 or Kubernetes, this is where the archive has been mounted into the XNAT container. |
Path Translation Server Archive Prefix | /home/andy/xnat-docker-compose/xnat-data/archive | See the Deployment page for more details on path translation. If using Docker or Kubernetes, this is where the archive lives on the Docker host. If using a PVC, this could be a relative path like |
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. If using Kubernetes, this is managed in the helm chart and not in the plugin settings. |
Path Translation Server 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. If using Kubernetes, this is managed in the helm chart and not in the plugin settings. |
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 |
|
JupyterHub API URL |
|
JupyterHub Token |
|
Workspace Path |
|
Path Translation XNAT Archive Prefix |
|
Path Translation Server Archive Prefix |
|
Path Translation User Workspace Prefix |
|
Path Translation Server User Workspace Prefix |
|
XNAT Archive PVC* |
|
*For K8s deployments only. This is not available in the UI, and is set in the helm chart.
References
[2] Path Translation