Manual installation

This page installs the GEO Knowledge Hub by writing the Helm values yourself and calling helm directly. Take this path when you want to author every value by hand, or when you cannot install Python tooling on the machine that drives the deployment. If you would rather have the values, the Secrets and the post-install script generated and checked for you, use the GEO Knowledge Hub CLI instead.

The following commands assume you have a cluster prepared as described in Prepare the cluster.

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

Standard (production)

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.

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

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

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

Next steps

1) Run the post-install setup. The chart starts the application but does not seed everything the GEO Knowledge Hub needs: the database schema, the file location, the GEO-specific roles, the administrator and the controlled vocabularies.

2) Open the instance on the address you set up when you prepared the cluster. You will be able to log in once the post-install setup has created the admin user:

email: admin@invenio.org
password: admin123

3) Validate the deployment to confirm every feature responds before you rely on it.