Validate the deployment (optional)

After the post-install setup, your instance is ready to use, and most people can stop there.

This page is for the times when you need to prove the deployment is really working well. The gkh validate drives a running instance over its API and UI and reports what does not work as expected. It covers Knowledge Packages, Knowledge Resources, drafts and file uploads, communities, search and DOI.

Prerequisites

You need a running instance, so finish either installation path first. You also need to have applied the post-install setup, so everything required (i.e., vocabularies, roles) is ready and available.

On your own machine, the only requirement is Python 3.12+ and uv.

1. Install the CLI

If you configured your instance with the GEO Knowledge Hub CLI, you already have this and can skip to the next step. Otherwise, install the CLI using:

uv tool install \
  --with "gkh-deploy[validation] @ git+https://github.com/geo-knowledge-hub/geo-deploy.git" \
  git+https://github.com/geo-knowledge-hub/geo-cli.git

After installation, confirm what are the plugins available on it:

gkh --version

It is expected you to see:

gkh-cli 0.1.0
  deploy: gkh-deploy 0.1.0
  validate: gkh-deploy 0.1.0

2. Create an API token

Most of the checks write to the API, so they need to authenticate as a valid user.

From the web interface of your instance: open your instance in a browser, click your avatar in the top right corner and go to Settings. Then, on the left sidebar, click on Applications. Under Personal access tokens, click New token, give it a name such as validation, and select all the available scopes. When you click Create, the token is shown once and never again, so copy it before leaving the page.

You can also mint one from the cluster, which is useful when there is no browser to hand:

kubectl exec -n invenio deploy/invenio-worker -c worker -- \
  invenio tokens create -n validation -u admin@invenio.org

3. Point it at your instance

Now that you have generated the token, you can use it in the GEO Knowledge Hub CLI to validate your instance. Run the validate run command, specifying the url and token:

gkh --url https://invenio.local:8080 --token <your token> validate run

Add --no-verify-tls when the certificate is self-signed, which it is if you followed the cluster preparation with Minikube.

The same three settings can come from the environment, so you do not have to repeat them:

GKH_BASE_URL=https://invenio.local:8080
GKH_API_TOKEN=<your token>
GKH_NO_VERIFY_TLS=true

They are also read from a .env file in the directory you run from. A flag on the command line wins over the environment, which wins over the file.

4. Run the checks

To validate all operations, use the command shown earlier:

gkh validate run

You can also run only part of the test suite. For example, to run the UI tests:

gkh validate run --suite ui

Or, if you prefer, only the API tests:

gkh validate run --suite api

The command exits with 0 when everything passes, 2 when no instance was given, and non-zero for any other failure, so it fits directly into a pipeline.

5. Include the checks that publish

Some checks create content that cannot be removed afterwards, such as publishing a record or minting a DOI. A published record cannot be deleted in InvenioRDM, and an administrator can only tombstone it later.

For that reason, these checks are skipped by default. Every other check creates drafts and deletes them when it finishes. To include the skipped operations, use the dedicated flag:

gkh validate run --allow-publish

Next steps

1) Try the REST API examples against your instance.

2) Review the parameters reference to fine-tune resource limits, autoscaling, and bundled-services credentials.