From a33f1d7d326d869cd950fe92cbb3fc0992510952 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Fri, 21 Jul 2023 11:06:41 +0300
Subject: [PATCH 01/13] Copy hub image into a new hub-experimental image and
 configure chartpress to push it on quay

---
 helm-charts/chartpress.yaml                   |  4 +++
 .../images/hub-experimental/Dockerfile        | 25 +++++++++++++++++++
 .../jupyterhub_configurator_config.py         | 15 +++++++++++
 .../images/hub-experimental/requirements.txt  |  1 +
 4 files changed, 45 insertions(+)
 create mode 100644 helm-charts/images/hub-experimental/Dockerfile
 create mode 100644 helm-charts/images/hub-experimental/jupyterhub_configurator_config.py
 create mode 100644 helm-charts/images/hub-experimental/requirements.txt

diff --git a/helm-charts/chartpress.yaml b/helm-charts/chartpress.yaml
index 1dfc4d962c..9aa9a74aee 100644
--- a/helm-charts/chartpress.yaml
+++ b/helm-charts/chartpress.yaml
@@ -4,3 +4,7 @@ charts:
     images:
       hub:
         valuesPath: jupyterhub.hub.image
+  - name: basehub
+    images:
+      hub-experimental:
+        imageName: quay.io/2i2c/experimental-hub
diff --git a/helm-charts/images/hub-experimental/Dockerfile b/helm-charts/images/hub-experimental/Dockerfile
new file mode 100644
index 0000000000..548646c8d9
--- /dev/null
+++ b/helm-charts/images/hub-experimental/Dockerfile
@@ -0,0 +1,25 @@
+# This image tag should match the dependent JupyterHub Helm chart's version as
+# declared in basehub/Chart.yaml.
+#
+# If you make an update to this tag and the JupyterHub Helm chart's version,
+# then first commit those changes.
+# Then, from the `helm-charts` directory where the `chartpress.yaml` is located,
+# perform `chartpress --push` with your quay.io container registry credentials
+# configured to have access to https://quay.io/repository/2i2c/pilot-hub.
+#
+# Note: if on macOs with M1, you need to run chartpress with docker buildx under the hood and specify
+# the architecture to use.
+# `chartpress --push --builder docker-buildx --platform linux/amd64`
+# Ref: https://cloudolife.com/2022/03/05/Infrastructure-as-Code-IaC/Container/Docker/Docker-buildx-support-multiple-architectures-images/
+#
+FROM jupyterhub/k8s-hub:3.0.0-beta.1
+
+COPY requirements.txt /tmp/
+
+RUN pip install -r /tmp/requirements.txt
+
+USER root
+RUN mkdir -p /usr/local/etc/jupyterhub-configurator
+
+COPY jupyterhub_configurator_config.py /usr/local/etc/jupyterhub-configurator/jupyterhub_configurator_config.py
+USER $NB_USER
diff --git a/helm-charts/images/hub-experimental/jupyterhub_configurator_config.py b/helm-charts/images/hub-experimental/jupyterhub_configurator_config.py
new file mode 100644
index 0000000000..67a79a7f0c
--- /dev/null
+++ b/helm-charts/images/hub-experimental/jupyterhub_configurator_config.py
@@ -0,0 +1,15 @@
+import json
+import os
+from glob import glob
+
+CONFIGURATOR_BASE_PATH = "/usr/local/etc/jupyterhub-configurator"
+
+schema_files = sorted(glob(os.path.join(CONFIGURATOR_BASE_PATH, "*.schema.json")))
+
+schemas = {}
+
+for sf in schema_files:
+    with open(sf) as f:
+        schemas[sf] = json.load(f)
+
+c.Configurator.schemas = schemas
diff --git a/helm-charts/images/hub-experimental/requirements.txt b/helm-charts/images/hub-experimental/requirements.txt
new file mode 100644
index 0000000000..4f895cace0
--- /dev/null
+++ b/helm-charts/images/hub-experimental/requirements.txt
@@ -0,0 +1 @@
+git+https://github.com/yuvipanda/jupyterhub-configurator@ed7e3a0df1e3d625d10903ef7d7fd9c2fbb548db

From cc286c584cf64d958e80667202a1f7267246fc58 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Fri, 21 Jul 2023 11:50:26 +0300
Subject: [PATCH 02/13] Bring latest kubespawner in the hub-experimental image

