Installation

GeoNinja can either be installed natively or in a Docker container. Both use cases require you to clone the GitHub repository first.

cd YOUR_PARENT_DIR
git clone https://github.com/hues-platform/geoninja

For the rest of these instructions, the location of the cloned repo will be assumed to be located at REPO_ROOT = YOUR_PARENT_DIR/geoninja.

Native installation

For the native installation instructions, we assume that you are using Anaconda for Python installation and dependency management. Alternative ways depending on your own local development setup viable as well if you adapt the steps accordingly.

Install Python and set up environment

Take a look at backend/pyroject.toml about which Python versions are supported and prepare a GeoNinja Python environment:

conda create --name geoninja python=3.13
conda activate geoninja

Since the project is configured using Poetry, make sure that you have it available:

conda install -c conda-forge poetry

Finally, you need to install both GeoNinja’s data pipeline and backend projects:

cd REPO_ROOT/data_pipeline
poetry install
cd REPO_ROOT/backend
poetry install

Run the data pipeline

Before GeoNinja can be used, the data pipeline needs to be run, downloading and preparing the geospatial maps which the app is based on.

cd REPO_ROOT/data_pipeline
python -m geoninja_dp.run

The pipeline places the prepared maps into the REPO_ROOT/backend/data/ directory, alongside data manifest files which detail the steps taken during data processing.

Run the backend

To run the backend, it needs to be invoced in a dedicated terminal where it will start listening for queries. The native code sequence for this is:

cd REPO_ROOT/backend
python -m uvicorn geoninja_backend.main:app --host 127.0.0.1 --port 8000

Alternatively, a launch configuration and dedicated task for this is included in the repository’s .vscode folder.

Run the frontend

To run the frontend, make sure to have node.js installed and available on your system. The frontend needs to be run in its own dedicated terminal via

cd REPO_ROOT/frontend
npm install
npm run dev

After that, GeoNinja is available at http://localhost:5173.

Docker installation

For the Docker installation, make sure to have a valid Docker installation on your system. For Windows users, we recommend Docker Desktop.

Set container configuration

We advise to reserve a reasonable amount of processing power for the container during the first installation of GeoNinja, around 16GB. If you are running Docker Desktop and have picked WSL2 during its installation, you would do this by editing (or creating) the file %userprofile%/.wslconfig and include the following settings:

[wsl2]
memory=14GB
swap=16GB

This can be reduced drastically after the data pipeline has concluded the first time that GeoNinja is launched.

Building the containers

cd REPO_ROOT
docker compose build

This will create three containers: geoninja_back, geoninja_front, and geoninja_dp, responsible for the backend, frontend, and the initial data pipeline.

Running via contianer

cd REPO_ROOT
docker compose up

The first time this is run, the data pipeline will be run automatically, downloading the maps and processing them for geospatial lookup. Afterwards, GeoNinja will be available at http://localhost:8080.