Skip to main content
Skip table of contents

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 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 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 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:

  1. Using the xnat-docker-compose repository. This is great if you want to evaluate this feature on a clean XNAT on a single system.
  2. 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.


See the Administration documentation for a technical overview, deployment instructions, and plugin management details.


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.


[1] JupyterHub

[2] JupyterHub Documentation

[3] xnat-docker-compose/features/jupyterhub @ GitHub

[4] xnat-jupyter-notebooks @ GitHub

JavaScript errors detected

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

If this problem persists, please contact our support.