diff --git a/docs/howto/operate/add-hub.md b/docs/howto/operate/add-hub.md index 66d0465fa0..5fc73ea544 100644 --- a/docs/howto/operate/add-hub.md +++ b/docs/howto/operate/add-hub.md @@ -1,8 +1,85 @@ # Add a new hub -Adding a new hub requires that we do three things: +## Step 0: Open a GitHub issue to track hub creation -1. [Create a new GitHub issue for the hub](https://github.com/2i2c-org/pilot-hubs/issues/new). -2. Create the hub via appending a new hub entry in the appropriate cluster file under - `config/hubs` file (see [](../../topic/config.md) for more information). -3. Start following [team process](team-process) around operating the hubs. +In order to track progress on deploying the new hub, [open a GitHub issue in the +`pilot-hubs/` repository](https://github.com/2i2c-org/pilot-hubs/issues/new/choose). +Make sure to choose the `new-hub` issue template. + +## Step 1: Decide where the hub will live + +Hubs need to exist on a kubernetes cluster, so we will need to +decide which cluster it should live in. + +1. For standalone hubs where we are being paid or the client has cloud + credits, we will need to create a cluster specifically for this hub + before deploying it. As a general rule, we will create one cluster per + billing account. +2. For hubs we are running for free, they will go into the `pilot-hubs` + cluster. +3. Hubs run with the support of [cloudbank](https://www.cloudbank.org/), + will go in the `cloudbank` cluster. + +Each cluster has configuration + list of hubs it supports under +`config/hubs/.cluster.yaml`. + +## Step 2: Decide the template used for the hub + +Hub templates map on to different major use-cases that we aim to enable. +Ask the hub user(s) about their needs and expected usage, and use their answer to select a [hub template](../../topic/hub-templates.md). +to be used. + +## Step 3: Decide the authentication provider to be used + +In consultation with the users, decide +[which authentication provider](https://pilot.2i2c.org/en/latest/admin/configuration/login.html#authentication) +the hub should use. + + +```{note} +While this can be changed later, it's a messy +process - so we should try to get this right the first time +``` + +## Step 4: Decide the user image for the hub + +The default user image is present in this repository (`images/user`), +and is geared towards simple datascience classes - with both R and +Python. Determine if this is acceptable - if not, you need to +make a [custom image](../configure/update-env.md) for them. + +## Step 5: Add hub config + +Add an entry for the hub in `config/hubs/.cluster.yaml` for this hub. +The following docs might be helpful: + +1. [Configuration Structure](../../topic/config.md) +2. [JSON Schema for `.cluster.yaml` file](https://github.com/2i2c-org/pilot-hubs/blob/master/config/hubs/schema.yaml) +3. [Zero to JupyterHub on k8s Docs](https://zero-to-jupyterhub.readthedocs.io/en/latest/), since ultimately + that is what we are configuring. + +## Step 6: Deploy manually and test + +[Deploy the hub manually](./manual-deploy.md) and test to make sure it works +the way you would like it to. This might take some iteration and multiple +tries. Specifically test that at least the following work ok: + +1. Authentication provider +2. Admin user access +3. User image in use (check the `JUPYTER_IMAGE` environment variable in a spawned server) +4. Default user interface when the user logs in (lab, notebook, rstudio, retrolab, etc) +5. Home page display configuration +6. (Optionally) `dask-gateway` functionality +7. (Optionally) Access to any cloud resources (like storage buckets, etc) + granted to the hub users + +## Step 7: Make a PR + +Make a PR with your changes, referencing the issue for creation of the hub. Seek +review from someone else, and get this merged! + +Getting this merged will mark the hub as being deployed. + +Finally, notify the users of the hub that it is now deployed, and ask that they test it out to make sure it works as expected. +If they are happy with the result, then close the issue for deploying the new hub. +Congratulations, you are done! 🎉