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.

Astuce

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 | | 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, the API rate limits, and the OGC API Features page-size ceiling.

| Setting | Maps to | |---------|---------| | CORS origins | CORS_ALLOWED_ORIGINS: comma-separated list of frontend origins allowed to make credentialed or native-route calls to 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) | | OGC Features max page size | ogc_items_max_page_size (admin setting, not read from .env; default 1000). Ceiling for limit on /api/collections/{id}/items; a larger limit is clamped silently |

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

CORS_ALLOWED_ORIGINS defaults to empty. That does not mean no cross-origin browser access: anonymous requests to the standards paths (/api/, /api/conformance, /api/collections*, /api/stac*, the DCAT routes) and to the vector and raster tile routes always get a credential-free Access-Control-Allow-Origin: *, so a public page on any origin can read the public catalog and draw public tiles with no setup. In 1.14.0 the anonymous catalog search routes (/api/search/datasets/, /api/search/facets/) are not on that list, so a cross-origin page searches through /api/collections/datasets/items?q= instead (tracked in geolens#1596).

The setting governs everything else: any request that carries a credential (X-Api-Key, Authorization, cookies) and every native application route. Those get credentialed CORS responses (Access-Control-Allow-Credentials: true), and the browser spec forbids pairing that 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 that signs in or sends a key.

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 | | Semantic Search | semantic_search_enabled (admin setting, not read from .env; default: false) | | Embedding Model | EMBEDDING_MODEL (default: text-embedding-3-small); the OpenAI-compatible model that generates search vectors | | Embedding Base URL | EMBEDDING_BASE_URL: a separate endpoint for embedding generation; falls back to OPENAI_BASE_URL when empty | | Embedding Dimensions | EMBEDDING_DIMS (default: 1536); Detect probes the configured model rather than making you look the number up |

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.

Enabling semantic search

Semantic search lives in the Semantic Search & Embeddings section of the AI tab. Turning the toggle on is only one of three steps, and it is the one that does the least on its own: with the toggle on and no embeddings generated, search silently falls back to keyword-only results.

1. Configure an OpenAI-compatible API key. Embeddings always go through the OpenAI-compatible path (OPENAI_API_KEY, optionally with OPENAI_BASE_URL for Azure, Ollama, or a local server) — an Anthropic key drives chat but cannot generate embeddings. Set Embedding Model to the model you want vectors from, then click Detect next to Embedding Dimensions to probe the model for its output size instead of entering it by hand. The button stays disabled until an OpenAI-compatible key is configured.

2. Turn on the Semantic Search toggle. This is semantic_search_enabled, an admin setting stored in the database and not read from .env. Putting SEMANTIC_SEARCH_ENABLED in your .env file has no effect.

3. Generate the embeddings. The Embedding Coverage panel shows how many catalog records currently have a vector (embedded_records/total_records). Click Generate Missing Embeddings to embed the records that lack one. Coverage has to be non-zero before semantic ranking changes any result.

Embeddings for new and edited records are generated as they are saved, so the backfill is a one-time catch-up for the catalog you already have. Use Regenerate All after changing the embedding model or dimensions: existing vectors were produced by the old model and are not comparable to new ones.

Note

Backfill is a manage_users operation, not manage_settings. An admin who can open the AI tab but lacks manage_users sees the model and toggle controls without the coverage panel or the backfill buttons.

The same three steps are available over the API: POST /api/settings/detect-embedding-dims/ probes the model, PUT /api/settings/ writes semantic_search_enabled, and GET /api/admin/embedding-stats/ plus POST /api/admin/backfill-embeddings/ report coverage and run the backfill (add ?force=true for the regenerate-all behavior). See Search & Discovery for what changes on the user-facing side once it is on.

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.

Attention

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