# How to Set Up the GeoLibre Development Environment from Source

> Set up the GeoLibre development environment from source. Follow clear steps to install dependencies, clone the repo, and launch the UI using npm install and npm run dev.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: getting-started
- Published: 2026-07-29

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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](https://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`](https://github.com/opengeos/GeoLibre/blob/main/CONTRIBUTING.md)【/cache/repos/github.com/opengeos/GeoLibre/main/CONTRIBUTING.md#L11-L19】 recommend this workflow for all contributors.

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/package.json)【/cache/repos/github.com/opengeos/GeoLibre/main/package.json】.

```bash
npm install

# Alternative: bun install

```

## Launch Development Servers

### Web UI Development

To start the browser-based development server, run:

```bash
npm run dev

```

This executes a Vite dev server configured in [`apps/geolibre-desktop/vite.config.ts`](https://github.com/opengeos/GeoLibre/blob/main/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:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/README.md)【/cache/repos/github.com/opengeos/GeoLibre/main/backend/geolibre_server/README.md】.

```bash
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】:

```bash
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】:

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

```

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

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/CONTRIBUTING.md)【/cache/repos/github.com/opengeos/GeoLibre/main/CONTRIBUTING.md#L21-L27】:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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.