diff --git a/docs/admins/howto/index.rst b/docs/admins/howto/index.rst index 36f4cbedb..b8eece414 100644 --- a/docs/admins/howto/index.rst +++ b/docs/admins/howto/index.rst @@ -11,6 +11,7 @@ Common Administrator Tasks core-pool new-hub rebuild-hub-image + new-image new-packages course-config calendar-scaler diff --git a/docs/admins/howto/new-image.rst b/docs/admins/howto/new-image.rst new file mode 100644 index 000000000..fab8375e3 --- /dev/null +++ b/docs/admins/howto/new-image.rst @@ -0,0 +1,96 @@ +.. _howto/new-packages: + +================================ +Creating a new single user image +================================ + +When deploying a new hub, or moving from a shared single user server image, +you might need to create a new image for users. We use +`repo2docker `_ to do this. + +There are two approaches to creating a repo2docker image: +1. Use a repo2docker-style image `template `_ (environment.yaml, etc) +2. Use a `Dockerfile `_ (useful for larger/more complex images) + +Generally, we prefer to use the former approach, unless we need to install +specific packages or utilities outside of python/apt as `root`. If that is +the case, only a `Dockerfile` format will work. + +Of course, as always create a feature branch for your changes, and submit a +PR when done. + +Find a hub to use as a template +=============================== + +Browse through our `deployments/` directory to find a hub that is similar to +the one you are trying to create. This will give you a good starting point. + +Create the :file:`image/` directory for your new hub +==================================================== + +Create a new directory under `deployments/` with the name of your hub. This +directory will contain the files that will be used to create the image. + +Then, copy the contents (and any subdirectories) of the source `image/` +directory in to the new directory. + +Modify :file:`hubploy.yaml` for the hub +======================================= + +In the deployment's :file:`hubploy.yaml` file, add or modify the `name`, `path` and +`base_image` fields to configure the image build and where it's stored in the +Google Artifcat Registry. + +`name` should contain the path to the image in the Google Artifact Registry and the name of the image. +`path` points to the directory containing the image configuration (typically :file::`image/`). +`base_image` is the base Docker image to use for the image build. + +For example, the `hubploy.yaml` for the data100 image looks like this: + + .. code-block:: yaml + images: + images: + - name: us-central1-docker.pkg.dev/ucb-datahub-2018/user-images/data100-user-image + path: image/ + repo2docker: + base_image: docker.io/library/buildpack-deps:jammy + registry: + provider: gcloud + gcloud: + project: ucb-datahub-2018 + service_key: gcr-key.json + + cluster: + provider: gcloud + gcloud: + project: ucb-datahub-2018 + service_key: gke-key.json + cluster: spring-2024 + zone: us-central1 + +Modify the image configuration as necessary +=========================================== + +This step is straightforward: edit/modify/delete/add any files in the `image/` +directory to configure the image as needed. + +Update CI/CD configuration +========================== + +Next, ensure that this image will be built and deployed by updating the +:file:`.circleci/config.yml` file in the root of the repository. Add new steps +under the `jobs/deploy:`, `workflows/test-build-images:` and `workflows/deploy:` +stanzas. + +Submitting a pull request +========================= + +Familiarize yourself with `pull requests `_ and `repo2docker `_ , and create a fork of the `datahub staging branch `_. + +#. Set up your git/dev environment by `following the instructions here `_. +#. Create a new branch for this PR. +#. Test the changes locally using `repo2docker`, then submit a PR to ``staging``. + * To use ``repo2docker``, you have to point it at the correct image directory. For example, to build the data100 image, you would run ``repo2docker deployments/data100/image`` from the base datahub directory. +#. Commit and push your changes to your fork of the datahub repo, and create a new pull request at ``__. +#. Once the PR is merged to staging and the new image is built and pushed to Artifact Registry, you can test it out on :code:`-staging.datahub.berkeley.edu`. +#. Changes are only deployed to prod once the relevant CI job is completed. See ``__ to view CircleCI job statuses.