Prepare the cluster

Both installation paths, the GEO Knowledge Hub CLI and the manual one, start from the same place: a cluster with an ingress controller, a namespace to install into, and a hostname you can reach the instance on. This page covers that groundwork once, so neither path has to repeat it.

If you already have a cluster

The Minikube steps below are for readers building a local environment. If you are deploying to a cluster that already exists, you only need two things from this page: the namespace and the hostname decision. Your platform team provides the rest.

Prerequisites

• Minikube, or any Kubernetes cluster
• Helm 3
• Kubectl

Total time: ~15 minutes for the whole installation, mostly waiting for image pulls.

Choose a configuration profile

This section ships two configurations, and the one you pick decides how much memory you need and which configuration you write later. Choose it now, before you start the cluster. The rest of this page and both installation paths follow your choice automatically, so you only make this decision once.

Minimal (development)

Collapses OpenSearch into a single node that holds every role and runs Redis without replicas, which brings the whole deployment down to eight pods. Nothing is replicated, so it is not something to build a production service on, but it starts quickly and it is what you want on a laptop or a small VM while you are developing against the API.

Budget roughly 4 vCPUs and 8 GB RAM.

Standard (production)

Follows the chart defaults, which spread OpenSearch across eight JVMs in four dedicated role pools and run Redis with three replicas, for twenty pods in total. The extra nodes buy you redundancy and room to grow, and the result is close enough to a real deployment that you can adapt it rather than start over.

Budget roughly 8 vCPUs and 16 GB RAM.

1. Start the Minikube cluster

Start the Minikube cluster with the following command:

Minimal (development)

minikube start \
  --cpus 4 \
  --memory 8192 \
  --driver docker

Standard (production)

minikube start \
  --cpus 8 \
  --memory 16384 \
  --driver docker

Verify the cluster is up:

kubectl cluster-info
kubectl get nodes

2. Enable required addons

Now, you need to enable the required addons:

minikube addons enable ingress
minikube addons enable default-storageclass
minikube addons enable storage-provisioner

3. Create a namespace

Next, create the invenio namespace:

kubectl create namespace invenio

4. Decide how you will reach it

The hostname you settle on here is not only a networking detail: both installation paths write it into the application configuration, so the application knows the address it is served on. Decide it before you configure anything.

This step depends on how you access your cluster

The commands below cover the two most common setups: Minikube running on your own machine, and Minikube running on a remote server you reach over SSH. If your environment is different (a VPN, a bastion host, a cloud LoadBalancer, or a real DNS name and certificate), adapt them.

What matters is only this: your browser must reach the ingress TLS port using the same hostname you configure the instance with. The instructions below use invenio.local:8080. If you serve the instance on a different hostname or port, use that one consistently from here on.

The ingress terminates TLS and redirects plain HTTP to HTTPS, so the application has to be reached over the ingress’ 443 port. First, point invenio.local at your loopback address:

echo "127.0.0.1 invenio.local" | sudo tee -a /etc/hosts

If Minikube runs on your own machine, forward the ingress controller to port 8080:

kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 8080:443

If Minikube runs on a remote server, open an SSH tunnel from your machine to the ingress instead. Get the Minikube IP on the server:

minikube ip   # e.g. 192.168.49.2

Then, from your own machine:

ssh -L 8080:192.168.49.2:443 <user>@<server>

Keep that session open while you use the instance.

Nothing answers on that address yet. You will open it once the application is installed and the post-install setup has created the admin user.

Next steps

The cluster is ready. Now choose how to produce and install the deployment:

1) Install with the CLI generates the Helm values, the Secrets and the post-install script for you, and checks the configuration before you install anything.

2) Install manually walks through the same deployment with a values.yaml you write and maintain yourself.