Getting Started
JupyterHub is an open source application for serving Jupyter notebooks for multiple users. It is designed for classrooms, corporate data science groups and scientific research groups. It is a multi-user Hub that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server.
Four subsystems make up JupyterHub:
a Hub (tornado process) that is the heart of JupyterHub
a configurable http proxy (node-http-proxy) that receives the requests from the client’s browser
multiple single-user Jupyter notebook servers (Python/IPython/tornado) that are monitored by Spawners
an authentication class that manages how users can access the system
The key pluggable components are the authenticator, the spawner, and the config.py configuration file for the Hub.
To serve single-user Jupyter notebook servers for XNAT users we've created:
- An authenticator for authenticating users with an XNAT
- A spawner for running the single-user Jupyter notebook servers on a Docker Swarm
- A config.py configuration primarily for mounting XNAT data into the single-user Jupyter containers
- An XNAT plugin which interacts with the Hub's REST API
To make life easier, we've built a Docker image for JupyterHub with the XNAT authenticator, swarm spawner, and config.py configuration file included.
Adding Jupyter to your XNAT requires running JupyterHub on a Docker swarm and deploying the JupyterHub plugin to your XNAT.
There are two approaches for setting up JupyterHub and the JupyterHub plugin:
- Using the xnat-docker-compose repository. This is great if you want to evaluate this feature on a clean XNAT on a single system.
- Set up JupyterHub alongside an existing XNAT.
Using the xnat-docker-compose repository
Head over to the xnat-docker-compose repository on GitHub and checkout the features/jupyterhub branch for the latest instructions. By utilizing the xnat-docker-compose repository, you can easily evaluate the JupyterHub integration on a clean XNAT system.
Deploying to an existing XNAT
Before installing, please consult the XNAT JupyterHub Version Compatibility Matrix to be sure this plugin will work on your system
See the Deployment page for details on deploying JupyterHub to an existing XNAT. This approach is recommended if you have automated or puppetized XNAT deployment and you would like to deploy JupyterHub in your existing environment. This can also be used to test against snapshots/backups of existing XNATs.
Administration
See the Administration documentation for a technical overview, deployment instructions, and plugin management details.
Usage
After setting up JupyterHub and the JupyterHub plugin, head to the Usage guide for details on using Jupyter with XNAT.
Sample Notebooks
Checkout a few sample notebooks on GitHub. The notebooks provide an overview of the XNAT/Jupyter integrated environment.
References
[1] JupyterHub