How to Set Up the GeoLibre Development Environment from Source

Setting up GeoLibre from source requires Node.js 22+, the Rust toolchain, and Linux build dependencies, followed by cloning the repository, running npm install at the root, and launching either the web UI with npm run dev or the desktop client with npm run tauri:dev.

GeoLibre is an open-source geospatial visualization platform organized as a single npm workspaces monorepo containing a web application, Tauri-based desktop client, TypeScript libraries, and an optional Python FastAPI sidecar. To contribute features, fix bugs, or customize the application, you must set up the development environment from source. This guide walks through the exact commands and configuration files located in the opengeos/GeoLibre repository.

Prerequisites

System Requirements

Before cloning the repository, ensure your system meets the baseline requirements defined in docs/getting-started.md【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L68-L73】.

• Node.js version 22 or newer.
• Rust toolchain installed via rustup.rs (required for compiling the Tauri desktop client).
• Linux dependencies for Tauri v2, including libwebkit2gtk, libsoup, and gtk development packages.

Clone and Install Dependencies

Fork the repository on GitHub, then clone your fork locally. The contributing guidelines in CONTRIBUTING.md【/cache/repos/github.com/opengeos/GeoLibre/main/CONTRIBUTING.md#L11-L19】 recommend this workflow for all contributors.

git clone https://github.com/YOUR_GITHUB_USERNAME/GeoLibre.git
cd GeoLibre

Install JavaScript dependencies across all workspaces by running the following command at the repository root. This resolves dependencies declared in the root package.json【/cache/repos/github.com/opengeos/GeoLibre/main/package.json】.

npm install

# Alternative: bun install

Launch Development Servers

Web UI Development

To start the browser-based development server, run:

npm run dev

This executes a Vite dev server configured in apps/geolibre-desktop/vite.config.ts, making the application available at http://localhost:5173【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L96-L100】.

Desktop Client Development

To launch the Tauri-based native application, use:

npm run tauri:dev

This command requires the Rust toolchain and compiles the desktop shell while hot-reloading the TypeScript frontend. See the Run the desktop app section in docs/getting-started.md【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L62-L66】 for platform-specific notes.

Optional Components

Python Sidecar Setup

The Python sidecar provides heavy raster processing and optional vector tools. It lives in backend/geolibre_server and follows the bootstrap process documented in backend/geolibre_server/README.md【/cache/repos/github.com/opengeos/GeoLibre/main/backend/geolibre_server/README.md】.

cd backend/geolibre_server
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -e .
uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

Install selective extras for specific workflows using the syntax documented in the Optional extras section【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L95-L114】:

pip install -e ".[conversion]"   # or [vector], [raster], [ml]

Docker Container

The repository includes a Dockerfile that builds the web UI and serves it with Nginx. To build and run locally【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L106-L122】:

docker build -t geolibre .
docker run --rm -p 8080:80 geolibre

For a pre-built image from the GitHub Container Registry:

docker pull ghcr.io/opengeos/geolibre:latest
docker run --rm -p 8080:80 ghcr.io/opengeos/geolibre:latest

Production Builds

When ready to create distributable artifacts, use the build scripts defined in the root package.json:

• npm run build: Compiles the web version into apps/geolibre-desktop/dist/.
• npm run tauri:build: Generates native installers for Windows, macOS, and Linux.
• npm run tauri:build:native-duckdb: Builds the desktop client with a native DuckDB binary for enhanced local database support.

Output locations and build flags are documented in the Build section of docs/getting-started.md【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L84-L88】.

Environment Configuration

External imagery services and the 3-D globe view require API credentials configured via environment variables.

Create a .env.local file in apps/geolibre-desktop to store Google Maps, Mapillary, Protomaps, and other imagery API keys【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L90-L115】. For Cesium Ion integration, set either VITE_CESIUM_TOKEN or CESIUM_TOKEN【/cache/repos/github.com/opengeos/GeoLibre/main/docs/getting-started.md#L51-L57】.

These variables are read at build time and can also be injected at runtime via the Settings → Environment Variables UI.

Pre-Submission Checks

Before opening a pull request, run the quality gates outlined in CONTRIBUTING.md【/cache/repos/github.com/opengeos/GeoLibre/main/CONTRIBUTING.md#L21-L27】:

pre-commit run --all-files
npm run ci

These commands execute linting, type checking, and unit tests across all workspaces.

Summary

• GeoLibre is an npm workspaces monorepo requiring Node.js ≥22 and Rust for full desktop development.
• Clone your fork, then run npm install at the root to wire up all workspaces.
• Launch the web UI with npm run dev (port 5173) or the desktop app with npm run tauri:dev.
• Optionally start the Python sidecar from backend/geolibre_server for raster processing capabilities.
• Use npm run build for web artifacts and npm run tauri:build for native installers.
• Configure API keys in .env.local and run npm run ci before submitting changes.

Frequently Asked Questions

Do I need Rust to build the web version of GeoLibre?

No. Rust is only required for compiling the Tauri desktop client. To develop and test the browser-based UI, you only need Node.js 22 or newer. Run npm run dev to start the Vite server without any Rust toolchain dependencies.

What is the fastest way to install dependencies across all workspaces?

Run npm install (or bun install) once at the repository root. Because GeoLibre uses npm workspaces, this single command installs dependencies for the web app, desktop client, and all shared TypeScript libraries declared in the root package.json.

How do I run the Python sidecar for raster processing?

Navigate to backend/geolibre_server, create a Python virtual environment, install the package in editable mode with pip install -e ., and start the server with uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765. Install optional extras like [raster] or [conversion] if your workflow requires specific processing capabilities.

Where do I configure API keys for imagery services?

Create a .env.local file inside apps/geolibre-desktop and add keys for Google Maps, Mapillary, Protomaps, or Cesium Ion. The application reads these variables at build time, and they can be updated at runtime through the Settings → Environment Variables UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}