Quickstart on Minikube

This page walks you through a complete deployment of the GEO Knowledge Hub on a local Minikube cluster, end-to-end. It offers two configurations to start from, one sized for development and one that follows the chart defaults, and either can be adapted to a real cluster with the parameters reference.

Total time: ~15 minutes (mostly waiting for image pulls).

Prerequisites

• Minikube
• Helm 3
• Kubectl

Choose a configuration profile

This quickstart ships two complete configurations, and the one you pick decides how much memory you need and which my-values.yaml you write in step 4. Choose it now, before you start the cluster. The rest of the page follows 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.

Production starting point

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 file is close enough to a real deployment that you can adapt it rather than start over.

Budget roughly 8 vCPUs and 16 GB RAM. The bundled services alone reserve about 10.5 GB once OpenSearch is sized correctly.

1. Start the Minikube cluster

Start the Minikube cluster with the following command:

Minimal (development)

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

Production starting point

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. Prepare the configuration file

The helm-invenio, provides a lot of configuration options. For this quick example, we will use few options to ensure we are using the GEO Knowledge Hub image and setting few extra configurations. These configurations are defined in a my-values.yaml file.

If you want to learn more about all configuration options available, you can check the parameters reference.

Minimal (development)

Around eleven pods in total. OpenSearch is collapsed into a single node that holds every role, and Redis runs without replicas.

image:
  registry: docker.io
  repository: geoknowledgehub/geo-knowledge-hub
  tag: "v1.7.0.dev16"

invenio:
  hostname: "invenio.local"
  # Disabled on purpose. The init job runs `rdm-records demo` without loading
  # the vocabularies first, and it overlaps with the commands you run in the
  # post-install setup. Everything it does is covered there.
  init: false
  demo_data: false

  extraConfig:
    INVENIO_SITE_UI_URL: "https://invenio.local:8080"
    INVENIO_SITE_API_URL: "https://invenio.local:8080/api"
    INVENIO_APP_ALLOWED_HOSTS: '["invenio.local:8080", "invenio.local"]'

    INVENIO_CACHE_REDIS_URL: "redis://invenio-redis-master:6379/0"
    INVENIO_CELERY_RESULT_BACKEND: "redis://invenio-redis-master:6379/2"

    # Bug: The chart injects RATELIMIT_STORAGE_URI but flask-limiter
    #      reads RATELIMIT_STORAGE_URL. Set both to be safe.
    INVENIO_RATELIMIT_STORAGE_URI: "redis://invenio-redis-master:6379/3"
    INVENIO_RATELIMIT_STORAGE_URL: "redis://invenio-redis-master:6379/3"

  # Must be a map of "email: password"
  default_users:
    "admin@invenio.org": "admin123"

  # DOI provider
  datacite:
    enabled: true
    username: "GKH.EXAMPLE"
    password: "GKH.PASSWORD"
    existingSecret: "" # required, see the note below
    prefix: "10.5072"  # datacite test prefix
    testMode: "True"

ingress:
  enabled: true
  class: "nginx"

web:
  replicas: 1
  uwsgi:
    processes: 2
    threads: 2

worker:
  replicas: 1
  concurrency: 2

# Bundled sub-charts.
postgresql:
  enabled: true
  auth:
    username: invenio
    password: "dbpassword123"
    database: invenio

redis:
  enabled: true
  # One Redis pod instead of a master plus three replicas
  architecture: standalone
  auth:
    enabled: false

rabbitmq:
  enabled: true
  auth:
    password: "mqpassword123"

opensearch:
  enabled: true

  # A single node that holds every role, sized so the heap is half the limit.
  master:
    masterOnly: false   # this node also takes the data and ingest roles
    replicaCount: 1
    heapSize: 1024m
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: "1"
        memory: 2Gi

  # Dedicated role pools are not needed on a single node.
  data:
    replicaCount: 0

  ingest:
    replicaCount: 0

  coordinating:
    replicaCount: 0

persistence:
  enabled: true
  size: 5G
  storage_class: "standard"

flower:
  enabled: true

Two things are worth knowing about this mode. The chart still creates the invenio-opensearch service and points it at the remaining pod, so INVENIO_SEARCH_HOSTS keeps working without any change. And the cluster reports yellow rather than green, which is expected on a single node, because replica shards have nowhere else to live. Indexing and search are unaffected.

Production starting point

Around nineteen pods in total. OpenSearch keeps the chart’s four dedicated role pools, Redis keeps its replicas, and the web and worker deployments are scaled out.

image:
  registry: docker.io
  repository: geoknowledgehub/geo-knowledge-hub
  tag: "v1.7.0.dev16"

invenio:
  hostname: "invenio.local"
  # Disabled on purpose. The init job runs `rdm-records demo` without loading
  # the vocabularies first, and it overlaps with the commands you run in the
  # post-install setup. Everything it does is covered there.
  init: false
  demo_data: false

  extraConfig:
    INVENIO_SITE_UI_URL: "https://invenio.local:8080"
    INVENIO_SITE_API_URL: "https://invenio.local:8080/api"
    INVENIO_APP_ALLOWED_HOSTS: '["invenio.local:8080", "invenio.local"]'

    INVENIO_CACHE_REDIS_URL: "redis://invenio-redis-master:6379/0"
    INVENIO_CELERY_RESULT_BACKEND: "redis://invenio-redis-master:6379/2"

    # Bug: The chart injects RATELIMIT_STORAGE_URI but flask-limiter
    #      reads RATELIMIT_STORAGE_URL. Set both to be safe.
    INVENIO_RATELIMIT_STORAGE_URI: "redis://invenio-redis-master:6379/3"
    INVENIO_RATELIMIT_STORAGE_URL: "redis://invenio-redis-master:6379/3"

  # Must be a map of "email: password"
  default_users:
    "admin@invenio.org": "admin123"

  # DOI provider
  datacite:
    enabled: true
    username: "GKH.EXAMPLE"
    password: "GKH.PASSWORD"
    existingSecret: "" # required, see the note below
    prefix: "10.5072"  # datacite test prefix
    testMode: "True"

