Configuration Reference

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.

Database

| Variable | Default | Required | Description | |---|---|---|---| | POSTGRES_DB | geolens | Yes | PostgreSQL database name | | POSTGRES_USER | geolens | Yes | PostgreSQL superuser username | | POSTGRES_PASSWORD | None (required) | Yes | PostgreSQL superuser password. Generate with openssl rand -base64 24. | | POSTGRES_HOST | localhost | No | Database hostname (application default localhost). Docker Compose sets this to db, the database service name. | | POSTGRES_PORT | 5432 | No | Database port (internal). The host-mapped port is configured separately. |

Authentication

| Variable | Default | Required | Description | |---|---|---|---| | JWT_SECRET_KEY | None (required) | Yes | 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. |

Upload settings

| Variable | Default | Required | Description | |---|---|---|---| | UPLOAD_MAX_SIZE_MB | 500 | No | Maximum upload file size in megabytes | | UPLOAD_STAGING_DIR | /app/staging | No | 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. | | UPLOAD_ALLOWED_EXTENSIONS | .zip,.gpkg,.geojson,.json,.csv,.tif,.tiff,.xlsx,.xls,.parquet | No | 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. |

UPLOAD_STAGING_DIR writability requirement

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.

Quick validation command:

docker compose exec api sh -lc '\
  dir=${UPLOAD_STAGING_DIR:-/app/staging}; \
  mkdir -p "$dir/exports" && \
  touch "$dir/.geolens-write-test" "$dir/exports/.geolens-write-test" && \
  rm -f "$dir/.geolens-write-test" "$dir/exports/.geolens-write-test"'

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.

Job queue

| Variable | Default | Required | Description | |---|---|---|---| | PROCRASTINATE_SCHEMA | catalog | No | PostgreSQL schema for the Procrastinate job queue tables | | INGEST_JOBS_RETENTION_DAYS | 30 | No | Days to retain finished ingest job records before pruning; 0 disables pruning. |

Public URLs

| Variable | Default | Required | Description | |---|---|---|---| | PUBLIC_APP_URL | http://localhost:8080 | No | 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. |

CORS

| Variable | Default | Required | Description | |---|---|---|---| | CORS_ALLOWED_ORIGINS | "" | No | Comma-separated list of exact origins allowed to make credentialed cross-origin API requests (a literal * is rejected). Required when the frontend is served from a different domain than the API. Anonymous reads of the standards and tile routes are unaffected; see Settings -> Network. |

Tile serving & CDN

| Variable | Default | Required | Description | |---|---|---|---| | TILE_CACHE_TTL | 300 | No | Tile cache TTL in seconds | | TILE_SIGNING_SECRET | None (falls back to JWT_SECRET_KEY) | No | Secret for signing tile request URLs. Set separately when you want to rotate tile secrets without invalidating JWT tokens. | | CDN_BASE_URL | None | No | CDN origin URL for tile delivery. When set, the frontend requests tiles from this URL instead of the API. |

Logging

| Variable | Default | Required | Description | |---|---|---|---| | LOG_JSON | false | No | Output logs in structured JSON format. Recommended for production. Controls log output only; Swagger/ReDoc exposure is governed by ENVIRONMENT (see Deployment / Security posture). | | LOG_LEVEL | INFO | No | Log level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL. |

Storage provider

| Variable | Default | Required | Description | |---|---|---|---| | STORAGE_PROVIDER | local | No | Storage backend for uploaded files. Options: local, s3, azure. | | S3_ENDPOINT | None | When s3 | S3-compatible endpoint URL. Leave unset for AWS S3. For MinIO: http://minio:9000. | | S3_BUCKET | None | When s3 | S3 bucket name. | | S3_ACCESS_KEY_ID | None | When s3 | S3 access key ID. | | S3_SECRET_ACCESS_KEY | None | When s3 | S3 secret access key. | | S3_REGION | us-east-1 | No | S3 region. | | S3_ALLOW_HTTP | false | No | Allow HTTP (non-TLS) connections to S3 endpoint. Enable for local MinIO. | | S3_ADDRESSING_STYLE | auto | No | S3 addressing style. Options: auto, path, virtual. Use path for MinIO. |

Azure Blob Storage

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 or AZURE_STORAGE_ACCOUNT_URL. | | AZURE_STORAGE_ACCOUNT_URL | None | One auth path | Account blob endpoint, https://<account>.blob.core.windows.net. | | AZURE_STORAGE_ACCOUNT_KEY | None | With account URL + key auth | Storage account access key. Leave unset (with AZURE_STORAGE_ACCOUNT_URL set) to authenticate via managed identity / Entra ID. |

