Quickstart on Minikube

This page walks you through a complete deployment of the GEO Knowledge Hub on a local Minikube cluster, end-to-end. The values used here are tuned for a single-node local cluster. For a real cluster, take this file as a starting point and adapt it with the parameters reference.

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

Prerequisites

• Minikube
• Helm 3
• Kubectl
• Roughly 6 vCPUs and 12 GB RAM free on your machine. The chart brings up Postgres, Redis, RabbitMQ and OpenSearch in addition to the Invenio web/worker pods.

1. Start the Minikube cluster

Start the Minikube cluster with the following command:

minikube start \
  --cpus 8 \
  --memory 12192 \
  --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.

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

invenio:
  hostname: "invenio.local"
  init: true
  demo_data: true

  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"

  default_users:
    - email: "admin@invenio.org"
      password: "admin123"
      active: true
      confirm: true

ingress:
  enabled: true
  class: "nginx"

# Scale down for local dev.
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
  auth:
    enabled: false

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

opensearch:
  enabled: true

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

flower:
  enabled: true

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_.

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 (and the install init job reports Completed).

8. Reach the application

The Minikube ingress controller is exposed on the cluster IP. Add an entry to /etc/hosts pointing invenio.local at it:

echo "$(minikube ip) invenio.local" | sudo tee -a /etc/hosts

Then port-forward the web service to a local port:

kubectl port-forward -n invenio svc/invenio-web 8080:80 --address 0.0.0.0

Open https://invenio.local:8080 in your browser. Log in with the default admin user (defined in the my-values.yaml file):

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.