hub-user-image-template

This is a template repository for creating dedicated single-user server images for UC Berkeley Jupyterhubs.

Overall workflow

The basic workflow for creating a new hub user image is as follows:

1. Create a new repository using this one as a template. Be sure to set the owner as berkeley-dsep-infra.

2. In the new repo, set the appropriate values in the Actions repository variables for HUB and IMAGE.

3. Give the new repo access to the berkeley-dsep-infra organization-level secrets: GAR_SECRET_KEY and DATAHUB_CREATE_PR.

4. Fork that repository to create your image repository.

5. Configure your Hub to use this new image by modifying that deployment's hubploy.yaml and add the parent repo's git information to repos.txt

6. Customize the image by editing repo2docker configuration files in your fork of the image repository, and then open a pull request to merge these changes to the main branch of the parent repo in the berkeley-dsep-infra organization.

These steps are just a summary, and much more detailed instructions are located here.

In addition, we also provide a template for a simplified README.md here.

Modifying the new image

The process to modify and push an image to the Google Artifact Registry via the CI/CD pipeline is located in the contribution guide

Moving an existing image into the berkeley-dsep-infra organization

If you have an existing image repository, and would like to bring it in to the berkeley-dsep-infra organization and retain the git history, please refer to our documentation ➡️ https://docs.datahub.berkeley.edu/admins/howto/transition-image.html

Our documentation is based on helpful guide put together by 2i2c ➡️ https://infrastructure.2i2c.org/howto/update-env/#split-up-an-image-for-use-with-the-repo2docker-action

About this template repository

This template repository uses the jupyterhub/repo2docker-action to build a Docker image using the contents of this repo, and pushes it to our Google Artifact Registry when a pull request is merged to main.

The environment

The repo provides a default environment.yml conda configuration file for repo2docker to use to define and build a single-user server image. This file is used to define the python packages that will be installed during the image build process, either via conda or pip.

Note: A complete list of configuration files that can be added to the repository and used by repo2docker to build the Docker image can be found in the repo2docker documentation.

Making changes to a single user server image

Once you've created the new image repo from this template, please refer to the contribution instructions located in the repo for detailed instructions.

The GitHub Action workflows

This template repository provides GitHub Action workflows that can build and push the image to Google Artifact Repository when configured, and push a commit to the datahub repository that modifies hubploy.yaml for any hubs using this image with the new SHA tag.

1. Build and test container image ➡️ test.yaml

This workflow is triggered when a pull request is opened against the default branch (main). During PR builds, the image is only built and not pushed to the Google Artifact Registry.

Please note that the image will not be built for documentation changes (markdown files or any graphic images in the images/ subdirectory).

2. YAML linting :arrow:_right: yaml-lint.yaml

This workflow is triggered when a pull request is opened against the default branch (main). It uses yamllint to check all yaml files in the repo for correctness.

3. Temporarily disabled: Test this PR on Binder Badge ➡️ binder.yaml

Since our images are typically large and take > 10m to build, this means that Binderhub builds will currently time out.

4. Build, test and push container image ➡️ build-push-open-pr.yaml

After a PR is merged to main, this workflow builds the image again, pushes it to the Google Artifact Registry and then creates a commit that updates the image tag for any hubs that use this image. That commit is then pushed to the Datahub repo, and you will then need to manually create a pull requests to merge and deploy the new image.