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.