.env.example

# =============================================================================
# Secrets (DO NOT COMMIT)
# - Rotate any secrets previously pasted into chat.
# =============================================================================

# Registry / deployment (Kamal)
KAMAL_REGISTRY_PASSWORD="<secret>"

# Admin basic auth (for /api/v1/admin/* endpoints)
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="<secret>"

# OpenAI
OPENAI_API_KEY="<secret>"
OPENAI_MODEL=gpt-3.5-turbo

# BTAA Geospatial API Key
BTAA_GEOSPATIAL_API_KEY="<secret>"

# Geoportal bridge sync
KITHE_BRIDGE_URL="https://geomg.lib.umn.edu/api/kithe_bridge"
KITHE_BRIDGE_TOKEN="<secret>"
KITHE_BRIDGE_PAGE_SIZE=500
KITHE_BRIDGE_REQUEST_TIMEOUT=30
KITHE_BRIDGE_VERIFY_SSL=true

# =============================================================================
# Application
# =============================================================================

APPLICATION_URL=http://localhost:8000/api/v1/
# Base URL for the Geoportal (resource pages). Used for citation URLs.
# When unset, derived from APPLICATION_URL by stripping /api/v1.
# GEOPORTAL_BASE_URL=http://localhost:3000
LOG_PATH=logs
# Comma-separated CORS origins (use * for all). Local dev: 3000 (React Router) or 5173 (Vite)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
# Enable crawler indexing and advertise the sitemap in robots.txt.
# Keep this false for local/dev/staging environments.
SEARCH_ENGINE_INDEXING_ENABLED=false

# =============================================================================
# Observability
# =============================================================================

# Shared AppSignal fallback. Kamal deploy configs override these per destination.
APPSIGNAL_ACTIVE=false
APPSIGNAL_APP_ENV=development
APPSIGNAL_APP_NAME="BTAA Geospatial API - Development"

# Backend FastAPI app identity.
APPSIGNAL_BACKEND_ACTIVE=false
APPSIGNAL_BACKEND_APP_ENV=development
APPSIGNAL_BACKEND_APP_NAME="BTAA Geospatial API - Development"
APPSIGNAL_BACKEND_ENABLE_HOST_METRICS=false
APPSIGNAL_BACKEND_HOST_ROLE=backend
APPSIGNAL_BACKEND_OPENTELEMETRY_PORT=8099

# Frontend React SSR app identity.
APPSIGNAL_FRONTEND_ACTIVE=false
APPSIGNAL_FRONTEND_APP_ENV=development
APPSIGNAL_FRONTEND_APP_NAME="BTAA Geoportal SSR - Development"
APPSIGNAL_FRONTEND_ENABLE_HOST_METRICS=false
APPSIGNAL_FRONTEND_HOST_ROLE=frontend
APPSIGNAL_FRONTEND_OPENTELEMETRY_PORT=8100

# AppSignal organization push API key.
APPSIGNAL_PUSH_API_KEY="<secret>"

# Optional reported release/revision override. Kamal deploy configs derive this
# from APP_REVISION, then KAMAL_VERSION, then the current Git commit.
APP_REVISION=local

# Feedback form email delivery. In Kamal production, sendmail is provided by
# msmtp-mta and relays through smtp.umn.edu. Use FEEDBACK_RECIPIENTS to route
# public feedback to the Geoportal team.
FEEDBACK_EMAIL_ENABLED=true
FEEDBACK_RECIPIENTS="ewlarson@gmail.com,majew030@umn.edu"
FEEDBACK_FROM="BTAA Geoportal <no-reply@geo.btaa.org>"
FEEDBACK_DELIVERY=sendmail

# Old Database
OLD_DB_NAME=geoportal_production_20251030

# =============================================================================
# Database
# =============================================================================

POSTGRES_PASSWORD="<secret>"
# IMPORTANT: keep the password in DATABASE_URL in sync with POSTGRES_PASSWORD.
DATABASE_URL=postgresql+asyncpg://postgres:<secret>@localhost:2345/btaa_geospatial_api
DB_POOL_MAX=5
SQLALCHEMY_ASYNC_POOL_SIZE=5
SQLALCHEMY_ASYNC_MAX_OVERFLOW=10
SQLALCHEMY_ASYNC_POOL_TIMEOUT=10
SQLALCHEMY_ASYNC_USE_NULLPOOL=false

# =============================================================================
# Elasticsearch
# =============================================================================

ELASTICSEARCH_URL=http://localhost:9200
ELASTICSEARCH_INDEX=btaa_geospatial_api

# =============================================================================
# Production disaster recovery backups (Kamal prd)
# =============================================================================

# Shared guard. Keep false locally/dev; prd deploy config defaults this true.
BACKUP_ENABLED=false
BACKUP_REQUIRED_DEST=prd
BACKUP_RETENTION_COUNT=3
BACKUP_S3_BUCKET=
BACKUP_S3_PREFIX=btaa-geospatial-api
BACKUP_S3_REGION=us-east-2
AWS_REGION=us-east-2
AWS_DEFAULT_REGION=us-east-2
AWS_ACCESS_KEY_ID="<secret>"
AWS_SECRET_ACCESS_KEY="<secret>"

