feat(helm): Setup helm-docs and generate readme files for helm charts

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/norwoodj/helm-docs
+    rev: v1.14.2
+    hooks:
+      - id: helm-docs-container
+        files: helm-charts/(.*)/values.yaml
+        args:
+          # Make the tool search for charts only under the `example-charts` directory
+          - --chart-search-root=helm-charts

helm-charts/cogstack-helm-ce/README.md

@@ -72,3 +72,58 @@ If the namespace was created only for this release, remove it with:
 ```bash
 kubectl delete namespace cogstack
 ```
+
+## Requirements
+
+| Repository | Name | Version |
+|------------|------|---------|
+| file://../medcat-service-helm | medcat-service(medcat-service-helm) | 0.0.1 |
+| file://../medcat-service-helm | anoncat-service(medcat-service-helm) | 0.0.1 |
+| file://../medcat-trainer-helm | medcat-trainer(medcat-trainer-helm) | 0.0.1 |
+| file://charts/jupyterhub | cogstack-jupyterhub | 0.1.0 |
+| https://opensearch-project.github.io/helm-charts/ | opensearch | 3.5.0 |
+| https://opensearch-project.github.io/helm-charts/ | opensearch-dashboards | 3.5.0 |
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| anoncat-service.enabled | bool | `true` | Enable AnonCAT service deployment. |
+| anoncat-service.env.APP_MEDCAT_MODEL_PACK | string | `"/cat/models/examples/example-deid-model-pack.zip"` | Model pack used by the MedCAT service when running in DeID mode. |
+| anoncat-service.env.DEID_MODE | bool | `true` | Enable DeID mode. |
+| anoncat-service.env.DEID_REDACT | bool | `false` | Enable redaction behaviour for DeID. |
+| anoncat-service.image.repository | string | `"cogstacksystems/medcat-service"` | MedCAT service image repository for AnonCAT. |
+| anoncat-service.image.tag | string | `"1.2.0"` | MedCAT service image tag used by AnonCAT. |
+| anoncat-service.replicasCount | int | `1` | Number of AnonCAT (medcat-service in DeID mode) replicas. |
+| cogstack-jupyterhub.enabled | bool | `true` | Enable JupyterHub (with hub and singleuser components). |
+| cogstack-jupyterhub.jupyterhub.hub.config.Authenticator.admin_users | list | `["admin"]` | Allowed admin users for the dummy authenticator. |
+| cogstack-jupyterhub.jupyterhub.hub.config.Authenticator.admin_users[0] | string | `"admin"` | Admin user entry for the dummy authenticator. |
+| cogstack-jupyterhub.jupyterhub.hub.config.DummyAuthenticator.password | string | `"SuperSecret"` | Password for the dummy authenticator (do not use in production). |
+| cogstack-jupyterhub.jupyterhub.hub.config.JupyterHub.authenticator_class | string | `"dummy"` | Authenticator class used by JupyterHub (dummy authenticator for demo/non-prod). |
+| cogstack-jupyterhub.jupyterhub.hub.image.name | string | `"cogstacksystems/jupyter-hub"` | JupyterHub hub image name. |
+| cogstack-jupyterhub.jupyterhub.hub.image.tag | string | `"2.2.2"` | JupyterHub hub image tag. |
+| cogstack-jupyterhub.jupyterhub.singleuser.image.name | string | `"cogstacksystems/jupyter-singleuser"` | JupyterHub singleuser image name. |
+| cogstack-jupyterhub.jupyterhub.singleuser.image.pullPolicy | string | `"IfNotPresent"` | JupyterHub singleuser image pull policy. |
+| cogstack-jupyterhub.jupyterhub.singleuser.image.tag | string | `"2.2.2"` | JupyterHub singleuser image tag. |
+| fullnameOverride | string | `""` | Fully override the chart fullname. |
+| imagePullSecrets | list | `[]` | This is for the secrets for pulling an image from a private repository more information can be found here: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ |
+| medcat-service.enabled | bool | `true` | Enable MedCAT service deployment. |
+| medcat-service.image.repository | string | `"cogstacksystems/medcat-service"` | MedCAT service image repository. |
+| medcat-service.image.tag | string | `"1.2.0"` | MedCAT service image tag. |
+| medcat-service.replicasCount | int | `1` | Number of MedCAT service replicas. |
+| medcat-trainer.enabled | bool | `true` | Enable MedCAT Trainer deployment. |
+| medcat-trainer.env.CSRF_TRUSTED_ORIGINS | string | `"http://localhost:8080"` | CSRF trusted origins for the MedCAT Trainer frontend (set for your deployment/port-forward). |
+| medcat-trainer.image.tag | string | `"latest@sha256:103215a7540ad614c32866f4cb00ddd91e7aff37cea9abc25dc226c577f9506d"` | MedCAT Trainer image tag (can be a digest-pinned tag). |
+| medcat-trainer.provisioning.enabled | bool | `true` | Enable provisioning of projects and models on startup. |
+| medcat-trainer.provisioning.existingConfigMap.name | string | `"cogstack-helm-ce-example-trainer-provisioining"` | Existing ConfigMap name containing the provisioning configuration. |
+| nameOverride | string | `""` | This is to override the chart name. |
+| opensearch-dashboards.enabled | bool | `true` | Deploy an opensearch-dashboards instance |
+| opensearch.enabled | bool | `true` | Deploy an opensearch cluster |
+| opensearch.extraEnvs | list | Sets the initial admin password for OpenSearch | Extra environment variables to pass to OpenSearch. |
+| provisioning.enabled | bool | `true` | Enable provisioning for supporting services (e.g. OpenSearch templates/documents). |
+| provisioning.opensearch.createExampleDocuments | bool | `true` | Create example documents in OpenSearch on startup. |
+| provisioning.opensearch.createIndexTemplate | bool | `true` | Create the OpenSearch index template on startup. |
+| provisioning.opensearchDashboards.createDashboards | bool | `true` | Create dashboards on startup. |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)

