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:
capabilitiesrestricts the app;[]grants none, and omitting it leaves the legacyVITE_GEOLIBRE_CAPABILITIES(or the default full grant) in force.- A non-empty
interfaceobject replaces the legacyadmin-profile.jsonwhole; fields are not merged. An omitted, empty ({}), or invalid interface leaves the legacy profile eligible. plugins.registryUrlsets the plugin registry.allowed,blockedandsideloadgate external plugin loads and installs;defaultActiveseeds activation in fresh projects.services,sharing,geolens,osmandbranding.appNameoverride the matchingGEOLIBRE_*deployment settings.sharing.embedOrigins: []turns the embed API off.branding.welcome: falsesuppresses the first-launch wizard.basemaps.regional: falsedisables the regional basemaps (Amap and Tencent, served from mainland China). See Regional basemaps.ai.enabled: truepoints the assistant at the same-origin/aiproxy;falseremoves any operator-configured AI proxy (a provider a user enters in Settings is unaffected).ai.modelpicks 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:
- final
deployment.jsonpolicy (including container environment overrides) - runtime environment (
window.__GEOLIBRE_DEPLOYMENT_ENV__) - 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
capabilitiessection, 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.