Containerized installation (Docker)

The containerized installation, builds the GEO Knowledge Hub (GKH) into a Docker image and runs the application and all its services (i.e., Postgres, Redis, RabbitMQ, OpenSearch, nginx) as a Compose stack.

It is the right path when you want to try the platform locally without installing Python and the JavaScript toolchain on your host. The entire stack boots and tears down with two commands. However, please note that it is not the right path for active development, every code change requires rebuilding the application image, which takes minutes.

The workflow presented in the steps below is identical to InvenioRDM’s “Option 2: Containerized preview” path. We decided to keep it here to make things easier and have your own login policies.

Environment for development

If you want a setup to develop the GEO Knowledge Hub, adding new features or fixing bugs, please check the local Python install instead. It is the right path for you.

Prerequisites

• Git
• Invenio CLI (Learn more)
• Docker Engine 20+ and Docker Compose plugin

Please note that you do not need Python, Node.js or pipenv on the host. Everything will run inside containers.

1. Clone the GEO Knowledge Hub

1. Clone the repository:

   git clone https://github.com/geo-knowledge-hub/geo-knowledge-hub.git
   cd geo-knowledge-hub

2. Verify the project layout. After cloning, the repository should look like this:

   • .dockerignore
   • Directory.github/ CI workflows (GKH-specific)

     • …
   • .gitignore
   • .invenio Invenio-CLI configuration
   • AUTHORS.rst Project authors (GKH-specific)
   • CHANGES.rst Changelog (GKH-specific)
   • CONTRIBUTING.rst Contribution guide (GKH-specific)
   • DEVELOPING.rst Developer guide (GKH-specific)
   • Dockerfile Application Docker image
   • INSTALL.rst Installation reference (GKH-specific)
   • LICENSE
   • Pipfile Python requirements (pipenv)
   • Pipfile.lock Locked Python dependencies (committed in GKH)
   • README.rst
   • Directoryapp_data/ Application data (e.g. vocabularies)

     • …
   • Directoryassets/ Web assets (CSS, JS, LESS, JSX)

     • …
   • Directorydocker/ Example NGINX and uWSGI configuration

     • …
   • docker-compose.full.yml Full infrastructure stack
   • docker-compose.yml Backend services for local development
   • docker-services.yml Shared services for the Compose files
   • invenio.cfg Invenio application configuration
   • Directorysite/ GKH custom Python and JS code

     • …
   • Directorystatic/ Static files served as-is (e.g. images)

     • …
   • Directorytemplates/ Jinja template overrides

     • …

   The GKH is a standard InvenioRDM instance, which is why the rest of this guide reuses the upstream invenio-cli commands directly. There is no GKH-specific install procedure to learn.

   What GKH adds on top of InvenioRDM lives in a small set of well-known directories:

   • site/ - a local Python package. Hosts GKH’s custom services, resources, REST endpoints, React components.
   • invenio.cfg - instance configuration: authentication backends, search settings, branding, feature flags.
   • assets/ and templates/ - webpack sources and Jinja template overrides for any UI customization.
   • app_data/ - vocabularies and reference data loaded during invenio-cli services setup.

   Everything else, like records, communities, requests, user accounts, OAI-PMH, REST API comes from upstream InvenioRDM packages declared in Pipfile and pinned in Pipfile.lock.

2. Build, set up, run

The installation runs two logical phases: Build the Docker images and set up the services. Each phase maps to a single invenio-cli sub-command, run in the order below.

First, build the application Docker image and pull the service images (i.e., Postgres, Redis, RabbitMQ, OpenSearch, nginx).

invenio-cli containers build

Once the images are ready, put the application and services to run:

invenio-cli containers start

Then, set up the auxiliary services. This creates the database tables, search indices, default file storage location, admin role, and (optionally) loads demo records.

Two flags are useful here: pass --no-demo-data to skip the demo records, or --force to tear down and recreate everything from scratch when an earlier setup ended in a broken state.

invenio-cli containers setup

Once the command finishes, the application is available at https://127.0.0.1.

Use 127.0.0.1, not localhost

As with the local Python install, the Content Security Policy (CSP) headers served by the containerized stack expect the literal host 127.0.0.1. Visit https://127.0.0.1, not https://localhost.

You can change this configuration using env variables or the invenio.cfg file. Please refer to the InvenioRDM documentation for more details.

Also, if you prefer, all four steps presented above can be simplified into a single command by passing the --build, and --setup flags to containers start:

invenio-cli containers start --build --setup

Next steps

1) For production deployments, use the Kubernetes (Helm) path. The Docker stack here is a single-host preview, not a production topology.

2) Try the REST API examples against your new local instance.