helm-charts/cogstack-helm-ce/README.md.gotmpl

@@ -0,0 +1,80 @@
+# CogStack Helm Community Edition
+
+This is a all in one helm chart that runs CogStack on Kubernetes
+
+## Overview
+
+This chart is an umbrella chart that deploys:
+
+| Component        | Description |
+|------------------|-------------|
+| **MedCAT**       | Medical Concept Annotation Tool — NER and linking for clinical text. |
+| **AnonCAT**      | De-identification service (MedCAT in DEID mode) for anonymising text. |
+| **MedCAT Trainer** | Training and model management for MedCAT, with Solr and PostgreSQL. |
+
+## Prerequisites
+
+- Kubernetes cluster
+- Helm 3+
+
+## Installation
+
+```sh
+helm install cogstack oci://registry-1.docker.io/cogstacksystems/cogstack-helm-ce
+```
+
+## Configuration
+These are some values that are likely to need customization for your deployment:
+
+| Value | Default | Description |
+|-------|---------|-------------|
+| `medcat-service.replicasCount` | `1` | Number of MedCAT service replicas. |
+| `anoncat-service.replicasCount` | `1` | Number of AnonCAT service replicas. |
+| `anoncat-service.env.DEID_REDACT` | `false` | Redaction behaviour for de-identification. |
+| `medcat-trainer.env.CSRF_TRUSTED_ORIGINS` | `"http://localhost:8080"` | CSRF trusted origins for MedCAT Trainer frontend (set correct value for your deployment, this default works for port forwarding). |
+
+Subcharts (MedCAT service, AnonCAT service, MedCAT Trainer) support additional options; see their respective charts under `../medcat-service-helm` and `../medcat-trainer-helm`. Pass them under the same keys as in this chart’s `values.yaml` (e.g. `medcat-service.*`, `anoncat-service.*`, `medcat-trainer-helm.*`).
+
+Example override file:
+
+```yaml
+# my-values.yaml
+medcat-service:
+  replicasCount: 2
+anoncat-service:
+  replicasCount: 1
+  env:
+    APP_ENABLE_DEMO_UI: true
+    DEID_MODE: true
+```
+
+Install with overrides:
+
+```bash
+helm install cogstack . -f my-values.yaml --namespace cogstack --create-namespace
+```
+
+## Dependencies
+
+The chart uses local subcharts via relative paths:
+
+- `medcat-service-helm` (as `medcat-service` and `anoncat-service`)
+- `medcat-trainer-helm`
+
+## Uninstall
+
+```bash
+helm uninstall cogstack-ce --namespace cogstack
+```
+
+If the namespace was created only for this release, remove it with:
+
+```bash
+kubectl delete namespace cogstack
+```
+
+{{ template "chart.requirementsSection" . }}
+
+{{ template "chart.valuesSection" . }}
+
+{{ template "helm-docs.versionFooter" . }}