Managed database / SSL

| Variable | Default | Required | Description | |---|---|---|---| | DATABASE_URL_OVERRIDE | None | No | Full PostgreSQL connection URL for managed databases (RDS, Cloud SQL). Overrides individual POSTGRES_* variables. | | DATABASE_SSL_MODE | prefer | No | Database SSL mode. Options: disable, prefer, require, verify-full. | | DATABASE_SSL_CA_CERT | None | When verify-full | 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. | | DB_USE_EXTERNAL_POOLER | false | No | Enable external connection pooler mode (PgBouncer, RDS Proxy). Disables prepared statements. |

Connection pool tuning

These variables control the SQLAlchemy connection pool. Ignored when DB_USE_EXTERNAL_POOLER is true.

| Variable | Default | Required | Description | |---|---|---|---| | DB_POOL_SIZE | 10 | No | Maximum number of persistent connections in the pool. | | DB_MAX_OVERFLOW | 3 | No | Maximum number of additional connections beyond DB_POOL_SIZE. Tuned down from SQLAlchemy’s default to fit the connection budget below. | | DB_POOL_TIMEOUT | 30 | No | Seconds to wait for a connection from the pool before raising an error. | | DB_POOL_RECYCLE | 1800 | No | Seconds after which a connection is recycled (replaced). Prevents stale connections with managed databases. | | TILE_POOL_MIN_SIZE | 2 | No | Minimum connections in the dedicated asyncpg tile query pool. | | TILE_POOL_MAX_SIZE | 10 | No | Maximum connections in the dedicated asyncpg tile query pool. |

Connection budget

The per-process pool defaults are sized so the core services fit a single PostgreSQL with max_connections = 80 (set in db/postgresql.conf). Each API worker process opens three pools: the SQLAlchemy pool, the asyncpg tile pool, and a Procrastinate connector used to enqueue jobs.

| Process | SQLAlchemy (DB_POOL_SIZE + DB_MAX_OVERFLOW) | Tile pool | Procrastinate | Worst-case | |---|—:|—:|—:|—:| | API (per uvicorn worker) | 10 + 3 = 13 | 10 | 3 | 26 | | Worker | 10 + 3 = 13 | — | 3 | 16 | | Admin / psql / CLI | n/a | n/a | n/a | ~2 |

With two API workers (UVICORN_WORKERS=2, the recommended production sizing) the worst case is 2 × 26 + 16 + 2 = 70 of 80, leaving a 10-connection buffer. The single-worker development default uses 44. If you add API workers, lower TILE_POOL_MAX_SIZE or DB_POOL_SIZE — or raise max_connections — to stay inside the budget.

Cache

| Variable | Default | Required | Description | |---|---|---|---| | REDIS_URL | None | No | Redis/Valkey connection URL for cross-instance caching. Leave unset for in-memory caching (single-instance default). Example: redis://valkey:6379/0. |

Backup

These variables configure the default-on backup service. Off-site upload stays disabled until BACKUP_S3_ENABLED=true.

| Variable | Default | Required | Description | |---|---|---|---| | BACKUP_SCHEDULE | 0 2 * * * | No | Cron expression for automated database backups. Default: daily at 2:00 AM UTC. | | BACKUP_RETENTION_DAILY | 7 | No | Number of daily backups to retain locally. Must be an integer of at least 1; the container refuses to start otherwise. | | BACKUP_RETENTION_WEEKLY | 4 | No | Number of weekly (Sunday) backups to retain locally. Must be an integer of at least 1; the container refuses to start otherwise. | | BACKUP_S3_ENABLED | false | No | Enable off-site backup upload to S3-compatible storage. Uses S3_* credentials. | | BACKUP_MAX_AGE_MINUTES | 1560 | No | Freshness threshold for the backup container’s healthcheck, in minutes. The service reports unhealthy when the last fully successful backup cycle is older than this. Raise it to about 1.5x the interval for less-frequent BACKUP_SCHEDULE values. | | BACKUP_MEM_LIMIT | 512m | No | Memory cap for the backup container (the nightly pg_dump + tar peaks around 300 MB). |

Outbound notifications

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.

Worker

