Plugin Settings
Site-wide admin privileges are required to access this functionality.
To access the JupyterHub plugin setting, navigate to Administer → Plugin Settings.
You will find a JupyterHub tab group in your plugin settings. Select the Setup tab to access the JupyterHub Setup panel.
Select the Edit action to view the JupyterHub Setup dialog which contains configuration preferences for the plugin.
The JupyterHub setup dialog provides descriptions for each setting. Here are more detailed descriptions and comments for some key settings. Customize these preferences according to 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 | This is the default. Works for linux test environments. |
http://host.docker.internal/jupyterhub/hub/api | Used for running 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. |
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. |
References