Kubernetes installation (Helm)
The Kubernetes path is the recommended way to run the GEO Knowledge Hub in production. It uses the
upstream helm-invenio chart from the InvenioRDM
community, configured with the GEO Knowledge Hub settings.
There are two ways to get there. Both install the same chart and produce the same instance. They differ only in who writes the configuration.
Which path should I use?
Section titled “Which path should I use?”| With the CLI | Manually | |
|---|---|---|
| You maintain | a ~40-line configuration file | a ~200-line values.yaml |
| Helm values | generated | written by hand |
| Configuration checks | run before anything is installed | none |
| Credentials | generated into Kubernetes Secrets | written into values.yaml |
| Post-install sequence | one script | seven commands, run by hand |
| Extra requirement | Python 3.12+ and uv, on your machine | none |
Take the CLI path unless you have a reason not to: it is faster, it keeps passwords out of your files, and it checks the configuration against the failure modes we have hit in production before you install anything.
Take the manual path when you want to author every value yourself, or when you cannot install Python tooling on the machine that drives the deployment.
Prerequisites
Section titled “Prerequisites”- A Kubernetes cluster. For local testing use Minikube or kind.
- Helm 3.
- Kubectl.
- An ingress controller (the chart targets nginx-ingress by default).
- A
ReadWriteManystorage class for the shared file volume. - For the CLI path only: Python 3.12+ and uv, on the machine you drive the deployment from. Nothing is installed on the cluster.
The pages
Section titled “The pages”Read the first two, then follow one of the two installation paths. Everything after the fork applies to both.
Helm chart
Architecture of the helm-invenio chart: deployments, bundled and external services, image, and how GKH layers its configuration on top.
Prepare the cluster
Shared groundwork for both paths: the sizing profile, the cluster and its addons, the namespace, and the hostname you will reach the instance on.
Install with the CLI
Describe the instance once, and let gkh deploy check the configuration and generate the Helm values, the Secrets and the post-install script.
Install manually
Write the values.yaml yourself and call helm directly, with a known-good file for each profile.
Post-install setup
What the chart does not seed: the database schema, the file location, the GEO-specific roles, the administrator and the controlled vocabularies.
Validate the deployment
An optional step to drive the instance over its API and UI with gkh validate, and confirm every feature works before going to production.
Helm chart parameters reference
Searchable list of every chart parameter.
Recommended path
Section titled “Recommended path”If you have never deployed the chart before, work through the pages in this order:
1) Read the Helm chart page to understand what the chart deploys, which services are bundled, and how GEO Knowledge Hub configuration is layered on top of the upstream defaults.
2) Work through Prepare the cluster, which also asks you to choose a sizing profile. That choice follows you through the rest of the section.
3) Install, either with the CLI or manually.
4) Run the post-install setup, which seeds what the chart does not. The CLI path runs this sequence for you; the page explains what it did.
5) Optionally validate the deployment before you rely on it.
6) Adapt your configuration to a real cluster (hostname, ingress class, image tag, persistence size, replica counts), using the parameters reference as a glossary.