# How to Configure the Python Sidecar FastAPI Server for Offline Geoprocessing

> Configure the Python sidecar FastAPI server for offline geoprocessing in GeoLibre. Install extras, set environment variables, and verify server binding for efficient local data processing.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-02

---

**To configure GeoLibre's Python sidecar FastAPI server for offline geoprocessing, install the optional extras with `pip install "geolibre[all]"`, set the `GEOLIBRE_CONVERSION_ROOTS` environment variable to a local directory, and verify that the server binds to `127.0.0.1` with per-launch authentication tokens.**

GeoLibre is an open-source geospatial desktop application that uses a Python FastAPI sidecar for local processing. The sidecar, located in `backend/geolibre_server/`, runs entirely on `127.0.0.1` and is launched by the Tauri desktop wrapper. Configuring it for offline operation ensures that all vector, raster, and conversion workflows execute without external network dependencies.

## Install Optional Dependencies for Offline Processing

The FastAPI server defined in [`backend/geolibre_server/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/main.py) can only perform geoprocessing when the underlying Python libraries are available. These dependencies are not included in the base installation to keep the package lightweight.

Install the full set of processing backends using the `all` extra:

```bash

# Install all optional processing dependencies (GeoPandas, Shapely, rasterio, etc.)

pip install "geolibre[all]"

```

If you are using **conda**, install the base package from conda-forge first, then add the pip extras:

```bash
conda install -c conda-forge geolibre
pip install "geolibre[all]"

```

These extras provide the heavy lifting for algorithms like WhiteboxTools and GDAL bindings, which operate entirely on local data without requiring internet access.

## Configure Environment Variables for Offline Mode

### Set Local Conversion Roots

The conversion endpoints in [`backend/geolibre_server/geolibre_server/app/conversion.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/conversion.py) respect the `GEOLIBRE_CONVERSION_ROOTS` environment variable to determine where file conversion operations are permitted. By default, this points to `./data`, but for offline workflows you should explicitly set it to a local directory you control:

```bash
export GEOLIBRE_CONVERSION_ROOTS=/path/to/local/data

```

This prevents the server from attempting to access or write to network-mounted drives or remote URLs during format conversions (e.g., GDB to GeoParquet).

### Disable External Network Calls

The sidecar does not require external network access for its core algorithms. To guarantee offline operation, ensure the following configurations are in place:

- **Prevent remote URL fetching** – The FastAPI server respects the Jupyter configuration flag `disable_check_xsrf` defined in [`backend/geolibre_server/jupyter_server_config.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/jupyter_server_config.py). Because the server runs behind a loop-back token, XSRF checks are safely disabled.
- **Restrict to localhost** – The server binds exclusively to `127.0.0.1` via `c.ServerApp.ip = "127.0.0.1"` in the Jupyter configuration, ensuring no external hosts can reach the API.

## Verify Localhost Binding and Security Settings

The desktop app embeds the JupyterLab UI in an iframe with an origin of `tauri://localhost` (or `http://tauri.localhost` on Windows). The Content Security Policy (CSP) is defined in [`backend/geolibre_server/jupyter_server_config.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/jupyter_server_config.py) via the `_FRAME_ANCESTORS` tuple. This setting allows the Tauri shell to frame the Jupyter interface while keeping the server isolated from external traffic.

No modification is required for offline mode, but you can verify the configuration includes:

```python
c.ServerApp.ip = "127.0.0.1"

```

This ensures the FastAPI instance in [`main.py`](https://github.com/opengeos/GeoLibre/blob/main/main.py) is only accessible from the local machine, even when the host has active network interfaces.

## Launch the Sidecar Without External Proxies

In the Tauri native code ([`src-tauri/src/lib.rs`](https://github.com/opengeos/GeoLibre/blob/main/src-tauri/src/lib.rs)), the sidecar is launched using the built-in `uv run --project` command. For offline scenarios, ensure this launch command does not include `--proxy` flags or other network-dependent parameters:

```rust
// Example launch pattern in src-tauri/src/lib.rs
Command::new_sidecar("geolibre_server")
    .args(["--port", "0"]) // Random free port
    .env("GEOLIBRE_CONVERSION_ROOTS", "/local/data")
    .spawn()

```

The server starts on a random free port, and the desktop wrapper automatically embeds the URL `http://127.0.0.1:<port>/` together with the per-launch authentication token handled by the Rust launcher.

## Test Offline Geoprocessing Workflows

After starting GeoLibre in desktop mode, verify that processing algorithms execute without network access. The following Python code runs a Whitebox "buffer" algorithm on a local GeoJSON layer:

```python
from geolibre import Map

# Create a map – the embedded sidecar starts automatically

m = Map(center=(-100, 40), zoom=4)

# Add a local GeoJSON file (no network access required)

m.add_geojson("data/roads.geojson", name="Roads")

# Run the Whitebox buffer algorithm on the "Roads" layer

result = m.run_algorithm(
    "buffer",
    {"layer": "Roads", "distance": 500},
    timeout=120
)

print("Buffer created, layer IDs:", result["resultLayerIds"])

```

To confirm the server is truly offline, monitor network connections while the app is running:

```bash

# Linux/macOS: Check for established connections excluding localhost

sudo lsof -i -n -P | grep ESTABLISHED | grep -v 127.0.0.1

```

If the output is empty, the sidecar is operating without external network calls. If an algorithm attempts to download remote resources, it will raise `RuntimeError: offline environment – external fetch blocked`, confirming the offline guard is active.

## Summary

- **Install processing extras** with `pip install "geolibre[all]"` to enable local vector, raster, and conversion algorithms.
- **Set `GEOLIBRE_CONVERSION_ROOTS`** to a local directory to restrict file conversion operations to offline-accessible paths.
- **Verify localhost binding** in [`backend/geolibre_server/jupyter_server_config.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/jupyter_server_config.py) (`c.ServerApp.ip = "127.0.0.1"`) to ensure the FastAPI server only accepts local connections.
- **Launch via Tauri** without proxy flags in [`src-tauri/src/lib.rs`](https://github.com/opengeos/GeoLibre/blob/main/src-tauri/src/lib.rs) to prevent external network dependencies.
- **Test with local data** using Whitebox algorithms and monitor network connections to confirm offline isolation.

## Frequently Asked Questions

### Does the GeoLibre FastAPI sidecar require an internet connection to start?

No. The server binds to `127.0.0.1` and generates a per-launch authentication token, making it completely isolated to the local machine. It does not phone home or check for updates during startup, allowing it to launch and operate in fully air-gapped environments.

### What Python packages are included in the `geolibre[all]` extra?

The `all` extra includes GeoPandas, Shapely, rasterio, WhiteboxTools, and other geoprocessing libraries required by the endpoints in [`backend/geolibre_server/geolibre_server/app/main.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/main.py). These packages perform the actual spatial analysis locally without external API calls.

### How do I verify that no external network calls are being made?

Use system monitoring tools like `lsof` (Linux/macOS) or `netstat` (Windows) to inspect established connections while the app is running. Filter out localhost traffic (`127.0.0.1`); if no other connections appear, the sidecar is operating offline. Additionally, attempting to run algorithms on remote URLs will raise a `RuntimeError` indicating that external fetches are blocked.

### Can I customize the Content Security Policy for the embedded iframe?

Yes. The CSP settings in [`backend/geolibre_server/jupyter_server_config.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/jupyter_server_config.py) control which origins can frame the JupyterLab interface via the `_FRAME_ANCESTORS` tuple. The default configuration allows `tauri://localhost` for the desktop shell. You can modify this if you have customized the Tauri scheme, though this is not required for offline functionality.