ingress:
  enabled: true
  class: "nginx"

# The chart defaults to 6 web replicas with 6 uWSGI processes each. These are
# lower so the profile still fits on one Minikube node. Raise them on a real
# cluster once you know your traffic.
web:
  replicas: 2
  uwsgi:
    processes: 4
    threads: 4

worker:
  replicas: 2
  concurrency: 4

postgresql:
  enabled: true
  auth:
    username: invenio
    password: "dbpassword123"
    database: invenio

redis:
  enabled: true
  auth:
    enabled: false

rabbitmq:
  enabled: true
  auth:
    password: "mqpassword123"

opensearch:
  enabled: true

  # Chart defaults give two master, two data, two coordinating and two ingest
  # nodes. Only the data nodes need correcting: the chart pairs a 1024m heap
  # with a 1536Mi limit, which the JVM exhausts before Lucene native memory
  # is accounted for. See the note below.
  data:
    heapSize: 1024m
    resources:
      requests:
        cpu: 500m
        memory: 2Gi
      limits:
        cpu: "1"
        memory: 3Gi

persistence:
  enabled: true
  size: 5G
  storage_class: "standard"

flower:
  enabled: true

The passwords, the invenio.local hostname and the DataCite test prefix are still placeholders from the quickstart. Replace them, and move the credentials into Kubernetes secrets, before this goes anywhere real.

From where these environment variables are coming from?

The environment variables defined in the app.extraConfig block are used to override the default InvenioRDM configuration. The settings defined there are basically the same as the ones defined in the invenio.cfg file, but as environment variables prefixed with INVENIO_.

datacite.existingSecret must be set to an empty string

The chart ships with invenio.datacite.existingSecret: "datacite-secrets" as its default. The secret template is only rendered when that value is empty.

So if you enable DataCite and set username/password while leaving the default in place, no secret is ever created, but the web and worker deployments still reference datacite-secrets through a secretKeyRef. The pods then fail to start with CreateContainerConfigError.

Set existingSecret: "" to let the chart create the secret from your username/password, or pre-create your own secret and point existingSecret at its name.

Why both files override the OpenSearch sizing

The bundled OpenSearch sub-chart ships data.heapSize: 1024m next to a container memory limit of 1536Mi. The JVM then starts with -Xmx1024m and -XX:MaxDirectMemorySize=512m, which reserves the whole limit before metaspace, thread stacks and Lucene native memory are accounted for. Under indexing load the container crosses its limit and the kernel kills the JVM (OOMKilled, exit code 137). The node restarts, shard recovery moves onto the surviving node, and that one is killed as well.

From the application side this appears as search engine timeouts while running invenio rdm-records fixtures. They look intermittent, because a request only fails when it reaches a node that is being restarted.

The rule is to give every OpenSearch container at least twice the heap it is configured with, which is why both files above set the resources explicitly rather than relying on the chart defaults.

5. Add the Helm repository

Once you have create your my-values.yaml file, you need to add the Helm repository:

helm repo add helm-invenio https://inveniosoftware.github.io/helm-invenio/
helm repo update

Verify the chart is available:

helm search repo helm-invenio

You should see something like:

NAME                  CHART VERSION  APP VERSION  DESCRIPTION
helm-invenio/invenio  0.11.1         12.0.10      Turn-key research data management platform.

6. Install the chart

Now, you can install the chart:

helm install invenio helm-invenio/invenio \
  --namespace invenio \
  --values my-values.yaml \
  --timeout 60m

The --timeout 60m is intentional: pulling the OpenSearch and Postgres images, plus initialising the database and creating indices on first boot, can take 10-20 minutes depending on your network / machine performance.

7. Watch the rollout

Now, you can watch the rollout:

kubectl get pods -n invenio -w

Wait until every pod reaches Running.

Database errors before the setup are expected

While the chart is coming up you will see the invenio-web pods restarting, and their logs will be full of errors like:

psycopg2.errors.UndefinedTable: relation "pages_page" does not exist
[pid: 8|app: 0|req: 1/1] HEAD /ping => generated 0 bytes in 46 msecs (HTTP/1.1 500)

This is expected. The database schema does not exist yet, so the web pods are running against an empty database and their /ping readiness probe returns HTTP 500, which makes Kubernetes restart them.

They settle as soon as you run invenio db create in the post-install setup. It only becomes a problem if the errors persist after that.

8. Reach the application

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 hostname invenio.local:8080, because that is the value of INVENIO_SITE_UI_URL and INVENIO_APP_ALLOWED_HOSTS in the my-values.yaml. If you serve the instance on a different hostname or port, change those settings to match it.

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.

Next, open https://invenio.local:8080 in your browser and accept the self-signed certificate warning. You will be able to log in once the post-install setup has created the admin user:

email: admin@invenio.org
password: admin123

9. Run the post-install setup

The chart starts the application but does not seed everything the GEO Knowledge Hub needs (custom roles, fixtures, file location). Once the application is up and running, you need to run the post-install setup.