Configuration¶
GeoJibe reads ENCIVA_* environment variables. Typical files:
enciva.envin the working directory/etc/enciva/enciva.envon a packaged hostENCIVA_CONFIGpointing at another env file
Process environment wins over the file. This page lists intended settings. It does not include secrets.
The service binary and variable prefix are still enciva / ENCIVA_ on current installs.
The official CLI and Python SDK use a separate prefix:
GEOJIBE_URL is the installation origin (no trailing slash). GEOJIBE_CONFIG_DIR optionally overrides where the CLI stores config.toml. See Public API and Command-line client.
Deployment¶
One GeoJibe binary serves Shared SaaS and self-hosted GeoJibe. Dedicated and On-Site are the same self-hosted software; see Deployment models.
| Name | Purpose | Default |
|---|---|---|
ENCIVA_DEPLOYMENT |
shared, dedicated (canonical self-hosted), or onsite (legacy self-hosted alias). Unknown values fail startup. |
onsite |
ENCIVA_PUBLIC_URL |
Canonical public URL for email links, OAuth callbacks, and redirects | unset (required on Shared; optional on self-hosted) |
Unset ENCIVA_DEPLOYMENT keeps the legacy On-Site alias and therefore unified self-hosted behavior: sign-in required, no public signup, no 3-Job limit, PUBLIC_URL optional.
Core¶
| Name | Purpose | Default | Required |
|---|---|---|---|
ENCIVA_LISTEN_ADDR |
HTTP listen address | 127.0.0.1:8080 |
No |
ENCIVA_DATA_DIR |
Working files, database, sync state | ./data |
No |
ENCIVA_HOST_DATA_DIR |
Host Docker Engine path that corresponds to ENCIVA_DATA_DIR when GeoJibe runs in a container. The official compose file sets this automatically from the host bind path (default /var/lib/enciva). Empty on host .deb installs. |
unset | Docker only (automatic) |
ENCIVA_LOG_LEVEL |
debug, info, warn, error |
info |
No |
ENCIVA_SECRET_KEY |
Encrypts saved connection secrets | Generated file in the data dir if unset | Yes if you restore a database that already has secrets |
ENCIVA_SESSION_TTL |
Sign-in cookie lifetime | 24h |
No |
ENCIVA_COOKIE_SECURE |
Set true behind HTTPS. Self-hosted defaults to true when unset. Explicit false still overrides. |
false (Shared); true (self-hosted) |
No |
Example:
Uploads and jobs¶
| Name | Purpose | Default |
|---|---|---|
ENCIVA_MAX_UPLOAD_MB |
Upload size | 256 |
ENCIVA_MAX_ZIP_FILES |
Files inside a ZIP | 256 |
ENCIVA_MAX_UNCOMPRESSED_MB |
Unzipped size | 1024 |
ENCIVA_JOB_TTL |
How long one-off job files are kept | 60m |
Spatial runtime (Docker)¶
Convert, inspect, and Python run in a pinned GeoJibe GDAL image. Docker is required for that path.
| Name | Purpose | Default |
|---|---|---|
GDAL_IMAGE or ENCIVA_GDAL_IMAGE |
Pinned image digest (not :latest) |
ghcr.io/geojibe/geojibe-gdal:3.13.3-1@sha256:d1e968f6c09ea9951e345ad959707aa1f94ce236dc469055bd4628436d04922f |
ENCIVA_DOCKER |
Docker CLI | docker |
ENCIVA_GDAL_PULL |
Pull image at startup | true |
ENCIVA_GDAL_TIMEOUT |
Per-job processing timeout | 120s |
ENCIVA_CONTAINER_MEMORY |
Memory limit | 2g |
ENCIVA_CONTAINER_CPUS |
CPU limit | 2 |
ENCIVA_CONTAINER_PIDS |
PID limit | 128 |
ENCIVA_HOST_DATA_DIR |
Host path of ENCIVA_DATA_DIR for GDAL bind mounts when GeoJibe runs in Docker Compose. Set automatically by the official compose file. |
/var/lib/enciva on Compose |
SQL Transform uses the same container limits. DuckDB memory and threads are derived from ENCIVA_CONTAINER_MEMORY and ENCIVA_CONTAINER_CPUS. GDAL temporary files for a job are written to {job}/work/tmp/ inside the job workspace (CPL_TMPDIR=/workspace/work/tmp). The container still has a small /tmp tmpfs for process homedir files only. Job cleanup removes the temp directory with the workspace.
Raster Processing (preview)¶
Raster detection, Inspect, and Convert (including GeoTIFF → COG) stay on Standard. The optional raster_processing feature gates QGIS Server raster Map Preview only.
There is no Stripe add-on purchase in this phase. Enable it on a test or self-hosted install with:
ENCIVA_RASTER_PROCESSING_ENABLED=true
ENCIVA_QGIS_SERVER_URL=http://127.0.0.1:8090/ows/
ENCIVA_QGIS_DATA_DIR=/data
| Name | Purpose | Default |
|---|---|---|
ENCIVA_RASTER_PROCESSING_ENABLED |
Installation-wide raster_processing feature. Does not use billing_exempt. |
false |
ENCIVA_QGIS_SERVER_URL |
Internal QGIS Server WMS URL. Empty means preview is unavailable. | unset |
ENCIVA_QGIS_DATA_DIR |
Path where the QGIS sidecar sees ENCIVA_DATA_DIR (used to inject MAP=). |
unset (host path) |
ENCIVA_QGIS_TIMEOUT |
Preview request timeout | 15s |
ENCIVA_QGIS_MAX_WIDTH |
Max WMS width | 2048 |
ENCIVA_QGIS_MAX_HEIGHT |
Max WMS height | 2048 |
ENCIVA_QGIS_CONCURRENCY |
In-process preview concurrency | 2 |
ENCIVA_QGIS_CONTAINER |
Host QGIS sidecar name used to run PyQGIS (docker exec, no extra container). Docker Compose does not set this; GeoJibe discovers the sibling qgis service in the same Compose project so two stacks can share one Docker host. |
geojibe-qgis (host .deb sidecar) |
ENCIVA_QGIS_PYTHON |
Optional host PyQGIS interpreter when QGIS is installed on the host instead of Docker | unset |
QGIS Server is a separate internal sidecar. Do not add QGIS to the pinned GDAL image. Publish it on loopback only. Dedicated installs can use deploy/geojibe-qgis.service / deploy/qgis-sidecar.sh, which match the production sidecar:
docker run -d --name geojibe-qgis \
--memory 2g --cpus 1 \
--restart unless-stopped \
-p 127.0.0.1:8090:80 \
-v /var/lib/enciva:/data:ro \
qgis/qgis-server:ltr@sha256:f7d7cb68a8776f57ea4f06d6792345dad0bdee2bc713aae3773d167d2740d748
Set ENCIVA_QGIS_DATA_DIR=/data to match the container mount. The official qgis/qgis-server image serves WMS at /ows/ with MAP= (not the container root). Bind the port to loopback only. Do not proxy :8090 through Apache. GeoJibe injects MAP= server-side. The browser never talks to QGIS Server.
Scheduled Jobs and Convert never start or call QGIS Server. If QGIS is down, Inspect, Convert, and Jobs continue; Map Preview shows the raster extent and Raster visual preview is currently unavailable.
URL, HTTP/API, FeatureServer, S3 import¶
| Name | Purpose | Default |
|---|---|---|
ENCIVA_URL_IMPORT_ENABLED |
Allow URL and HTTP/API import | true |
ENCIVA_URL_CONNECT_TIMEOUT |
Connect timeout | 10s |
ENCIVA_URL_DOWNLOAD_TIMEOUT |
Download timeout | 2m |
ENCIVA_URL_HEADER_TIMEOUT |
Header timeout | 30s |
ENCIVA_URL_MAX_REDIRECTS |
Redirect cap | 5 |
ENCIVA_URL_DOWNLOAD_MAX_BYTES |
Size cap (0 = unset; then the upload cap is used) | unset |
ENCIVA_FEATURESERVER_IMPORT_ENABLED |
Allow FeatureServer import | true |
ENCIVA_FEATURESERVER_TIMEOUT |
Import timeout | 10m |
ENCIVA_FEATURESERVER_MAX_FEATURES |
Feature cap | 2000000 |
ENCIVA_S3_IMPORT_ENABLED |
Allow S3 import | true |
ENCIVA_S3_TIMEOUT |
Import timeout | 10m |
ENCIVA_AZURE_BLOB_IMPORT_ENABLED |
Allow Azure Blob import | true |
ENCIVA_AZURE_BLOB_TIMEOUT |
Azure Blob import/upload timeout | 10m |
ENCIVA_AZURE_BLOB_MAX_BYTES |
Max Azure Blob download size (0 uses the URL download limit) |
0 |
ENCIVA_GOOGLE_CLIENT_ID |
Google OAuth client ID for Drive Source/Destination | unset |
ENCIVA_GOOGLE_CLIENT_SECRET |
Google OAuth client secret. Never logged. | unset |
ENCIVA_GOOGLE_DRIVE_TIMEOUT |
Drive download/upload timeout | 10m |
ENCIVA_GOOGLE_DRIVE_MAX_BYTES |
Max Drive download size (0 uses the URL download limit) |
0 |
Google Drive uses ENCIVA_PUBLIC_URL + /auth/google-drive/callback as the OAuth redirect URI. Missing Google OAuth credentials or a missing ENCIVA_PUBLIC_URL disables the connector; GeoJibe still starts. Do not derive the callback from the request Host header.
Sync¶
| Name | Purpose | Default |
|---|---|---|
ENCIVA_QFIELD_SYNC_ENABLED |
Show/run QFieldCloud sync | true |
ENCIVA_MERGIN_SYNC_ENABLED |
Show/run Mergin Maps sync | true |
ENCIVA_QFIELDCLOUD_CLI |
qfieldcloud-cli path |
/opt/enciva/runtime/qfield/.venv/bin/qfieldcloud-cli |
ENCIVA_GEODIFF_BIN |
GeoDiff binary | /usr/local/bin/geodiff |
ENCIVA_MERGIN_PYTHON |
Mergin Python | /opt/enciva/runtime/mergin/.venv/bin/python3 |
ENCIVA_MERGIN_DBSYNC |
Mergin db-sync script | /opt/enciva/runtime/mergin/db-sync-2.1.1/dbsync_daemon.py |
ENCIVA_SYNC_TIMEOUT |
One sync cycle | 10m |
ENCIVA_SYNC_LIST_TIMEOUT |
Project listing | 60s |
Sync tools run on the GeoJibe process host, not in the isolated GDAL worker. On a .deb install that is the Linux host (geojibe-setup runs deploy/install-sync-runtime.sh). On Docker Compose the same tools are installed in the application image at the same default paths. Missing binaries produce Synchronization runtime is unavailable.
Optional AI authoring¶
| Name | Purpose | Default |
|---|---|---|
ENCIVA_LLM_ENABLED |
Enable Transform/Job AI authoring | false |
ENCIVA_LLM_API_KEY or OPENAI_API_KEY |
API key | unset |
ENCIVA_LLM_MODEL |
Model name | gpt-4o-mini |
ENCIVA_LLM_BASE_URL |
OpenAI-compatible base URL | https://api.openai.com/v1 |
ENCIVA_LLM_TIMEOUT |
Request timeout | 120s |
Disabled unless enabled and a key is set. Job execution does not call the model.
First administrator¶
Used only when the user database is empty:
| Name | Purpose | Required |
|---|---|---|
ENCIVA_BOOTSTRAP_ADMIN_USERNAME |
First username | With password |
ENCIVA_BOOTSTRAP_ADMIN_PASSWORD |
First password (no shipped default) | Yes, to bootstrap |
ENCIVA_BOOTSTRAP_ADMIN_NAME |
Display name | No |
The first sign-in asks for a password change.
The bootstrap administrator on the installation account is SuperAdmin. SuperAdmin is not an account role and cannot be granted by signup, profile edits, Stripe, or PATs.
| Name | Purpose | Required |
|---|---|---|
ENCIVA_SUPERADMIN_USERNAMES |
Comma-separated usernames to grant SuperAdmin at startup | No |
Existing databases: migration 24 grants SuperAdmin to the oldest administrator on the installation account only. Customer admins are not promoted. If no SuperAdmin exists, the oldest installation administrator is granted one at startup. Operators can grant or revoke SuperAdmin from Admin → Account → Users. The last SuperAdmin cannot be removed.
Outbound email¶
SMTP is a server setting used for Job Notifications and Shared account verification. Job editors only choose the recipient. Email is disabled unless both host and from address are set.
| Name | Purpose | Default |
|---|---|---|
ENCIVA_SMTP_HOST |
SMTP hostname | unset |
ENCIVA_SMTP_PORT |
SMTP port | 587 |
ENCIVA_SMTP_USERNAME |
SMTP login | unset |
ENCIVA_SMTP_PASSWORD |
SMTP password | unset |
ENCIVA_SMTP_TLS |
starttls, tls, or none |
starttls |
ENCIVA_SMTP_FROM |
From address | unset |
ENCIVA_SMTP_FROM_NAME |
From display name | GeoJibe |
Shared Stripe billing¶
Used only when ENCIVA_DEPLOYMENT=shared. Checkout, Customer Portal, and webhooks stay disabled until all four values are set. Price IDs and secrets are server-side only.
| Name | Purpose | Default |
|---|---|---|
ENCIVA_STRIPE_SECRET_KEY |
Stripe secret key | unset |
ENCIVA_STRIPE_WEBHOOK_SECRET |
Stripe webhook signing secret | unset |
ENCIVA_STRIPE_PRICE_STANDARD_MONTHLY |
Standard monthly Price ID | unset |
ENCIVA_STRIPE_PRICE_STANDARD_ANNUAL |
Standard annual Price ID | unset |
ENCIVA_STRIPE_PRICE_DEDICATED_MONTHLY |
Dedicated monthly Price ID (Shared only) | unset |
ENCIVA_STRIPE_PRICE_DEDICATED_ANNUAL |
Dedicated annual Price ID (Shared only) | unset |
ENCIVA_STRIPE_PRICE_ONSITE_ANNUAL |
On-Site annual Price ID (Shared only) | unset |
ENCIVA_LICENSE_SERVER_URL |
license.geojibe.com base URL for Shared provisioning |
unset |
ENCIVA_LICENSE_SERVER_ADMIN_TOKEN |
Server-to-server admin token for the license service | unset |
ENCIVA_LICENSE_DEDICATED_MAX_ACTIVATIONS |
Activation limit for new Dedicated licenses | 1 |
ENCIVA_LICENSE_ONSITE_MAX_ACTIVATIONS |
Activation limit for new On-Site licenses | 1 |
Dedicated and On-Site Price IDs are optional. Shared Standard Checkout stays available when they are unset. Both Dedicated Price IDs map to the same product type (dedicated) and the same technical entitlements; billing interval only changes the Stripe subscription period. Dedicated Checkout requires a server-validated hosting_region (US, CA, GB, or EU). That value is the GeoJibe-operated hosting region, not the customer billing country. Stripe still collects the customer billing address for tax. On-Site does not use hosting_region. The license-server admin token is never sent to browsers or self-hosted installs.
Checkout return URLs use ENCIVA_PUBLIC_URL. Customer Portal returns to {ENCIVA_PUBLIC_URL}/account?billing=portal. Self-hosted license Checkout returns to {ENCIVA_PUBLIC_URL}/account?licenses=success.
Customer Portal (Stripe Dashboard)¶
Creating a Portal Session does not enable management features by itself. In the test-mode Stripe Dashboard go to Settings → Billing → Customer portal (or Billing → Customer portal) and configure:
- Activate the Customer Portal if it is not already on.
- Payment methods — allow customers to update their payment method.
- Billing information — allow customers to update name, address, and tax IDs.
- Invoice history — allow customers to view and download invoices.
- Cancel subscription — leave this on. Prefer cancel at period end (not immediately) so GeoJibe can keep access until
current_period_end. After a scheduled cancel, Stripe lets the customer renew/undo until the period ends — that is the undo-cancellation path GeoJibe relies on. - Switch plan — this is off by default. Turn it on and add the hosted Standard product with both Prices:
ENCIVA_STRIPE_PRICE_STANDARD_MONTHLYandENCIVA_STRIPE_PRICE_STANDARD_ANNUAL. Leave Update quantities off (quantity stays 1). Choose the proration behavior you want for Monthly ↔ Annual; GeoJibe does not implement plan switching itself. - Do not enable seat/quantity updates. Add the Dedicated monthly, Dedicated annual, and On-Site annual prices so customers can cancel those subscriptions in the Portal. Do not offer Standard ↔ Dedicated/On-Site as a plan switch. If you enable Dedicated monthly ↔ annual switching, GeoJibe still treats both prices as the same Dedicated product.
GeoJibe Account → Plan & Billing only displays subscription state and opens this Portal. Cards, invoices, cancellation, and Monthly ↔ Annual switching stay in Stripe.
See Job Notifications and Deployment models.