Build a Docker image with repo2docker
#
Note
Docker images to be used this way must have the jupyterhub
package of a
matching version with the Helm chart. This documentation is for Helm chart
4.0.0-beta.4.git.136.h70e33c1, and it uses JupyterHub version 5.2.1.
If you can’t find a pre-existing image that suits your needs, you can create your own image. An easy way to do this is with the package repo2docker.
repo2docker lets you quickly convert a Git repository into a Docker image that can be used as a base for your JupyterHub instance. Anything inside the Git repository will exist in a user’s environment when they access your JupyterHub.
repo2docker
will attempt to figure out what should be pre-installed, and you
can help it out by adding various configuration files to the repository. For
example if you include a requirements.txt
file in the root level of the
repository, repo2docker
will pip install
the specified packages into the
Docker image to be built.
See repo2docker’s documentation for more details.
Below we’ll cover how to use repo2docker
to generate a Docker image and how
to configure JupyterHub to build off of this image:
Download and start Docker.
You can do this by downloading and installing Docker. Once you’ve started Docker, it will show up as a tiny background application.
Install repo2docker using
pip
:pip install jupyter-repo2docker
If that command fails due to insufficient permissions, try it with the command option,
user
:pip install --user jupyter-repo2docker
Create (or find) a Git repository you want to use.
This repo should have all materials that you want your users to be able to use. You may want to include a pip
requirements.txt
file to list packages, one per file line, to install such as when usingpip install
. Specify the versions explicitly so the image is fully reproducible. An examplerequirements.txt
follows:jupyterhub==0.9.4 numpy==1.14.3 scipy==1.1.0 matplotlib==2.2.2
Get credentials for a docker repository.
The image you will build for your JupyterHub must be made available by being published to some container registry. You could for example use quay.io or Docker Hub.
In the next step, you need an image reference for you and others to find your image with.
An image reference on Docker Hub:
<dockerhub-username>/<image-name>:<image-tag>
An image reference on quay.io:
quay.io/<quay-username>/<image-name>:<image-tag>
Your image name can be anything memorable.
We recommend using the first 7 characters of the SHA in the Git commit as this improves reproducibility. You can get these in various ways, one of which is like this:
git ls-remote <your-git-repository> | grep HEAD | awk '{ print $1 }' | cut -c -7
Use repo2docker to build a Docker image.
jupyter-repo2docker \ --no-run \ --user-name=jovyan \ --image=<your-image-reference> \ <a-git-repository-url>
This tells
repo2docker
to fetch the default branch of the Git repository, and uses heuristics to build a Docker image of it.Push the newly-built Docker image to your repository.
docker push <your-image-reference>
Edit the JupyterHub configuration to build from this image. Edit
config.yaml
file to include these lines in it:singleuser: image: name: <your-image-reference> tag: "<tag>"
If the tag is the first several characters of the SHA and they happen to all be numerical, you must use quotes around the tag as above in order for the YAML to be parsed correctly.
Tell helm to update JupyterHub to use this configuration.
Use the standard method to apply the changes to the config.
Restart your server if you are already logged in.
If you already have a running JupyterHub server, you’ll need to restart it from the JupyterHub control panel. Within JupyterLab look at the meny named “Hub”. New users won’t have to do this.
Note
The contents of your GitHub repository might not show up if you have enabled persistent storage. Disable persistent storage if you want the Git repository contents to show up.
Enjoy your new computing environment!
You should now have a live computing environment built off of the Docker image we’ve created.