| Variable | Default | Required | Description | |---|---|---|---| | WORKER_CONCURRENCY | 1 | No | Number of jobs the background worker processes concurrently. | | WORKER_QUEUES | priority,ingest,raster | No | Comma-separated list of job queues the worker consumes, in priority order. | | WORKER_SHUTDOWN_TIMEOUT | 30 | No | Graceful shutdown timeout for the background worker in seconds |

Configuration lockdown

| Variable | Default | Required | Description | |---|---|---|---| | ENV_ONLY_CONFIG | false | No | 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 / security posture

| Variable | Default | Required | Description | |---|---|---|---| | ENVIRONMENT | (unset) | No | 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. |

Deployment knobs (running outside Docker Compose)

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.

AI & LLM

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.

Inference (chat / map generation)

| Variable | Default | Required | Description | |---|---|---|---| | ANTHROPIC_API_KEY | None | No | Anthropic API key. When set, Anthropic is the default inference provider. | | LLM_MODEL | claude-sonnet-5 | No | Default Anthropic model name (admin-overridable). | | MAX_AI_TOKENS_PER_USER_PER_DAY | 0 | Admin UI only | Managed on the admin AI tab — not read from .env. Per-user daily AI token budget; 0 = unlimited. The value shown is the built-in default. | | OPENAI_API_KEY | None | No | OpenAI-compatible API key. Used for inference when Anthropic key is absent, and always used for embeddings. | | OPENAI_MODEL | gpt-4o | No | Default OpenAI-compatible model name (admin-overridable). | | OPENAI_BASE_URL | None | No | Custom endpoint for OpenAI-compatible providers (Ollama, Groq, Together). Leave unset for default OpenAI. |

Embeddings (semantic search)

Embeddings always use the OpenAI-compatible API. Anthropic does not provide an embedding endpoint.

| Variable | Default | Required | Description | |---|---|---|---| | EMBEDDING_MODEL | text-embedding-3-small | No | Embedding model name (admin-overridable). | | EMBEDDING_DIMS | 1536 | No | Expected vector dimensions (admin-overridable, auto-detectable from admin UI). | | EMBEDDING_BASE_URL | None | No | Separate endpoint for embeddings. Falls back to OPENAI_BASE_URL if unset. |

Common provider configurations

Anthropic inference + OpenAI embeddings (recommended):

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

OpenAI for everything:

OPENAI_API_KEY=sk-...

Anthropic inference + Ollama embeddings:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=ollama          # any non-empty value
EMBEDDING_BASE_URL=http://ollama:11434/v1
EMBEDDING_MODEL=nomic-embed-text

Ollama for everything:

OPENAI_API_KEY=ollama          # any non-empty value
OPENAI_BASE_URL=http://ollama:11434/v1
OPENAI_MODEL=llama3
EMBEDDING_MODEL=nomic-embed-text

Host port mapping

These variables control which ports are exposed on the Docker host. They do not affect internal container communication.

| Variable | Default | Description | |---|---|---| | DB_PORT | 5432 | Host port for PostgreSQL. Set to 5434 in .env.example to avoid conflicts. | | API_PORT | 8000 | Host port for the FastAPI backend. Set to 8001 in .env.example. | | FRONTEND_PORT | 8080 | Host port for the frontend. |

Internal service ports

These are fixed inside Docker containers and are not configurable:

| Service | Port | Protocol | |---|---|---| | PostgreSQL (db) | 5432 | TCP | | FastAPI (api) | 8000 | HTTP | | Worker (worker) | 8001 | HTTP (health only) | | Titiler (titiler) | 8000 | HTTP | | Frontend (frontend) | 5173 | HTTP (Vite dev server) |

Docker volumes

| Volume | Purpose | Mount Point | |---|---|---| | pgdata | PostgreSQL data persistence | /var/lib/postgresql/data on db | | upload_staging | Uploaded file staging area | /app/staging on api |

Example .env file

# Database
POSTGRES_DB=geolens
POSTGRES_USER=geolens
POSTGRES_PASSWORD=secure-db-password

# Auth
JWT_SECRET_KEY=a1b2c3d4e5f6...  # Use: openssl rand -hex 32
GEOLENS_ADMIN_USERNAME=admin
GEOLENS_ADMIN_PASSWORD=secure-admin-password

# AI (optional; omit to disable AI features)
ANTHROPIC_API_KEY=sk-ant-...     # Inference (chat, map generation)
OPENAI_API_KEY=sk-...            # Embeddings (semantic search)

# Ports (non-default to avoid conflicts)
DB_PORT=5434
API_PORT=8001
FRONTEND_PORT=8080