helm-charts/cogstack-helm-ce/charts/jupyterhub/README.md

@@ -0,0 +1,54 @@
+# cogstack-jupyterhub
+
+![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square)
+
+A Helm chart for CogStack Jupyter Hub using official JupyterHub chart
+
+## Requirements
+
+| Repository | Name | Version |
+|------------|------|---------|
+| https://hub.jupyter.org/helm-chart/ | jupyterhub | 4.3.2 |
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| jupyterhub.cull.enabled | bool | false, so pods stay running indefinitely d | Enable culling of user pods |
+| jupyterhub.hub.config.Authenticator.admin_users[0] | string | `"admin"` |  |
+| jupyterhub.hub.config.DummyAuthenticator.password | string | `"SuperSecret"` |  |
+| jupyterhub.hub.config.JupyterHub.authenticator_class | string | `"dummy"` |  |
+| jupyterhub.hub.config.KubeSpawner.fs_gid | int | `0` |  |
+| jupyterhub.hub.config.KubeSpawner.http_timeout | int | `120` |  |
+| jupyterhub.hub.config.KubeSpawner.notebook_dir | string | `"/home/jovyan/work"` |  |
+| jupyterhub.hub.config.KubeSpawner.start_timeout | int | `300` |  |
+| jupyterhub.hub.config.KubeSpawner.uid | int | `0` |  |
+| jupyterhub.hub.config.Spawner.default_url | string | `"/lab/"` |  |
+| jupyterhub.hub.config.Spawner.notebook_dir | string | `"/home/jovyan/work"` |  |
+| jupyterhub.hub.extraConfig | object | `{"00-custom-spawner":"# Custom environment variables for user pods\nc.KubeSpawner.environment = {\n    'GRANT_SUDO': '1',\n    'CHOWN_HOME': 'yes',\n    'CHOWN_HOME_OPTS': '-R',\n}\n# Allow root in notebooks\nc.KubeSpawner.args = ['--allow-root']\n"}` | Extra hub configuration for custom spawner settings |
+| jupyterhub.hub.extraConfig.00-log-level | string | `"c.Application.log_level = 'DEBUG'\n"` |  |
+| jupyterhub.hub.image.name | string | `"cogstacksystems/jupyter-hub"` | Image repository for the JupyterHub hub. |
+| jupyterhub.hub.image.pullPolicy | string | `"IfNotPresent"` | Pull policy for the JupyterHub hub. |
+| jupyterhub.hub.image.tag | string | `"2.2.2"` | Image tag for the JupyterHub hub. |
+| jupyterhub.prePuller.continuous.enabled | bool | `false` |  |
+| jupyterhub.prePuller.hook | object | `{"enabled":false}` | Enable pulling the singleuser image before they are used to improve startup time |
+| jupyterhub.proxy.service.type | string | `"ClusterIP"` |  |
+| jupyterhub.scheduling.userScheduler.replicas | int | `1` |  |
+| jupyterhub.singleuser.cmd[0] | string | `"jupyterhub-singleuser"` |  |
+| jupyterhub.singleuser.extraPodConfig | object | `{"securityContext":{"runAsGroup":0,"runAsUser":0}}` | Extra arguments passed to jupyterhub-singleuser |
+| jupyterhub.singleuser.fsGid | int | `0` |  |
+| jupyterhub.singleuser.image.name | string | `"cogstacksystems/jupyter-singleuser"` |  |
+| jupyterhub.singleuser.image.pullPolicy | string | `"IfNotPresent"` |  |
+| jupyterhub.singleuser.image.tag | string | `"2.2.2"` |  |
+| jupyterhub.singleuser.lifecycleHooks.postStart | object | `{"exec":{"command":["sh","-c","if [ ! -f /home/jovyan/work/.notebooks_initialized ]; then\n  echo \"First run - copying notebooks and medcat-scripts...\";\n  cp -r /srv/jupyterhub/notebooks/* /home/jovyan/work/;\n  cp -r /srv/jupyterhub/medcat-scripts /home/jovyan/work/;\n  touch /home/jovyan/work/.notebooks_initialized;\n  echo \"Notebooks initialized successfully\";\nelse\n  echo \"Notebooks already initialized - skipping\";\nfi\n"]}}` | Lifecycle hook to copy notebooks from image to PVC on first run |
+| jupyterhub.singleuser.networkPolicy.enabled | bool | `false` |  |
+| jupyterhub.singleuser.startTimeout | int | `600` |  |
+| jupyterhub.singleuser.storage.capacity | string | `"5Gi"` | Capacity of the storage for the user pods. |
+| jupyterhub.singleuser.storage.extraVolumeMounts.jupyter-examples.mountPath | string | `"/home/jovyan/work/examples"` |  |
+| jupyterhub.singleuser.storage.extraVolumeMounts.jupyter-examples.name | string | `"jupyter-examples"` |  |
+| jupyterhub.singleuser.storage.extraVolumeMounts.jupyter-examples.readOnly | bool | `true` |  |
+| jupyterhub.singleuser.storage.extraVolumes | object | `{"jupyter-examples":{"configMap":{"name":"jupyter-examples"},"name":"jupyter-examples"}}` | NOTE: Prefer dictionary-form here to avoid Helm merge issues when this subchart is configured by a parent chart. |
+| jupyterhub.singleuser.uid | int | `0` |  |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)