---
 helm-charts/images/hub-experimental/requirements.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/helm-charts/images/hub-experimental/requirements.txt b/helm-charts/images/hub-experimental/requirements.txt
index 4f895cace0..2186d5ee7f 100644
--- a/helm-charts/images/hub-experimental/requirements.txt
+++ b/helm-charts/images/hub-experimental/requirements.txt
@@ -1 +1,3 @@
 git+https://github.com/yuvipanda/jupyterhub-configurator@ed7e3a0df1e3d625d10903ef7d7fd9c2fbb548db
+# Brings on using `unlisted_choice` in profile options per https://github.com/2i2c-org/infrastructure/issues/2146
+git+https://github.com/jupyterhub/kubespawner@def501f1d60b8e5629745acb0bcc45b151b1decc

From 9a54d426b8b42ebb0d280ab6dd9abf15e53d8449 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Fri, 21 Jul 2023 12:04:02 +0300
Subject: [PATCH 03/13] Use hub-experimental image for leap and enable
 unlisted_image_choice for each of the profiles

---
 config/clusters/leap/common.values.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/config/clusters/leap/common.values.yaml b/config/clusters/leap/common.values.yaml
index 896150e453..a5f27d6637 100644
--- a/config/clusters/leap/common.values.yaml
+++ b/config/clusters/leap/common.values.yaml
@@ -37,6 +37,9 @@ basehub:
             name: LEAP
             url: https://leap-stc.github.io
     hub:
+      image:
+        name: quay.io/2i2c/experimental-hub
+        tag: "0.0.1-0.dev.git.6406.hc1091b1c"
       allowNamedServers: true
       config:
         Authenticator:
@@ -189,6 +192,11 @@ basehub:
                     cpu_limit: 16
             image: &profile_list_profile_options_image
               display_name: Image
+              unlisted_choice:
+                enabled: True
+                display_name: "Custom org/image:tag"
+                kubespawner_override:
+                  image: "{value}"
               choices:
                 pangeo_new:
                   display_name: Base Pangeo Notebook ("2023.05.18")
@@ -268,6 +276,11 @@ basehub:
           profile_options:
             image:
               display_name: Image
+              unlisted_choice:
+                enabled: True
+                display_name: "Custom org/image:tag"
+                kubespawner_override:
+                  image: "{value}"
               choices:
                 tensorflow_new:
                   display_name: Pangeo Tensorflow ML Notebook ("2023.05.18")

From b0ac7af9f7b4514980574839d80934b7cda350da Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Fri, 21 Jul 2023 20:00:26 +0300
Subject: [PATCH 04/13] Add regex

---
 config/clusters/leap/common.values.yaml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/config/clusters/leap/common.values.yaml b/config/clusters/leap/common.values.yaml
index a5f27d6637..f187f5f45e 100644
--- a/config/clusters/leap/common.values.yaml
+++ b/config/clusters/leap/common.values.yaml
@@ -194,7 +194,9 @@ basehub:
               display_name: Image
               unlisted_choice:
                 enabled: True
-                display_name: "Custom org/image:tag"
+                display_name: "Custom image"
+                validation_regex: "^.+:.+$"
+                validation_message: "Must be an image location, matching ^.+:.+$"
                 kubespawner_override:
                   image: "{value}"
               choices:
@@ -278,7 +280,9 @@ basehub:
               display_name: Image
               unlisted_choice:
                 enabled: True
-                display_name: "Custom org/image:tag"
+                display_name: "Custom image"
+                validation_regex: "^.+:.+$"
+                validation_message: "Must be an image location, matching ^.+:.+$"
                 kubespawner_override:
                   image: "{value}"
               choices:

From d5592def722d0935b5773242dbf46920153e01c2 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Mon, 24 Jul 2023 14:47:30 +0300
Subject: [PATCH 05/13] Add custom suer profile choice

---
 .../features/custom-user-profile-choice.md    | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 docs/howto/features/custom-user-profile-choice.md

