The operator-facing environment variables for GeoLens, their defaults, and descriptions. Unless noted otherwise, set these in the .env file at the project root. A few quota and policy settings (flagged below) are managed only from the admin UI and are not read from .env.
Secret key for signing JWT tokens. Generate with openssl rand -hex 32. Must be at least 32 chars; the boot validator also rejects six well-known public placeholders (change-me, secret, etc.).
JWT_ALGORITHM
HS256
No
JWT signing algorithm
ACCESS_TOKEN_EXPIRE_MINUTES
15
No
JWT access-token lifetime in minutes
REFRESH_TOKEN_EXPIRE_DAYS
7
No
JWT refresh-token lifetime in days
GEOLENS_ADMIN_USERNAME
None (required)
Yes
Username for the automatically created admin account
GEOLENS_ADMIN_PASSWORD
None (required)
Yes
Password for the initial admin account
REGISTRATION_ENABLED
false
No
Whether self-registration is enabled. When false, only admins can create users.
EMAIL_VERIFICATION_REQUIRED
true
Admin UI only
Managed on the admin Auth tab — not read from .env. The value shown is the built-in default. Require new self-registered accounts to verify their email address before first login. Only relevant when REGISTRATION_ENABLED=true; requires a configured SMTP channel to deliver the verification email.
LANDING_FIRST
false
No
Redirect unauthenticated visits to / to the login page instead of the catalog (admin-overridable, “Login-as-Landing Page”). Useful for demo or lead-capture front doors.
PASSWORD_MIN_LENGTH
12
No
Minimum password length, enforced at every password entry point (register, change-password, admin create, SAML->local conversion).
PASSWORD_REQUIRE_CLASSES
3
No
Number of character classes required out of 4 (lowercase, uppercase, digit, symbol). Accepts 1 to 4.
Directory for temporary file storage during ingestion/export. Must be writable by the API runtime user (uid:gid 1001:1001). Mapped to upload_staging Docker volume.
Comma-separated list of allowed file extensions for upload. Note: an admin-saved override in Admin → Storage takes precedence over this default — existing deployments that customized the list must add new extensions (such as .parquet) there
PRESIGNED_MULTIPART_THRESHOLD_MB
100
No
Files larger than this (MB) use multipart presigned S3 URLs. Only applies when STORAGE_PROVIDER=s3.
INGEST_HTTP_TIMEOUT_SECONDS
300
No
GDAL_HTTP_TIMEOUT passed to ogr2ogr during remote-fetched ingest. Raise for very large datasets; lower for fail-fast ingest debugging.
MAX_STORAGE_BYTES_PER_USER
0
Admin UI only
Managed on the admin Storage tab — not read from .env. Per-user storage quota in bytes; 0 = unlimited. The value shown is the built-in default.
MAX_DATASETS_PER_USER
0
Admin UI only
Managed on the admin Storage tab — not read from .env. Per-user dataset-count quota; 0 = unlimited. The value shown is the built-in default.
GeoLens validates staging writability at startup and before export execution. Both UPLOAD_STAGING_DIR and ${UPLOAD_STAGING_DIR}/exports must allow write access for the API runtime user.
If this command fails, fix ownership/permissions on the mounted path or set UPLOAD_STAGING_DIR to a writable directory, then restart the API container.
Browser-facing app URL. Used for share links and OAuth redirect URIs.
PUBLIC_API_URL
http://localhost:8080/api
No
Externally-reachable API base URL. Used in OGC self/collection/next link hrefs.
PUBLIC_BASE_URL
None
No
Deprecated. Will be removed in a future release. Legacy alias for PUBLIC_API_URL. Use PUBLIC_API_URL instead. The application logs a deprecation warning at startup when this is set.
Output logs in structured JSON format. Recommended for production. Controls log output only; Swagger/ReDoc exposure is governed by ENVIRONMENT (see Deployment / Security posture).
Set STORAGE_PROVIDER=azure and configure a container plus one authentication path: either a connection string, or an account URL with an access key (leave the key unset to use managed identity / Entra ID).
Variable
Default
Required
Description
AZURE_STORAGE_CONTAINER
None
When azure
Blob container name (e.g. geolens-prod).
AZURE_STORAGE_CONNECTION_STRING
None
One auth path
Full connection string (also used for Azurite). Provide this orAZURE_STORAGE_ACCOUNT_URL.
Path to CA certificate file for database SSL verification.
DATABASE_POOL_PRE_PING
true
No
Enable connection pool pre-ping to detect broken connections before use. Adds slight latency per checkout. Set to false only if you need to disable this for a specific environment.
Optional email (SMTP) and webhook alerts for signup, ingest, and health events. Everything defaults to off, so existing deployments are unaffected until NOTIFICATIONS_ENABLED=true and at least one channel is configured. See Backups & Restore and Infrastructure & Monitoring for the operational context.
Variable
Default
Required
Description
NOTIFICATIONS_ENABLED
false
No
Master toggle. When false, all notification sends are a no-op regardless of channel config.
SMTP_HOST
None
No
SMTP server hostname. Configure together with SMTP_USERNAME, SMTP_PASSWORD, and SMTP_FROM_ADDRESS to enable the email channel.
SMTP_PORT
587
No
SMTP server port.
SMTP_USERNAME / SMTP_PASSWORD
None
No
SMTP credentials (secret; never rendered in logs).
SMTP_FROM_ADDRESS
None
No
From address for outbound email.
SMTP_USE_TLS
true
No
Use STARTTLS for the SMTP connection.
NOTIFICATION_WEBHOOK_URL
None
No
Incoming-webhook endpoint (Slack, Teams, or custom) that receives JSON notifications.
NOTIFICATION_WEBHOOK_SECRET
None
No
Optional HMAC signing secret for webhook payloads.
NOTIFICATION_ADMIN_EMAIL
None
No
Recipient for event alerts. Falls back to SMTP_FROM_ADDRESS when unset.
NOTIFY_ON_SIGNUP
false
No
Send an alert when a new account registers.
NOTIFY_ON_INGEST_COMPLETE
false
No
Send an alert when an ingest finishes successfully.
NOTIFY_ON_INGEST_FAILED
false
No
Send an alert when an ingest fails.
NOTIFY_ON_HEALTH_ALERT
false
No
Send an alert when the health check reports a degraded status (cooldown-deduplicated).
These are environment-only settings (not stored in the admin settings database) because the channel credentials are secrets.
When true, all admin-overridable settings are locked to their environment values. The PersistentConfig DB layer is bypassed for reads and returns 403 on writes. Use for hardened production deployments where operators want to prevent runtime configuration changes via the admin UI.
Deployment environment: development or production. When production, the API hides its docs (/api/docs and /api/redoc return 404) and sets the Secure flag on the OAuth session cookie. When unset, the posture falls back to LOG_JSON for backward compatibility. Set ENVIRONMENT=production on any public, TLS-terminated deployment.
These knobs matter when the frontend image fronts the API outside the bundled Compose stack (bare containers, Kubernetes, the community Helm chart). Under stock Docker Compose the defaults are correct and you can leave them unset.
Variable
Default
Required
Description
API_UPSTREAM
http://api:8000
No
Where the frontend’s nginx proxies /api, raster tiles, and embeds. Set to the API Service’s fully qualified name on Kubernetes. Trailing slashes are stripped.
NGINX_RESOLVER
first nameserver in /etc/resolv.conf, else 127.0.0.11
No
DNS resolver nginx uses to resolve API_UPSTREAM. Bare IPv6 resolvers are bracketed automatically.
CLIENT_MAX_BODY_SIZE
500m
No
Upload ceiling enforced by the frontend nginx. Invalid values fail fast at boot. Keep this at or above UPLOAD_MAX_SIZE_MB.
TRUSTED_PROXY_CIDRS
(empty)
No
Comma/space-separated CIDRs of proxies trusted to set X-Forwarded-For/-Proto (e.g. Cloudflare’s published ranges). Required for correct client IPs and anonymous raster rate limiting behind a load balancer or CDN. Empty treats the direct peer as the client.
For a non-AWS S3 backend, the API and worker derive AWS_S3_ENDPOINT, AWS_HTTPS, and AWS_VIRTUAL_HOSTING from the S3_* settings above automatically; you do not normally set them by hand.
GeoLens supports two AI subsystems: inference (chat, map generation, metadata drafts) and embeddings (semantic search). They can use different providers.
API keys are set exclusively via environment variables. All other AI settings (provider, model, base URL) can also be overridden at runtime from the admin Settings > AI tab.