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.

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
Site banner	A site-wide announcement banner shown to every visitor (logged-in and anonymous) when enabled with non-empty text; pick a color (`info`, `success`, `warning`, or `destructive`). Visitors can dismiss it for the rest of their browser session

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 to 22; typical values 2 to 4 for global views, 10 to 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
Require Email Verification	`email_verification_required` (admin setting, not read from `.env`; default: true). Self-registered accounts must confirm their email before first login; delivery requires a configured SMTP channel (see Configuration Reference -> Outbound notifications)
Login-as-Landing Page	`LANDING_FIRST` (default: false). Redirects unauthenticated visits to `/` to the login page instead of the catalog
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, plus upload size and file-extension limits. The default is local filesystem (Docker volumes); production deployments commonly switch to S3-compatible object storage.

Setting	Maps to
Storage backend	`STORAGE_PROVIDER`: `local`, `s3`, or `azure`
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`
Max Storage per User	`max_storage_bytes_per_user` (admin setting, not read from `.env`; default: 0 = unlimited)
Max Datasets per User	`max_datasets_per_user` (admin setting, not read from `.env`; default: 0 = unlimited)
Upload max size	`UPLOAD_MAX_SIZE_MB` (default: 500)
Allowed extensions	`UPLOAD_ALLOWED_EXTENSIONS`

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 CORS origins and the API rate limits.

Setting	Maps to
CORS origins	`CORS_ALLOWED_ORIGINS`: comma-separated list of frontend origins allowed to call the API
Global rate limit	`global_rate_limit` (admin setting; default 60 requests/second)
Semantic search rate limit	`semantic_search_rate_limit` (admin setting; default 30 requests/min)
Basemap proxy rate limit	`basemap_proxy_rate_limit` (admin setting; default 120 requests/min)

The login rate limit lives on the Auth tab (login_rate_limit, default 5 attempts/min), not here.

CORS_ALLOWED_ORIGINS defaults to empty (no cross-origin browser access). A wildcard * is not honored. Because GeoLens sends credentialed CORS responses (Access-Control-Allow-Credentials: true), the browser spec forbids pairing them with a wildcard, so the middleware rejects * and you must list exact origins (comma-separated). Set them explicitly for any browser client served from a different origin than the API.

Outbound notification channels (SMTP email and webhooks for signup, ingest, and health events) are environment-only — their credentials are secrets and never stored in the settings database, so they do not appear in this tab. See Configuration Reference -> Outbound notifications.

AI

The AI tab toggles AI chat across GeoLens — the map builder panel, the dataset-detail Ask AI assistant, and the read-only map viewer — and configures the upstream LLM provider. The AI feature toggle ships enabled, but AI is inert until a provider API key is configured — with no key, AI endpoints return unavailable.

Setting	Maps to
Anthropic API key	`ANTHROPIC_API_KEY` (write-only in UI)
Anthropic model	`LLM_MODEL` (default: `claude-sonnet-5`)
Max AI Tokens per User per Day	`max_ai_tokens_per_user_per_day` (admin setting, not read from `.env`; default: 0 = unlimited)
OpenAI-compatible API key	`OPENAI_API_KEY` (write-only in UI)
OpenAI-compatible base URL	`OPENAI_BASE_URL`: for non-OpenAI endpoints (Azure, local servers)
OpenAI-compatible model	`OPENAI_MODEL` (default: `gpt-4o`)
AI feature toggle	Database-stored; when off, the AI chat panel is hidden for all users

There is no explicit provider-selection variable: the active provider is derived from which key is configured. If ANTHROPIC_API_KEY is set, GeoLens uses Anthropic; otherwise it falls back to the OpenAI-compatible path (OPENAI_API_KEY + OPENAI_BASE_URL).

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.

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.