Settings Reference

The Admin → Settings page in the GeoLens web UI groups every system setting into seven tabs. This page orients you to what each tab controls and where to find the deeper documentation. The settings UI is the recommended interface for day-to-day configuration; the same values are also stored as .env variables and can be set at deploy time.

Tip

For per-environment-variable detail, see Configuration Reference — this page orients you to the seven Settings tabs and what each controls.

Replace https://geolens.example.com with your GeoLens instance’s URL in every example below.

General

The General tab covers instance branding and the default landing page. Settings here are cosmetic and operational defaults — none affect security or data.

Setting	Purpose
Site name	Brand name shown in the page title and the top nav
Default landing route	Where authenticated users land after login (/ for catalog, /maps for map list)
Admin contact email	Surfaced in error pages and the support footer

These map to environment variables documented under Configuration Reference → General. Persistent settings stored in the database take precedence over .env defaults.

Map

The Map tab controls the default map view and basemap configuration for new maps. Existing maps keep their per-map settings; this tab only seeds the defaults shown when a user creates a fresh map.

Setting	Purpose
Default basemap	Initial basemap for new maps (e.g., Carto Voyager, OpenStreetMap, none)
Default zoom level	Zoom 0–22; typical values 2–4 for global views, 10–14 for city scale
Default bounding box	Initial map extent in WGS84 (minx,miny,maxx,maxy)
Vector tile sources	Custom MVT sources available to map authors

The basemap list is configurable — you can add MapTiler, Mapbox, or self-hosted basemap servers. Configuration details are in Configuration Reference.

Auth

The Auth tab covers password policy, JWT expiry, registration, and OAuth providers. The OAuth Providers section is the entry point for the OAuth/OIDC setup walkthrough.

Setting	Maps to
JWT signing secret	JWT_SECRET_KEY (env-only — not editable in UI)
Access token lifetime	ACCESS_TOKEN_EXPIRE_MINUTES (default: 15)
Self-registration	REGISTRATION_ENABLED (default: false) — see User management
OAuth providers	Database-stored — see OAuth/OIDC setup

JWT_SECRET_KEY is set in .env and not editable through the UI. Rotating it invalidates all active JWT tokens (forcing every user to log in again) and re-encrypts every stored OAuth client secret — coordinate carefully with your OAuth provider rotation schedule.

Storage

The Storage tab controls where dataset files and processing artifacts are stored. The default is local filesystem (Docker volumes); production deployments commonly switch to S3-compatible object storage.

Setting	Maps to
Storage backend	STORAGE_BACKEND — local or s3
S3 endpoint	S3_ENDPOINT — full URL for S3-compatible providers
S3 bucket	S3_BUCKET — bucket name
S3 credentials	S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY (write-only in UI)
S3 region	S3_REGION

Backup off-site replication uses the same S3 credentials by default — see Backups & restore for BACKUP_S3_ENABLED and the dedicated backup destination configuration. Storage and backups can use different buckets if needed by setting backup-specific overrides.

Network

The Network tab covers HTTP-level configuration — upload size limits, allowed file extensions, and CORS origins.

Setting	Maps to
Upload max size	UPLOAD_MAX_SIZE_MB (default: 500)
Allowed extensions	UPLOAD_ALLOWED_EXTENSIONS
CORS origins	CORS_ORIGINS — comma-separated list of frontend origins allowed to call the API

CORS origins must be set explicitly for browser-based clients hosted on a different origin than the GeoLens API. The default * is permitted only when REGISTRATION_ENABLED=false and no API keys are issued — production deployments should always specify exact origins.

AI

The AI tab toggles the AI chat panel in the map builder and configures the upstream LLM provider. AI features are disabled by default; enabling them requires an API key from a supported provider.

Setting	Maps to
LLM provider	LLM_PROVIDER — anthropic or openai
Anthropic API key	ANTHROPIC_API_KEY (write-only in UI)
OpenAI API key	OPENAI_API_KEY (write-only in UI)
AI feature toggle	Database-stored — when off, the AI chat panel is hidden for all users

The AI chat is gated by both the use_ai_chat permission (see User management) and the global feature toggle. Disabling the toggle takes effect immediately for all sessions; users see the AI panel disappear on next page load.

Permissions

The Permissions tab is where the role-to-capability matrix is overridden. The default matrix is documented at User management → Roles & permissions; this tab lets you grant additional capabilities to non-admin roles or restrict capabilities further.

Caution

Lockout prevention: manage_users and manage_settings cannot be removed from the admin role or granted to non-admin roles. The system enforces this on save — attempting an unsafe change shows a validation error. See User management → Roles & permissions for the full matrix.

Common customizations:

• Restricted viewer: remove export from the viewer role for read-only audit-trail use cases
• Power editor: grant manage_collections to a custom curator role between editor and admin
• Locked-down public: disable use_ai_chat for all non-admin roles to control LLM API spend

Custom permission matrices persist in the database and survive restarts. To reset to the shipped defaults, use Config Ops → Reset Permissions in the admin UI.

See also

• User management & RBAC — the Permissions tab interacts with the role/permission matrix
• OAuth/OIDC setup — the Auth tab includes OAuth provider configuration
• Backups & restore — the Storage tab + backup-specific config (BACKUP_S3_ENABLED)
• Configuration reference — per-environment-variable deep documentation