Picking or building a Docker image

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

Picking an existing Docker image

When selecting a Docker image for your JupyterHub setup you may choose any of the existing Jupyter docker stacks. It's important to ensure that the version of JupyterHub in the chosen image matches with your current version, which can be verified in the plugin settings. We've created the xnat/datascience-notebook image which builds upon the jupyter/datascience-notebook image by including additional XNAT related Python packages. There is also an xnat/tensorflow-notebook available for use.

Building Docker Images for JupyterHub

To build your own JupyterHub compatible Docker image, we recommend consulting the JupyterHub documentation as well as the Jupyter Docker Stacks documentation.

When building your image, we suggest including the following packages:

CODE

xnat==0.4.3
pyxnat>=1.4
pydicom>=2.3.0
jupyterlab-git>=0.41.0

XNATpy version 0.4.3 introduced support for the XNAT JupyterHub integration. The pyxnat package is serves as an additional Python client for XNAT. The pydicom package offers functionality for interacting with DICOM data in Python. Additionally, the jupyterlab-git extension enables Git integration within JupyterLab.

Here is an example Dockerfile which could be use to build a new Jupyter environment using the above requirements.txt file.

CODE

FROM jupyter/datascience-notebook:hub-3.0.0

COPY --chown=${NB_UID}:${NB_GID} requirements.txt /tmp/

RUN python3 -m pip install --requirement /tmp/requirements.txt && \
    fix-permissions "${CONDA_DIR}" && \
    fix-permissions "/home/${NB_USER}" && \
    rm /tmp/requirements.txt \

Enabling Docker Images for JupyterHub

To enable your Docker image for JupyterHub in XNAT, you need to ensure that the image is pulled to your Docker swarm nodes. This step ensures that the image is available for use when users request a Jupyter server.

To pull a Docker image, you can use the following command as an example:

docker image pull xnat/datascience-notebook:latest

Once the image is successfully pulled, you can proceed with enabling it in XNAT by setting up a new Jupyter environment. User's should now be allowed to launch Jupyter servers which use the specified image.

MATLAB Integration for Jupyter

The MATLAB Integration for Jupyter allows users to directly access MATALB within Jupyter. It enables running MATLAB code within Jupyter notebooks and also provides the option to open a browser-based version of MATLAB.

To utilize the capabilities of MATLAB in your JupyterHub deployment, follow the instructions provided by MathWorks for building a Docker image specifically tailored for MATLAB integration with Jupyter.

GPU Accelerated Notebooks

Jupyter Docker Stacks provides a variety of community-maintained Docker images designed for GPU-accelerated notebooks. The gpu-jupyter image, built upon NVIDIA's CUDA Docker image, has been successfully utilized in conjunction with the JupyterHub integration, enabling GPU computations within Jupyter notebooks.

Notebook Image Sizes

The Jupyter Docker images are known to have larger sizes, typically ranging from 4GB to 15GB+. As a result, it may be necessary to allocate additional storage space for Docker images. To optimize the launch time and enhance the user experience, it is recommended to manually pull the images to the swarm nodes supporting JupyterHub, rather than relying on automatic pulling. This approach ensures faster startup of Jupyter servers and improves overall performance.