# Elasticsearch snapshots can use fs locally or s3 in prd.
ELASTICSEARCH_SNAPSHOT_REPOSITORY=btaa_geoportal_snapshots
ELASTICSEARCH_SNAPSHOT_REPOSITORY_TYPE=fs
ELASTICSEARCH_SNAPSHOT_S3_BASE_PATH=btaa-geospatial-api/prd/elasticsearch
# Optional, e.g. standard_ia. Leave empty for the Elasticsearch default.
ELASTICSEARCH_SNAPSHOT_S3_STORAGE_CLASS=
ELASTICSEARCH_SNAPSHOT_S3_SERVER_SIDE_ENCRYPTION=true

# =============================================================================
# Redis (shared: endpoint caching + other features)
# =============================================================================

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD="<secret>"
REDIS_DB=0
REDIS_APPENDONLY=yes
REDIS_SAVE=900 1 300 10 60 10000

# =============================================================================
# Endpoint response caching (Redis)
# =============================================================================

# Master switch for @cached_endpoint
ENDPOINT_CACHE=false

# Per-endpoint TTLs (in seconds)
ITEM_CACHE_TTL=86400  # 24 hours
SEARCH_CACHE_TTL=3600     # 1 hour
SUGGEST_CACHE_TTL=7200    # 2 hours 
LIST_CACHE_TTL=43200      # 12 hours
CACHE_TTL=43200           # Default TTL (12 hours)

# Cache namespace/versioning (bump CACHE_APP_VERSION to invalidate safely)
CACHE_VERSION=2026-01-07
# CACHE_APP_VERSION=2026-01-07

# Redis safety/timeouts for caching (separate from rate limiting/celery usage)
REDIS_TIMEOUT_SECONDS=0.5
REDIS_LOCK_TTL_SECONDS=10
CACHE_LOCK_WAIT_SECONDS=0.25

# Stampede protection + Resilience during upstream issues
STALE_IF_ERROR_SECONDS=300
MAX_STALE_EXTENSION_SECONDS=3600
TAG_INDEX_TTL_PADDING_SECONDS=60

# Optional hard TTL override for cached records (otherwise defaults to 2*ttl)
# CACHE_HARD_TTL_SECONDS=120

# Debug/observability
CACHE_DEBUG_HEADERS=true     # adds X-Cache header
CACHE_LOG_EVENTS=true        # logs cache_event JSON lines

# =============================================================================
# Response compression (FastAPI)
# =============================================================================

ENABLE_RESPONSE_COMPRESSION=true
GZIP_MINIMUM_SIZE=1000
GZIP_COMPRESSLEVEL=6

# =============================================================================
# Rate limiting
# =============================================================================

RATE_LIMIT_ENABLED=false
API_KEY_TIER_CACHE_TTL_SECONDS=60
API_KEY_LAST_USED_UPDATE_INTERVAL_SECONDS=60
API_KEY_TIER_CACHE_MAX_ENTRIES=2048

# =============================================================================
# Cloudflare Turnstile browser gate
# =============================================================================

# Create a Turnstile widget in Cloudflare, then set the public site key for the
# React bundle and the secret key for FastAPI Siteverify calls.
TURNSTILE_ENABLED=false
TURNSTILE_SECRET_KEY="<secret>"
TURNSTILE_ALLOWED_HOSTNAMES=localhost,127.0.0.1
TURNSTILE_EXPECTED_ACTION=geoportal_gate
TURNSTILE_PROTECTED_PATHS=/api/v1/search,/api/v1/suggest,/api/v1/map/h3
TURNSTILE_SESSION_TTL_SECONDS=3600
TURNSTILE_COOKIE_SECURE=false
TURNSTILE_ENABLE_LOCAL=false
VITE_TURNSTILE_ENABLED=false
VITE_TURNSTILE_ENABLE_LOCAL=false
VITE_TURNSTILE_SITE_KEY=
VITE_TURNSTILE_ACTION=geoportal_gate

# =============================================================================
# Analytics storage retention / rollups
# =============================================================================

# Raw analytics tables are partitioned monthly and rolled up daily.
# Retention drops whole raw partitions only after rollups have covered them.
ANALYTICS_RETENTION_API_USAGE_DAYS=30
ANALYTICS_RETENTION_SEARCH_DAYS=90
ANALYTICS_RETENTION_IMPRESSION_DAYS=30
ANALYTICS_RETENTION_EVENT_DAYS=90

# How many past/future monthly partitions to keep pre-created.
ANALYTICS_PARTITION_HISTORY_MONTHS=2
ANALYTICS_PARTITION_FUTURE_MONTHS=2

# Safety valve for one maintenance run; if the rollup job is catching up,
# it will process at most this many calendar days before the next run.
ANALYTICS_ROLLUP_MAX_DAYS_PER_RUN=31

# =============================================================================
# GBL Admin production dump restore (optional)
# =============================================================================
#
# These are used by:
#   - make gbl-admin-db-download
#   - make gbl-admin-db-sync
#
# By default, the Makefile downloads into `tmp/` in the repo.
# If you set GBL_ADMIN_LOCAL_DIR, prefer a path you can write to
# (avoid `/Volumes/...` unless you’ve mounted an external drive there).
#
# GBL_ADMIN_LOCAL_DIR=tmp/gbl_admin_restore
# GBL_ADMIN_SSH_USER=ewlarson
# GBL_ADMIN_SSH_HOST=geomg.lib.umn.edu
# GBL_ADMIN_REMOTE_DIR=/opt/data/pgdump
# GBL_ADMIN_DUMP_GLOB=pgdump-geoportal_production-*.sql.gz
# GBL_ADMIN_SQL_GLOB=pgdump-geoportal_production-*.sql