Use a custom hub image¶
Community hubs use an image we curate as the default. This can be replaced with your own custom image fairly easily. However, custom images should be maintained by the hub admins, and we won’t be able to help much with things in it.
On top of whatever you are using, your image should match the following requirements:
jupyterhubpackage is installed in such a way that the command
jupyterhub-singleuserworks when executed with the image. 99% of the time, this just means you need to install the
Everything should be able to run as a non-root user, most likely with a uid 1000.
There are a few options to help make this easier.
Use repo2docker to build your image.
Use a pangeo curated docker image. They have an ‘onbuild’ variant of their images that lets you easily customize them.
Use a jupyter curated docker image.
Nothing will be installed on top of this by us, so you really have full control of what goes in your environment.
Which image registry to use?¶
While you can push your image to dockerhub, it now has pretty strict usage limits. This could cause disruptions in your hub if a new image can not be pulled due to these rate limits. We recommend the following image repositories:
quay.io. Owned by RedHat / IBM. Easiest to get started in, and recommended as the default
Google Artifact Registry, if you already have infrastructure running on Google Cloud.
AWS Public Container Registry if you already have infrastructure running on AWS.
GitHub container registry. It integrates better with GitHub, but doesn’t have a clear policy on rate limits yet.
Configuring your hub to use the custom image¶
The hub config under
config/hubs can contain arbitry
zero to jupyterhub on kubernetes
config, so we can use that to set the image name & tag. Here is some example config, with only
the useful bits.
- name: custom-image-hub ... config: basehub: jupyterhub: singleuser: image: name: pangeo/pangeo-notebook tag: 2020.12.08
This can be any image name & tag.
Whenever you push a new image, you’ll have to make a PR that updates the tag here. Only on merge will the hub get the new image.
Split up an image for use with r2d-action¶
Sometimes we have user images defined in a repo, and we want to extract it to a standalone repo so it can be used with the repo2docker action. But we want to retain full history of the image still, so we can look back and see why things are the way they are, as well as credit the people who contributed over time. This page documents the git-fu required to make this happen.
Clone the base repository you are extracting the image from. We will be performing destructive operations on this clone, so it has to be a fresh clone.
git clone <base-repo-url> <hub-image> --origin source
We name the directory
<hub-image>as that would be the name of the repo with just the user image. We ask git to name the remote it creates be called
source, as we will create a new GitHub repo later that will be
git-filter-repoto remove everything from the repo except the image directory.
git filter-repo --subdirectory-filter <path-to-image-directory> --force
The repo root directory now contains the contents of
<path-to-image-directory>, as well as full git history for any commits that touched it! This way, we do not lose history or attribution.
Create a user image repository in GitHub based off this template. The template makes it much easier to setup repo2docker-action on it.
Add the new user image repo as a remote you can push commits to / pull commits from. This will be the primary location of this repo now, so let’s call it
git remote add origin firstname.lastname@example.org:<your-org-or-user-name>/<your-repo-name>.git
Fetch the new repo and check out the
mainbranch, as that is the final destination for our image contents.
git fetch origin git checkout main
environment.ymlfile from the repo - it is present as an example only, and we have our own we are bringing.
git rm environment.yml git commit -m 'Remove unused environment.yml file'
Merge the branch we prepared earlier with just our image contents into this
mainbranch, while telling git to not freak out about them being from different repos initially.
git merge staging --allow-unrelated-histories -m 'Bringing in image directory from deployment repo' git push origin main
In this case,
stagingwas the name of the branch in the source repo, and
mainis the name of the main branch in the new user image repo.
Now follow the instructions in the README of your new repo to complete setting up the repo2docker action as well as using this on your hub!