diff --git a/docs/howto/features/custom-user-profile-choice.md b/docs/howto/features/custom-user-profile-choice.md
new file mode 100644
index 0000000000..b0339fc756
--- /dev/null
+++ b/docs/howto/features/custom-user-profile-choice.md
@@ -0,0 +1,34 @@
+# Allow users to setup custom, free-form user profile choices
+
+Sometimes it is useful to allow users to specify their own, free-form choice for an option.
+We can make this possible by enabling and configuring [`KubeSpawner.profile_list.<profile>.profile_options.<option>.unlisted_choice`](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html#kubespawner.KubeSpawner.profile_list).
+
+If enabled, when the user selects “Other” as a choice, a free form input is enabled. An optional regex can be configured that the free form input should match - eg. `^pangeo/.*$`.
+
+Example configuration that allows a custom free-form, user specified image:
+
+```yaml
+jupyterhub:
+   singleuser:
+      profileList:
+        - display_name: "CPU only"
+          description: "Start a container limited to a chosen share of capacity on a node of this type"
+          profile_options:
+            image:
+              display_name: Image
+              unlisted_choice:
+                enabled: True
+                display_name: "Custom image"
+                validation_regex: "^.+:.+$"
+                validation_message: "Must be an image location, matching ^.+:.+$"
+                kubespawner_override:
+                  image: "{value}"
+              choices:
+                pangeo_new:
+                  display_name: Base Pangeo Notebook ("2023.05.18")
+                  default: true
+                  slug: "pangeo_new"
+                  kubespawner_override:
+                    image: "pangeo/pangeo-notebook:2023.05.18"
+                pangeo_old: (...)
+```

From a9cfa1ed9cec28a29f672c11190dde4db58cc552 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Mon, 24 Jul 2023 14:48:47 +0300
Subject: [PATCH 06/13] Rename file for clarity

---
 ...om-user-profile-choice.md => allow-unlisted-profile-choice.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/howto/features/{custom-user-profile-choice.md => allow-unlisted-profile-choice.md} (100%)

diff --git a/docs/howto/features/custom-user-profile-choice.md b/docs/howto/features/allow-unlisted-profile-choice.md
similarity index 100%
rename from docs/howto/features/custom-user-profile-choice.md
rename to docs/howto/features/allow-unlisted-profile-choice.md

From 97d8b7ad71840e4ff2b072b83f59d14780286d9f Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Mon, 24 Jul 2023 16:51:07 +0300
Subject: [PATCH 07/13] Add docs and diagram about hub-experimental image and
 roll out policy

---
 docs/conf.py                          |   1 +
 docs/howto/custom-jupyterhub-image.md | 139 ++++++++++++++++++--------
 docs/requirements.txt                 |   1 +
 3 files changed, 100 insertions(+), 41 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 913daf2c66..d0f45e477b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -15,6 +15,7 @@
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinxcontrib.mermaid",
 ]
 
 intersphinx_mapping = {
diff --git a/docs/howto/custom-jupyterhub-image.md b/docs/howto/custom-jupyterhub-image.md
index 1f6ce703bd..4c2a4ca279 100644
--- a/docs/howto/custom-jupyterhub-image.md
+++ b/docs/howto/custom-jupyterhub-image.md
@@ -1,20 +1,62 @@
 # Modify our custom JupyterHub image
 
-The 2i2c hubs use a custom hub image that is defined in the [helm-charts directory of the infrastructure repository](https://github.com/2i2c-org/infrastructure/tree/HEAD/helm-charts/images/hub).
+The 2i2c hubs use a custom `hub` image that is defined in the [helm-charts directory of the infrastructure repository](https://github.com/2i2c-org/infrastructure/tree/HEAD/helm-charts/images/hub).
+
+## The `hub` image
 
 This custom hub image is built on top of the [jupyterhub/k8s-hub](https://hub.docker.com/r/jupyterhub/k8s-hub) Docker image and configured based on the needs of 2i2c hubs.
 This allows adding and configuring other packages like the [jupyterhub-configurator](https://github.com/yuvipanda/jupyterhub-configurator) or using specific versions of the spawner and authenticator.
 More information about this custom image can be found in the [Dockerfile](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub/Dockerfile) itself.
 
-The 2i2c custom hub image is lives at [Quay.io](https://quay.io/repository/2i2c/pilot-hub).
 
-## Updating the hub image
+## The `hub-experimental` image
+
+In addition to the `hub` image, there is also a `hub-experimental` image, that is defined in the [helm-charts directory of the infrastructure repository](https://github.com/2i2c-org/infrastructure/tree/HEAD/helm-charts/images/hub-experimental).
+
+This `hub-experimental` image is very similar to the hub image, but its primary goal is to be used to test changes like new packages, newer package versions, or even unreleased or unmerged versions of them. It can be used to deploy such change just to one or a few specific communities, without having to worry about the instabilities it can generate for other communities.
+
+```{note}
+Both the 2i2c custom `hub` and the `hub-experimental` images live at [Quay.io](https://quay.io/repository/2i2c/pilot-hub).
+```
+
+## When to roll out the changes in `hub-experimental` to `hub`
+
+```{important}
+Our current policy states that a change in `hub-experimental` must be rolled out into `hub`, **within  4 weeks**, otherwise it should be removed. Any issues identified within these 4 weeks, must be fixed it until it's good enough to deploy to all hubs.
+```
+
+The workflow is the following:
+```{mermaid}
+flowchart TD
+  build_hub_experimental[Build a new `hub-experimental` image fa:fa-camera-retro]-->configure_hub_with_experiment[Configure the hub of at least one community to use the new image]
+  configure_hub_with_experiment-->deploy_hub[fa:fa-rocket Deploy]
+  -- Watch for one week to see how it goes! ---
+  deploy_hub --> condition{{Runs for one week without needing any fixes?}}
+  condition -- Yes --- roll_out[Roll out changes from `hub-experimental` into the `hub` image]
+  condition -- No --- fix[Fix issues fa:fa-ban]
+  fix --> condition
+  roll_out --> deploy_everywhere[Deploy hub image everywhere fa:fa-rocket]
+  -- More testing for hubs that are configured differently ---
+  deploy_everywhere --> end_condition[`hub-experimental` image is the same as `hub` fa:fa-exclamation]
+```
 
-When this hub image needs to be updated, the steps to take are:
+## How to install an unreleased version of a package in the `hub-experimental` image
 
-1. Update the [Dockerfile](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub/Dockerfile) with any changes wanted
+To install an unreleased package, we will need to install directly from GitHub and not from PyPI:
 
-2. Commit the changes
+1. Identify the package and commit you wish to install into the hub image. Example:
+
+   ```bash
+   https://github.com/jupyterhub/kubespawner@def501f1d60b8e5629745acb0bcc45b151b1decc
+   ```
+
+2. Update the [requirements.txt](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub-experimental/requirements.txt)) file to add this package and commit, prefixed by a `git+` on a new row. Example:
+
+   ```bash
+   git+https://github.com/jupyterhub/kubespawner@def501f1d60b8e5629745acb0bcc45b151b1decc
+   ```
+
+3. Commit the changes
 
    ```bash
    git add helm-charts/images/hub/Dockerfile
@@ -25,56 +67,71 @@ When this hub image needs to be updated, the steps to take are:
    The commit SHA with be used to generate the image tag.
    ```
 
-3. Rebuild the Docker image and push it to the [Quay.io registry](https://quay.io/repository/2i2c/pilot-hub)
+## How to build and push a new version of the hub image (`hub` or `hub-experimental`)
+
+Rebuild the Docker image and push it to the [Quay.io registry](https://quay.io/repository/2i2c/pilot-hub)
  
-   - Your `@2i2c` address should give you access to push to the Quay.io registry where the hub image lives, but make sure you are logged into quay.io container registry with the right credentials and these creds are configured to have access to <https://quay.io/repository/2i2c/pilot-hub>.
-     Please contact someone at 2i2c for access if this is not the case.
+- Your `@2i2c` address should give you access to push to the Quay.io registry where the hub image lives, but make sure you are logged into quay.io container registry with the right credentials and these creds are configured to have access to <https://quay.io/repository/2i2c/pilot-hub>.
+  Please contact someone at 2i2c for access if this is not the case.
 
-     ```bash
-     docker login quay.io
-     ```
+  ```bash
+  docker login quay.io
+  ```
 
-     ```{seealso}
-     Checkout the [Getting Started with Quay.io](https://docs.quay.io/solution/getting-started.html) docs for more info.
-     ```
+  ```{seealso}
+  Checkout the [Getting Started with Quay.io](https://docs.quay.io/solution/getting-started.html) docs for more info.
+  ```
 
-   - Make sure you have [jupyterhub/chartpress](https://github.com/jupyterhub/chartpress) installed.
+- Make sure you have [jupyterhub/chartpress](https://github.com/jupyterhub/chartpress) installed.
 
-     ```bash
-     pip install chartpress
-     ```
+  ```bash
+  pip install chartpress
+  ```
 
-     This package is also listed under `dev-requirements.txt`, so it should be present if you've installed the dev dependencies.
+  This package is also listed under `dev-requirements.txt`, so it should be present if you've installed the dev dependencies.
 
-   - Make sure you are in the `helm-charts` directory, where the `chartpress.yaml` is located:
+- Make sure you are in the `helm-charts` directory, where the `chartpress.yaml` is located:
 
-     ```bash
-     cd ./helm-charts
-     ```
+  ```bash
+  cd ./helm-charts
+  ```
 
-   - Run chartpress to build the image, push it to the registry and update the basehub helm chart to use the updated image tag
+- Run chartpress to build the image, push it to the registry and update the basehub helm chart to use the updated image tag
 
-     ```bash
-     chartpress --push
-     ```
+  ```bash
+  chartpress --push
+  ```
 
-     ````{note}
-     If you are on macOs with M1, you need to run chartpress with [docker buildx](https://docs.docker.com/build/buildx/) under the hood and specify which platform to use, i.e. `amd64`[^1].
+  ````{note}
+  If you are on macOs with M1, you need to run chartpress with [docker buildx](https://docs.docker.com/build/buildx/) under the hood and specify which platform to use, i.e. `amd64`[^1].
 
-     ```
-      chartpress --push --builder docker-buildx --platform linux/amd64
-     ```
-     ````
+  ```
+  chartpress --push --builder docker-buildx --platform linux/amd64
+  ```
+  ````
 
-   - Commit the changes made by `chartpress` to `helm-charts/basehub/values.yaml`, but discard the changes made to `helm-charts/basehub/Chart.yaml` as the last may cause problems with the `daskhub` dependency mechanism.
+- **If building and pushing the `hub` image**, then commit the changes made by `chartpress` to `helm-charts/basehub/values.yaml`, but discard the changes made to `helm-charts/basehub/Chart.yaml` as the last may cause problems with the `daskhub` dependency mechanism.
 
-     ```bash
-     git add helm-charts/basehub/values.yaml
-     git commit
-     ```
+  ```bash
+  git add helm-charts/basehub/values.yaml
+  git commit
+  ```
 
-```{note}
+- **If building and pushing the `hub-experimental` image**, then discard the changes to both `helm-charts/basehub/values.yaml` and `helm-charts/basehub/Chart.yaml`, because we only want to deploy this image to particular hubs
+
+## How to configure a hub to use the new `hub-experimental` image
+
+You will need to put a config similar to the one below in your hub configuration file:
+
+```
+hub:
+  image:
+    name: quay.io/2i2c/experimental-hub
+    tag: "0.0.1-0.dev.git.6406.hc1091b1c"
+```
+
+```{important}
 The image tag of the of the [jupyterhub/k8s-hub](https://hub.docker.com/r/jupyterhub/k8s-hub) [in the Dockerfile](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub/Dockerfile#L9) must match the dependent JupyterHub Helm chart's version as declared in [basehub/Chart.yaml](https://github.com/2i2c-org/infrastructure/blob/master/helm-charts/basehub/Chart.yaml#L14).
 ```
 
-[^1]: <https://cloudolife.com/2022/03/05/Infrastructure-as-Code-IaC/Container/Docker/Docker-buildx-support-multiple-architectures-images/>
+[^1]: <https://cloudolife.com/2022/03/05/Infrastructure-as-Code-IaC/Container/Docker/Docker-buildx-support-multiple-architectures-images/>
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
index de00434bf4..786c72a66b 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -7,3 +7,4 @@ sphinx-copybutton
 sphinx-design
 # Pin pydate-sphinx-theme
 git+https://github.com/2i2c-org/sphinx-2i2c-theme
+sphinxcontrib-mermaid==0.9.2

From 6f1ffb42e789a19a12a8de62612bce933c455ecb Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Mon, 24 Jul 2023 17:03:03 +0300
Subject: [PATCH 08/13] Some cleanup

---
 docs/howto/features/index.md | 2 +-
 docs/index.md                | 1 +
 docs/topic/features.md       | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/howto/features/index.md b/docs/howto/features/index.md
index c953a26118..f6e01e44b7 100644
--- a/docs/howto/features/index.md
+++ b/docs/howto/features/index.md
@@ -47,5 +47,5 @@ ephemeral.md
 :maxdepth: 2
 :caption: Other
 dedicated-nodepool.md
-custom-jupyterhub-image.md
+allow-unlisted-profile-choice.md
 ```
diff --git a/docs/index.md b/docs/index.md
index 53d472ff8c..a4327dfa62 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -69,6 +69,7 @@ deployed occasionally as a specific addition.
 :caption: How-to guides
 howto/features/index.md
 howto/bill.md
+howto/custom-jupyterhub-image.md
 howto/manage-domains/index.md
 howto/grafana-github-auth.md
 howto/update-env.md
diff --git a/docs/topic/features.md b/docs/topic/features.md
index 99a0d5a832..2ca11f4014 100644
--- a/docs/topic/features.md
+++ b/docs/topic/features.md
@@ -1,4 +1,4 @@
-(hub-features)=
+(hub-features-summary)=
 # Features available on the hubs
 
 This document is a concise description of various features we can

From 23dd1e6b9874149f3cafa2a649f8b5d10206f73e Mon Sep 17 00:00:00 2001
From: Georgiana <georgiana.dolocan@gmail.com>
Date: Tue, 25 Jul 2023 10:07:15 +0300
Subject: [PATCH 09/13] Fix link towards quay 2i2c organization

Co-authored-by: Yuvi Panda <yuvipanda@gmail.com>
---
 docs/howto/custom-jupyterhub-image.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/howto/custom-jupyterhub-image.md b/docs/howto/custom-jupyterhub-image.md
index 4c2a4ca279..67e23cca38 100644
--- a/docs/howto/custom-jupyterhub-image.md
+++ b/docs/howto/custom-jupyterhub-image.md
@@ -16,7 +16,7 @@ In addition to the `hub` image, there is also a `hub-experimental` image, that i
 This `hub-experimental` image is very similar to the hub image, but its primary goal is to be used to test changes like new packages, newer package versions, or even unreleased or unmerged versions of them. It can be used to deploy such change just to one or a few specific communities, without having to worry about the instabilities it can generate for other communities.
 
 ```{note}
-Both the 2i2c custom `hub` and the `hub-experimental` images live at [Quay.io](https://quay.io/repository/2i2c/pilot-hub).
+Both the 2i2c custom `hub` and the `hub-experimental` images live at [Quay.io](https://quay.io/organization/2i2c).
 ```
 
 ## When to roll out the changes in `hub-experimental` to `hub`

From 211d61633188f2da7be2368e69e1611e65d90c18 Mon Sep 17 00:00:00 2001
From: Georgiana <georgiana.dolocan@gmail.com>
Date: Tue, 25 Jul 2023 10:07:40 +0300
Subject: [PATCH 10/13] Better wording for the validation message

Co-authored-by: Yuvi Panda <yuvipanda@gmail.com>
---
 config/clusters/leap/common.values.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/clusters/leap/common.values.yaml b/config/clusters/leap/common.values.yaml
index f187f5f45e..1f59a4ac0b 100644
--- a/config/clusters/leap/common.values.yaml
+++ b/config/clusters/leap/common.values.yaml
@@ -196,7 +196,7 @@ basehub:
                 enabled: True
                 display_name: "Custom image"
                 validation_regex: "^.+:.+$"
-                validation_message: "Must be an image location, matching ^.+:.+$"
+                validation_message: "Must be a valid public docker image, including a tag"
                 kubespawner_override:
                   image: "{value}"
               choices:

From a6acf8cecab80cb6805ae4278d2513f81a9f5651 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Tue, 25 Jul 2023 10:14:10 +0300
Subject: [PATCH 11/13] Add note about the importance of commit sha vs branch

Co-authored-by: Yuvi Panda <yuvipanda@gmail.com>
---
 docs/howto/custom-jupyterhub-image.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/howto/custom-jupyterhub-image.md b/docs/howto/custom-jupyterhub-image.md
index 67e23cca38..600fb1985a 100644
--- a/docs/howto/custom-jupyterhub-image.md
+++ b/docs/howto/custom-jupyterhub-image.md
@@ -44,13 +44,17 @@ flowchart TD
 
 To install an unreleased package, we will need to install directly from GitHub and not from PyPI:
 
-1. Identify the package and commit you wish to install into the hub image. Example:
+1. Identify the package and commit you wish to install into the hub image
+
+   ```{important}
+   Specify a full commit hash after `@`, not a branch name. This way, our builds are more reproducible!
+   ```
 
    ```bash
    https://github.com/jupyterhub/kubespawner@def501f1d60b8e5629745acb0bcc45b151b1decc
    ```
 
-2. Update the [requirements.txt](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub-experimental/requirements.txt)) file to add this package and commit, prefixed by a `git+` on a new row. Example:
+2. Update the [requirements.txt](https://github.com/2i2c-org/infrastructure/blob/HEAD/helm-charts/images/hub-experimental/requirements.txt) file to add this package and commit, prefixed by a `git+` on a new row
 
    ```bash
    git+https://github.com/jupyterhub/kubespawner@def501f1d60b8e5629745acb0bcc45b151b1decc

From 80bc3e221930b10b5521a92026b078cd4cec59d9 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Tue, 25 Jul 2023 10:22:51 +0300
Subject: [PATCH 12/13] Put the icons before the description in the diagram

---
 docs/howto/custom-jupyterhub-image.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/howto/custom-jupyterhub-image.md b/docs/howto/custom-jupyterhub-image.md
index 600fb1985a..72a6728cde 100644
--- a/docs/howto/custom-jupyterhub-image.md
+++ b/docs/howto/custom-jupyterhub-image.md
@@ -28,16 +28,16 @@ Our current policy states that a change in `hub-experimental` must be rolled out
 The workflow is the following:
 ```{mermaid}
 flowchart TD
-  build_hub_experimental[Build a new `hub-experimental` image fa:fa-camera-retro]-->configure_hub_with_experiment[Configure the hub of at least one community to use the new image]
+  build_hub_experimental[fa:fa-camera-retro Build a new `hub-experimental` image]-->configure_hub_with_experiment[Configure the hub of at least one community to use the new image]
   configure_hub_with_experiment-->deploy_hub[fa:fa-rocket Deploy]
   -- Watch for one week to see how it goes! ---
   deploy_hub --> condition{{Runs for one week without needing any fixes?}}
   condition -- Yes --- roll_out[Roll out changes from `hub-experimental` into the `hub` image]
-  condition -- No --- fix[Fix issues fa:fa-ban]
+  condition -- No --- fix[fa:fa-ban Fix issues]
   fix --> condition
-  roll_out --> deploy_everywhere[Deploy hub image everywhere fa:fa-rocket]
+  roll_out --> deploy_everywhere[fa:fa-rocket Deploy hub image everywhere]
   -- More testing for hubs that are configured differently ---
-  deploy_everywhere --> end_condition[`hub-experimental` image is the same as `hub` fa:fa-exclamation]
+  deploy_everywhere --> end_condition[fa:fa-exclamation `hub-experimental` image is the same as `hub`]
 ```
 
 ## How to install an unreleased version of a package in the `hub-experimental` image

From 441fa5f5c796f380b7f241a99c2e5ba4869f2866 Mon Sep 17 00:00:00 2001
From: Georgiana Dolocan <georgiana.dolocan@gmail.com>
Date: Tue, 25 Jul 2023 10:34:50 +0300
Subject: [PATCH 13/13] Use anchors to avoid repetition

Co-authored-by: Yuvi Panda <yuvipanda@gmail.com>
---
 config/clusters/leap/common.values.yaml | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/config/clusters/leap/common.values.yaml b/config/clusters/leap/common.values.yaml
index 1f59a4ac0b..d46ea07e32 100644
--- a/config/clusters/leap/common.values.yaml
+++ b/config/clusters/leap/common.values.yaml
@@ -192,7 +192,7 @@ basehub:
                     cpu_limit: 16
             image: &profile_list_profile_options_image
               display_name: Image
-              unlisted_choice:
+              unlisted_choice: &profile_list_unlisted_choice
                 enabled: True
                 display_name: "Custom image"
                 validation_regex: "^.+:.+$"
@@ -278,13 +278,7 @@ basehub:
           profile_options:
             image:
               display_name: Image
-              unlisted_choice:
-                enabled: True
-                display_name: "Custom image"
-                validation_regex: "^.+:.+$"
-                validation_message: "Must be an image location, matching ^.+:.+$"
-                kubespawner_override:
-                  image: "{value}"
+              unlisted_choice: *profile_list_unlisted_choice
               choices:
                 tensorflow_new:
                   display_name: Pangeo Tensorflow ML Notebook ("2023.05.18")