This directory contains the Geo Engine backend service: a Rust-based API server that implements the project's geospatial data APIs, data management, and core processing logic.

• Language: Rust
• Build tool: cargo (part of the Rust toolchain)
• Purpose: serve geospatial APIs, data processing, and storage integration

• Install Rust (stable toolchain) and cargo — see https://rustup.rs/
• GDAL (>= 3.8.4) and its development headers (libgdal-dev on Debian/Ubuntu)
• Proj (>= 9.4) and its development headers (libproj-dev on Debian/Ubuntu)
• A PostgreSQL database (if using the PostGIS extension for geospatial storage)

You may want to use our Development Container for a pre-configured environment with all dependencies.

just backend run — builds and runs the backend server with development configuration. See just backend build for just building without running.

Create Settings.toml or environment variables (database connection, bind address, API keys) as required by your environment. Cf. Settings-default.toml for all available configuration options.

• Format code: just backend fmt
• Run Clippy lints: just backend lint
• Run unit and integration tests: just backend test

The OpenAPI specification for the public API is available at the repository root: openapi.json.

• Use RUST_LOG to control runtime logging verbosity (e.g. RUST_LOG=debug).
• Many common development tasks are exposed via the top-level justfile.

Please run Clippy with cargo clippy --all-targets --all-features before creating a pull request.

We use SQLFluff to lint our SQL files.

You can install it with pip install sqlfluff.

To lint all SQL files, run sqlfluff lint. This will also be checked in our CI.

There is a VSCode extension available. This helps to format the files.

Please provide tests with all new features and run cargo test before creating a pull request.

Edit Settings-test.toml for environment-specific test parameters.

For running the PostgreSQL tests, you need to have it installed. Furthermore, you need to create a default user geoengine with the password geoengine.

postgres psql --host=localhost --user=geoengine << EOF
\set AUTOCOMMIT on
CREATE USER geoengine WITH PASSWORD 'geoengine' CREATEDB;
CREATE DATABASE geoengine OWNER geoengine;
\c geoengine
CREATE EXTENSION postgis;
EOF

During development, you can use the following setting in your Settings.toml to clean the database on server startup:

[postgres]
clear_database_on_start = true

For running the NFDI/GFBio ABCD data providers (GfbioAbcdDataProviderDefinition and GfbioCollectionsDataProviderDefinition) during development, you need to integrate the test data like this:

# delete existing data
psql --host=localhost --user=geoengine --dbname=geoengine -c \
  "DROP SCHEMA IF EXISTS abcd CASCADE;"

# insert data
cat test_data/gfbio/init_test_data.sql test_data/gfbio/test_data.sql | \
  psql --host=localhost --user=geoengine --dbname=geoengine --single-transaction --file -

For running the GBIF data provider (GbifDataProviderDefinition) during development, you need to integrate the test data like this:

# delete existing data
psql --host=localhost --user=geoengine --dbname=geoengine -c \
  "DROP SCHEMA IF EXISTS gbif CASCADE;"

# insert data
cat test_data/gbif/init_test_data.sql test_data/gbif/test_data.sql | \
  psql --host=localhost --user=geoengine --dbname=geoengine --single-transaction --file -

The file openapi.json contains the OpenAPI specification for the Geo Engine API. It is generated by using this CLI command:

cargo run --bin geoengine-cli -- openapi > openapi.json

Our CI checks if the OpenAPI spec is up to date.

For performance-critical features, we aim to provide benchmarks in the benches directory. If you plan on optimizing a feature of Geo Engine, please confirm it this way.

We use the expression/deps-workspace crate to manage dependencies for compiling expressions at runtime. This ensures that it is compatible with Geo Engine when linking against it.

It is important to keep the dependencies in sync with the Geo Engine dependencies. You can verify this by running the check-expression-deps test of the [geoengine-expression] crate.

cargo test --package geoengine-expression --test check-expression-deps

To update the expression dependencies, you can use the update-expression-deps.rs script located in the .scripts directory. This script helps to keep the dependencies in sync and up to date. Run it with:

chmod +x .scripts/update-expression-deps.rs

./.scripts/update-expression-deps.rs

Problem: When running Geo Engine or its tests you encounter one of the following (or similar) errors:

• Cannot allocate Memory (OS Error 12)
• Os { code: 11, kind: WouldBlock, message: "Resource temporarily unavailable" }

Solution: Adjust the system's max_map_count parameter:

• Temporary configuration:
  • sudo sysctl -w vm.max_map_count=262144
• Permanent configuration:
  • Add the following line to /etc/sysctl.d/local.conf
    • vm.max_map_count=262144
  • Reload the system config:
    • sudo sysctl --system