helm-charts/cogstack-helm-ce/charts/jupyterhub/README.md.gotmpl

@@ -0,0 +1,18 @@
+{{ template "chart.header" . }}
+{{ template "chart.deprecationWarning" . }}
+
+{{ template "chart.badgesSection" . }}
+
+{{ template "chart.description" . }}
+
+{{ template "chart.homepageLine" . }}
+
+{{ template "chart.maintainersSection" . }}
+
+{{ template "chart.sourcesSection" . }}
+
+{{ template "chart.requirementsSection" . }}
+
+{{ template "chart.valuesSection" . }}
+
+{{ template "helm-docs.versionFooter" . }}

helm-charts/cogstack-helm-ce/charts/jupyterhub/values.yaml

@@ -2,8 +2,11 @@
 jupyterhub:
   hub:
     image:
+        # -- Image repository for the JupyterHub hub.
       name: cogstacksystems/jupyter-hub
+      # -- Image tag for the JupyterHub hub.
       tag: "2.2.2"
+      # -- Pull policy for the JupyterHub hub.
       pullPolicy: IfNotPresent
     extraConfig:
       00-log-level: |
@@ -28,7 +31,7 @@ jupyterhub:
         default_url: /lab/
         notebook_dir: /home/jovyan/work
 
-    # Extra hub configuration for custom spawner settings
+    # -- Extra hub configuration for custom spawner settings
     extraConfig:
       00-custom-spawner: |
         # Custom environment variables for user pods
@@ -48,8 +51,8 @@ jupyterhub:
       name: cogstacksystems/jupyter-singleuser
       tag: "2.2.2"
       pullPolicy: IfNotPresent
-    # Lifecycle hook to copy notebooks from image to PVC on first run
     lifecycleHooks:
+      # -- Lifecycle hook to copy notebooks from image to PVC on first run
       postStart:
         exec:
           command:
@@ -73,15 +76,16 @@ jupyterhub:
     fsGid: 0
     cmd: ["jupyterhub-singleuser"]
 
-    # Extra arguments passed to jupyterhub-singleuser
+    # -- Extra arguments passed to jupyterhub-singleuser
     extraPodConfig:
       securityContext:
         runAsUser: 0
         runAsGroup: 0
 
     storage:
+      # -- Capacity of the storage for the user pods.
       capacity: 5Gi
-      # NOTE: Prefer dictionary-form here to avoid Helm merge issues
+      # -- NOTE: Prefer dictionary-form here to avoid Helm merge issues
       # when this subchart is configured by a parent chart.
       extraVolumes:
         jupyter-examples:
@@ -94,11 +98,14 @@ jupyterhub:
           mountPath: /home/jovyan/work/examples
           readOnly: true
   cull:
+    # -- Enable culling of user pods
+    # @default -- false, so pods stay running indefinitely
     enabled: false
   scheduling:
     userScheduler:
       replicas: 1
   prePuller:
+    # -- Enable pulling the singleuser image before they are used to improve startup time
     hook:
       enabled: false
     continuous: