Skip to content

Deployment Policy

deployment.json is a single, versioned file that describes the client-facing settings of a GeoLibre deployment: which capabilities users have, which interface elements are visible, which plugins may load, the curated service library, sharing endpoints, and branding.

Loading

The web and Jupyter builds fetch deployment.json from the app's base URL (<base>/deployment.json) before the first render. Desktop reads its config-dir file first (see Desktop); only an absent file or a failed read falls back to that web URL. The selected policy is resolved before the first render. No policy applies when the selected file is absent (404 or an HTML fallback page), not JSON, or of an unknown version. An unreachable web file or a fetch that takes more than 3 seconds also yields no policy. In those cases the app uses the next client configuration source.

Every build ships a deployment.json stub containing null, which means no policy, so static hosts answer the startup fetch instead of logging a 404. To apply a policy on a static host, replace that file in the published output; on Docker the entrypoint overwrites it on every boot. On desktop the stub is the bundled web fallback, so a config-dir file still takes precedence.

The recommended deployment input is a versioned deployment.json. On Docker, the entrypoint validates the mounted source, applies nonblank environment overrides field by field, and writes the generated public policy on every boot (see Docker). The client then resolves settings in this order: final policy, window.__GEOLIBRE_DEPLOYMENT_ENV__, then build environment.

Availability: Runtime policy delivery, desktop config-dir loading, and Docker enforcement first shipped in v3.3.0. Older Docker images and desktop releases ignore deployment.json; use v3.3.0 or later (the ghcr.io/opengeos/geolibre:latest image is rebuilt from main).

The previous admin-profile.json and VITE_GEOLIBRE_CAPABILITIES inputs are legacy, still honoured. They remain fallbacks where the primary policy does not specify a usable section; this documentation does not remove them.

What each section does today:

  • capabilities restricts the app; [] grants none, and omitting it leaves the legacy VITE_GEOLIBRE_CAPABILITIES (or the default full grant) in force.
  • A non-empty interface object replaces the legacy admin-profile.json whole; fields are not merged. An omitted, empty ({}), or invalid interface leaves the legacy profile eligible.
  • plugins.registryUrl sets the plugin registry. allowed, blocked and sideload gate external plugin loads and installs; defaultActive seeds activation in fresh projects.
  • services, sharing, geolens, osm and branding.appName override the matching GEOLIBRE_* deployment settings. sharing.embedOrigins: [] turns the embed API off.
  • branding.welcome: false suppresses the first-launch wizard.
  • basemaps.regional: false disables the regional basemaps (Amap and Tencent, served from mainland China). See Regional basemaps.
  • ai.enabled: true points the assistant at the same-origin /ai proxy; false removes any operator-configured AI proxy (a provider a user enters in Settings is unaffected). ai.model picks the proxy's model.

The client parser is lenient and section-based. Invalid sections, including capabilities with unknown names, are dropped with a warning; other valid sections survive. Capabilities then fall back to runtime or build environment, or the default full grant. Docker source validation is strict and fails boot before overrides can repair an invalid input file.

{"version":1,"capabilities":["data:add","export:data"],"interface":{"enabled":true,"level":"intermediate","lock":true}}

For capability details and Docker route enforcement, see Deployment Capabilities and Self-Hosting: container policy enforcement.

Example

{
  "version": 1,
  "capabilities": ["project:edit", "data:add", "processing:run", "export:data", "plugins:install", "settings:manage"],
  "interface": {
    "enabled": true,
    "level": "intermediate",
    "lock": true,
    "hiddenDataSources": ["arcgis"],
    "hiddenPlugins": ["plugin-a"],
    "hiddenMenus": ["help"],
    "hiddenMenuItems": ["project.print"]
  },
  "plugins": {
    "registryUrl": "https://plugins.example.com/registry.json",
    "allowed": ["acme-tools"],
    "blocked": ["bad-plugin"],
    "sideload": false,
    "defaultActive": ["acme-tools"]
  },
  "services": {
    "builtins": true,
    "catalog": [
      {
        "id": "city-wms",
        "name": "City WMS",
        "kind": "wms",
        "category": "Municipal",
        "fields": { "url": "https://maps.example.com/wms", "version": "1.3.0", "opacity": 0.8, "transparent": true }
      }
    ]
  },
  "basemaps": { "regional": false },
  "sharing": {
    "shareUrl": "https://projects.example.com",
    "collabUrl": "wss://relay.example.com",
    "embedOrigins": ["https://portal.example.com"]
  },
  "geolens": { "url": "same-origin" },
  "osm": { "overpassUrl": "https://overpass.example.com/api/interpreter" },
  "ai": { "enabled": true, "model": "gpt-5-mini" },
  "branding": { "appName": "Acme Maps", "welcome": false }
}

Point your editor at the schema for completion and validation by adding "$schema": "https://raw.githubusercontent.com/opengeos/GeoLibre/main/schema/deployment.schema.json". GeoLibre ignores $schema.

Field reference

Every section and every field is optional except version. An absent section means "not specified": the next source in the precedence chain applies.

Top level

Field Type Meaning
version 1 Policy format version. Documents with any other version are ignored.

capabilities

An array of the capability names from Deployment Capabilities: project:edit, data:add, processing:run, export:data, plugins:install, settings:manage. Omit it to grant all capabilities; [] grants none.

interface

Field Type Meaning
enabled boolean Whether UI profile filtering is active (default true).
level beginner | intermediate | advanced Experience-level preset that seeds the hidden lists.
lock boolean Prevent users changing the profile in Settings.
hiddenDataSources, hiddenPlugins, hiddenMenus, hiddenMenuItems string[] Explicit hidden ids, overriding the preset.

plugins

Field Type Meaning
registryUrl string Plugin marketplace registry URL, absolute or relative to the app.
allowed string[] External plugin ids allowed to load. Omit for any; [] for none.
blocked string[] External plugin ids never loaded.
sideload boolean Allow installing from a manifest URL, zip, directory or project file (default true).
defaultActive string[] Plugin ids active in a fresh project.
openPanel string Panel id to open automatically on startup in a fresh project.
fileAccess object (plugin id → string[]) Literal absolute file paths each plugin may read; honoured only from a machine-wide policy file.

services

Field Type Meaning
builtins boolean false hides the built-in starter services.
catalog object[] Curated entries: id, name, kind (wms, wfs, wmts, xyz, arcgis, csw), optional category, and non-empty fields (string, number or boolean values).

basemaps

Field Type Meaning
regional boolean false disables the regional basemaps (Amap and Tencent), whose tiles are served from mainland China. Default true.

sharing

Field Type Meaning
shareUrl string Projects server URL (https://…; plain http:// only on localhost/127.0.0.1), or off to remove Share and the Gallery.
collabUrl string Live collaboration relay (wss://…; plain ws:// only on loopback).
embedOrigins string[] Origins allowed to drive a framed app (https://host), or * for any.

geolens

Field Type Meaning
url string Default GeoLens server (https://…; plain http:// only on loopback in the container), same-origin, or off.

osm

Field Type Meaning
overpassUrl string Overpass API interpreter URL for the OSM downloader and the OSM-backed God's Eye View feeds, such as https://overpass.example.com/api/interpreter: https:// on a DNS name or IPv4 address, no credentials, query, or fragment. Unset uses the public relay https://tiles.geolibre.app/overpass. Set it to keep area-of-interest queries on an instance you run or trust. The viewer's browser calls it directly, so it must be reachable from every viewer and send CORS headers (Access-Control-Allow-Origin for the GeoLibre origin, on error responses too), or be served on the GeoLibre origin. Plain http:// is accepted only on loopback (localhost, 127.0.0.1, [::1]), which means the viewer's own machine. Only the desktop app can reach such an endpoint: the container is the enforcement point and rejects plain http:// at boot, and on a web build served by any other host the client parser still accepts it, but the page's CSP (connect-src allows https: only) blocks the request. Unlike the public relay, a configured endpoint never falls back to api.openstreetmap.org, and an invalid value (which also drops the osm section) disables OSM downloads instead of using the public relay.

ai

Field Type Meaning
enabled boolean Expose the same-origin AI assistant route (default false).
model string Default assistant model id.

branding

Field Type Meaning
appName string App name in the toolbar and tab title, at most 60 characters.
welcome boolean false skips the first-launch welcome wizard.

Omitted versus empty

For capabilities and plugins.allowed, leaving the field out and writing [] mean opposite things. Omitted means "no restriction from this file"; [] means "nothing is granted/allowed".

Plugin precedence

An id in blocked is never loaded, even if it is also in allowed. When allowed is present, any non-bundled external id not in it is not loaded.

The evaluator checks sideload permission first, then blocked, then allowed. Bundled drop-ins under public/plugins/ are exempt from allowed and sideload, but still honor blocked. Built-in plugins are not external plugins and are not governed by these load restrictions.

For URL plugins, GeoLibre must fetch plugin.json to learn the id. A denied id never has its entry or stylesheet fetched or its code imported. Denials appear as external plugin load issues.

With sideload: false, manifest URL, zip and directory controls disappear and programmatic installs refuse. Project-supplied manifest URLs produce no trust prompt and cannot be trusted into settings. Previously installed URLs stay in settings, but only URLs recognized by permitted entries in the current registry may load (plus bundled drop-ins). If that registry is unavailable, installed URLs fail closed; bundled drop-ins can still load. Existing file-installed archives and additional directories cannot load. Each skipped configured directory is reported as an external plugin load issue without reading its contents. Each settings-triggered or forced scan checks current registry membership before reusing a previous load. A previously loaded URL that is no longer approved is unloaded, including when the registry is unavailable. Its installed URL and integrity pin remain until the user uninstalls it; registry approval returning does not silently trust changed code. Denied registry entries are hidden in the marketplace, but their installed source URLs remain removable in Settings.

defaultActive marks permitted, loaded external plugins for activation in a fresh project. It does not override a saved project's active plugin list and does not allow a denied plugin to load. URL updates preserve these deployment defaults for later fresh projects. Without a plugins section, existing loading and activation behavior is unchanged.

openPanel names a registered dockable right-panel or floating panel to open automatically when the application starts with a fresh project. It opens once startup is ready: plugins have loaded, the map is ready, any ?url= project has settled, and any native startup restore has finished (or failed). A restore that never completes keeps the panel closed (a console warning notes when it outlasts the startup gate). A ?url= project that loads is a saved project, so the panel does not open for it; the wait only matters when that load fails and the app falls back to a fresh project.

The panel never opens in a saved project, in the read-only viewer preset, or when side panels are hidden (?maponly, ?panels=hidden, ?hidePanels=true).

If the panel registers asynchronously during plugin activation, it opens once it registers. A right-panel target is skipped if another right panel became active while it was waiting (opened by the user or by a plugin activating at startup), and a console warning names it; a floating target still opens. A warning is also logged if the panel has not registered after 10 seconds. A right panel the user opens before startup is ready (for example during a slow restore) is not protected: if the deployment panel is already registered at that point, it opens in its place. The S3 Browser opened by the Settings → Startup option is a startup plugin too: whichever of the two panels opens last keeps the right dock.

Like every other field, an invalid openPanel (blank or not a string) makes the desktop parser drop the whole plugins section, including blocked, allowed and sideload, with a console warning naming the field. The container validator rejects the whole file instead, so validate desktop policy files against schema/deployment.schema.json.

fileAccess configures an administrator-side allowlist of literal absolute file paths per plugin id (e.g. {"my-plugin": ["/etc/geolibre/app.cfg"]}). To prevent unprivileged tampering, fileAccess is honoured exclusively from a machine-wide deployment.json (%ProgramData%/GeoLibre/ on Windows, /etc/geolibre/ on Linux, /Library/Application Support/GeoLibre/ on macOS); if defined in a per-user policy, it is ignored with a console warning. The allowlist gates the native readAllowedFile(pluginId, path) API on the desktop, where both the requested path and allowlist entries are canonicalised to prevent path traversal and symlink escapes. Reads enforce a 50 MB size limit. Plugins call app.readAllowedFile(path); the host binds the calling plugin's id. Plugins still share one unsandboxed webview, so this scopes well-behaved plugins to their own list rather than isolating a hostile one.

Plugin policy is client-side enforcement only, not a server security boundary: a modified client can bypass it. It does not provide signing or sandboxing.

Regional basemaps

The Change basemap and New project dialogs offer a collapsed Regional section with basemaps served from inside mainland China (Amap and Tencent), for users there whom the default providers serve poorly. A project file can name one of them as its basemap, so GeoLibre asks before loading it when a project is opened (from a file, a URL, a share link, drag and drop, a startup or project-history restore, or a host framing the app, including the Jupyter widget): the map shows the default basemap until the user picks Load or Use default basemap. The answer holds for the rest of the session, so opening the same basemap again (or a host re-sending its project) does not ask twice, and a framing host keeps seeing its own basemap in the state the app reports back. Closing the dialog without either button keeps the default basemap but is not remembered, so the next project naming that basemap asks again. Picking the basemap in the UI later counts as Load.

These do not ask: a basemap the user picks in the UI, or that a plugin, script or the assistant sets on their behalf (code the user installed or ran); a new project, a template, an undo step or a duplicate; a project the iframe embed API loads for an embedOrigins origin the deployment allowlisted; and a live collaboration session, a deliberate exception, since its basemap is shared state of a session the user chose to join. Only a regional basemap the user picked or accepted is remembered and restored at the next launch.

basemaps.regional: false (or GEOLIBRE_DISABLE_REGIONAL_BASEMAPS=1 on Docker, or VITE_GEOLIBRE_DISABLE_REGIONAL_BASEMAPS=1 at build time) removes them entirely:

  • the Regional section disappears from both dialogs, and the Basemaps control plugin no longer lists its mainland-China providers (Amap, Tencent and Tianditu);
  • a project that names one opens on the default basemap without a prompt, with a short notice saying why;
  • plugins, scripts and the assistant cannot set one either, and a regional basemap remembered from an earlier session is not restored.

The prompt and the switch cover the built-in regional basemaps (the geolibre://regional-basemap/... values of a project's basemapStyleUrl). A custom style URL, raster basemaps stacked from the Basemaps control, and any XYZ or WMS layer are ordinary project data: a project can still point one at any tile server, in mainland China or elsewhere, the same way it can name any other data source.

Like the rest of the policy this is client-side: it stops GeoLibre from requesting those tiles, not a modified client.

Precedence between sources

The order, highest first, is:

  1. final deployment.json policy (including container environment overrides)
  2. runtime environment (window.__GEOLIBRE_DEPLOYMENT_ENV__)
  3. build-time environment

The legacy admin-profile.json is still honoured for the interface only when the selected policy has no non-empty, valid interface section.

Versioning

New fields are additive and keep version: 1. A document with any other version is ignored with a console warning.

Validation

The client parser is lenient and works section by section:

  • A section with any invalid field, or any unknown key inside it, is dropped whole with a console warning. The other sections still apply.
  • An unknown capability name drops the entire capabilities section, so the deployment falls back to environment settings or defaults (it does not grant nothing). Check the console if a restriction seems missing.
  • Unknown top-level keys are ignored with one warning.
  • Non-JSON content or a non-object is ignored silently.

The container validates strictly: it rejects unknown keys, duplicate or invalid ids, service ids that collide after trimming, and numeric service field values beyond the safe-integer range, none of which JSON Schema alone can all express.

Desktop

A machine-wide deployment.json takes precedence: when %ProgramData%\GeoLibre\deployment.json (Windows), /etc/geolibre/deployment.json (Linux) or /Library/Application Support/GeoLibre/deployment.json (macOS) exists, it is the whole desktop policy and the per-user file below is not read. Use it when users must not be able to edit the policy; it is the only source that can grant plugins.fileAccess.

Otherwise, place deployment.json in Tauri's <app_config_dir> (see UI Profiles for the legacy profile locations). For the standard org.geolibre.desktop application identifier, the paths are:

OS Policy path
Linux $XDG_CONFIG_HOME/org.geolibre.desktop/deployment.json, or ~/.config/org.geolibre.desktop/deployment.json when XDG_CONFIG_HOME is unset
macOS ~/Library/Application Support/org.geolibre.desktop/deployment.json
Windows %APPDATA%\org.geolibre.desktop\deployment.json (normally C:\Users\<user>\AppData\Roaming\org.geolibre.desktop\deployment.json)

These follow Tauri's app config directory. Sandboxed installations may resolve the directory inside their sandbox; custom builds with a different application identifier use that identifier instead.

The read_deployment_policy command returns raw UTF-8 text, or null when the file is absent. A leading UTF-8 BOM is accepted by the parser. The selected policy is applied before the first render, including capability restrictions, without rebuilding the app. Restart GeoLibre after changing the file; changes are not watched.

An existing config-dir file is authoritative, even if empty, malformed or of an unsupported version: it yields no policy rather than falling back to a bundled or web file. Config-dir and web policies are never merged. When the file is absent, GeoLibre fetches <base>/deployment.json instead. Other read errors (including permission failures) produce a console warning in every build and fall back to that same web file. Unsupported versions also warn in every build. With no file in either location, existing behavior is unchanged.

A non-empty, valid policy interface replaces the legacy profile whole; an absent, empty, or dropped invalid interface leaves the legacy profile eligible. The config directory is user-writable: this is desktop provisioning, not a security boundary or server-side enforcement.

Docker

The image writes the generated public file to /usr/share/nginx/html/deployment.json on every boot, served at /deployment.json with Cache-Control: no-store, Content-Type: application/json and X-Content-Type-Options: nosniff. The source file is selected by GEOLIBRE_DEPLOYMENT_FILE (for example /etc/geolibre/deployment.json); mount it read-only there, never over the generated output. With no source or overrides, the image writes {"version":1}, which adds no capability restriction.

The source file is strictly validated before any environment overrides are applied. Nonblank GEOLIBRE_* values then override their corresponding fields; blank values count as unset. Invalid input stops boot and cannot be repaired by an override.

docker run --rm -p 8080:80 \
  -v "$PWD/deployment.json:/etc/geolibre/deployment.json:ro" \
  -e GEOLIBRE_DEPLOYMENT_FILE=/etc/geolibre/deployment.json \
  -e GEOLIBRE_CAPABILITIES=data:add,export:data \
  ghcr.io/opengeos/geolibre:latest

Configuration changes take effect on the next container start; they do not require rebuilding the image.

Variable Policy field
GEOLIBRE_CAPABILITIES capabilities: comma-separated names, or none for no grants
GEOLIBRE_SERVICES_FILE services.catalog
GEOLIBRE_BUILTIN_SERVICES=off services.builtins: false
GEOLIBRE_DISABLE_REGIONAL_BASEMAPS basemaps.regional: 1/true sets false, 0/false sets true
GEOLIBRE_SHARE_URL sharing.shareUrl
GEOLIBRE_COLLAB_URL sharing.collabUrl
GEOLIBRE_EMBED_ORIGINS sharing.embedOrigins
GEOLIBRE_GEOLENS_URL geolens.url
GEOLIBRE_OVERPASS_URL osm.overpassUrl
GEOLIBRE_APP_NAME branding.appName: whitespace collapsed, cut to 60 characters
GEOLIBRE_AI_URL / GEOLIBRE_AI_MODEL ai.enabled: true / ai.model

The boot log has one Deployment policy: <path> from <VAR> = <value> line per override. Tokens never appear in it, and a query string or fragment on a URL is replaced with [redacted].

Invalid input stops the boot with an ERROR: line that names the JSON path (for example ERROR: GEOLIBRE_DEPLOYMENT_FILE capabilities[1] must be one of: ...), so nginx never starts with a weaker policy than you asked for. A file with ai.enabled: true also needs GEOLIBRE_AI_URL, GEOLIBRE_AI_PROXY_URL and GEOLIBRE_AI_PROXY_TOKEN, otherwise the boot fails.

GEOLIBRE_CAPABILITIES overrides the final policy's client grants at container generation time. The generated policy is what nginx enforces; build-time client grants alone do not configure nginx.

Public file, no secrets

deployment.json is served to every browser. Never put secrets in it. The AI proxy URL and token, the sidecar token, trusted proxies, Basic Auth and CSP stay in server environment variables and files.

Client hiding is not enforcement

Hiding or removing an interface element does not stop someone with browser devtools. Nginx enforcement applies only to the bundled Docker routes; it does not restrict desktop processing, browser WASM, separately exposed sidecars, or plugin execution. See Deployment Capabilities and Self-Hosting.