Local installation (Python)

The local Python install puts the application directly on your machine in a pipenv-managed virtual environment, while the supporting services (Postgres, Redis, RabbitMQ, OpenSearch) run as Docker containers. This is the right approach when you intend to implement new features or fix bugs in the codebase. You have hot-reload option and is quick to have it configured.

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

Prerequisites

• Git
• Python 3.9+
• Invenio CLI (Learn more)
• Docker Engine 20+ and Docker Compose plugin
• Node.js 21+ (the GEO Knowledge Hub build pipeline uses webpack)

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 GEO Knowledge Hub (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 three logical phases: install dependencies, set up the supporting services, and start the development server. Each phase maps to a single invenio-cli sub-command, run in the order below.

First, using one command we will install the Python and JavaScript dependencies required to build and run the application. Then, after the installation, it builds the JS and CSS bundles with webpack.

invenio-cli install

Once the dependencies and assets are ready, we can start and configure the service containers (i.e., Postgres, Redis, RabbitMQ, OpenSearch). This is done with the following command:

The configuration process here includes the creation of the database tables, the file storage location, the admin role, and the optional loading of demo records.

invenio-cli services setup

Finally, start the development server.

invenio-cli run

The application is now available at https://127.0.0.1:5000.

Next steps

1) Get familiarized with the platform by exploring the Knowledge Packages and Resource concepts as well as the Metadata schema

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

Or if you prefer, you can check the following sections other ways to build the GEO Knowledge Hub.