Skip to content

Configuration reference

All settings are environment variables (or .env entries). The short list most users need is in .env.example; everything below is available.

GEOMETRIKKS_ENV_FILE overrides the path of the .env file itself (default: .env in the working directory); setting it to an empty value disables dotenv loading entirely, so configuration comes only from real environment variables. It is read once at import time.

Application

Section titled “Application”
Variable Default Description
APP_NAME GeoMetrikks API Application name
APP_VERSION (computed) Application version (defaults to installed package metadata)
APP_DESCRIPTION Real-time GeoIP lookups and traffic analytics API Application description
APP_DEBUG false Enable debug mode
APP_ENVIRONMENT production Application environment
APP_RUNTIME host Execution runtime; container images set this to container.
APP_IMAGE_TAG - Optional container image tag embedded at build time.
APP_AUTH_DISABLED false Disable the built-in session auth entirely. Set true only when an authenticating reverse proxy (Authelia, Tailscale, …) fronts the app.
APP_ADMIN_USER admin Admin login username
APP_ADMIN_PASSWORD - Admin login password (required unless auth_disabled=true)
APP_SESSION_SECURE false Mark the session cookie Secure so browsers only send it over HTTPS. Recommended when serving behind a TLS reverse proxy.
APP_TRUSTED_PROXIES (computed) Reverse-proxy IPs/CIDRs allowed to supply X-Forwarded-For. Env accepts one value, comma-separated values, or a JSON list. Empty (default): forwarded headers are never trusted.

Application mode

Section titled “Application mode”
Variable Default Description
APP_MODE full Application mode: full (all components) or agent (logparser only)
APP_PROXY_ADVISORY true Warn on Settings > Status when most recent traffic for a tailed file comes from CDN or private peer addresses, meaning the proxy logs its upstream instead of the visitor. CDN findings for agent-tailed sources are scanned from the database on the head every 5 minutes. Set to false when the traffic mix is deliberate (Tailscale-only access, a CDN you front on purpose).

API server

Section titled “API server”
Variable Default Description
API_HOST 0.0.0.0 API server host
API_PORT 8000 API server port
API_LOG_LEVEL - DEPRECATED: use LOG_LEVEL. Kept as a fallback for existing deployments.

Database

Section titled “Database”
Variable Default Description
DB_ECHO false Enable SQLAlchemy query logging
DB_ECHO_POOL false Enable SQLAlchemy pool logging
DB_MAX_OVERFLOW 10 Max connections above pool_size
DB_POOL_SIZE 5 Database connection pool size
DB_POOL_TIMEOUT 30 Connection pool timeout in seconds
DB_POOL_RECYCLE 3600 Connection recycle time in seconds
DB_POOL_DISABLED false Disable connection pooling
DB_POOL_PRE_PING true Enable pool pre-ping to check connections
DB_USER geouser Database user
DB_PASSWORD - Database password
DB_HOST localhost Database host
DB_PORT 5432 Database port
DB_DATABASE geometrikks Database name
DB_DROP_ON_STARTUP false Drop all tables on startup (development only)
DB_MIGRATE_ON_STARTUP true Run alembic migrations automatically at app startup. Disable when migrations run as a separate deployment step (litestar database upgrade); the app then expects the schema to already be at head and fails startup if it is not usable

GeoIP

Section titled “GeoIP”
Variable Default Description
GEOIP_DB_PATH data/geoip/GeoLite2-City.mmdb Path to GeoIP2/GeoLite2 database file
GEOIP_LOCALES ["en"] List of GeoIP locales to use
GEOIP_VALIDATE_DB_PATH false Fail settings validation when the GeoIP database file is missing. Off by default: the auto-downloader/degraded-mode path owns the missing-file case (set true to fail fast instead).
GEOIP_VALIDATE_LOCALES true Validate that the specified GeoIP locales are supported
MAXMINDDB_USER_ID - MaxMind account ID for GeoLite2 auto-download
MAXMINDDB_LICENSE_KEY - MaxMind license key for GeoLite2 auto-download
GEOIP_REFRESH_DAYS 7 Re-download the GeoLite2 database when older than this many days
GEOIP_ASN_DB_PATH data/geoip/GeoLite2-ASN.mmdb Path to the GeoLite2 ASN database file
GEOIP_ASN_ENABLED true Download and use the GeoLite2 ASN database for per-request ASN/organization enrichment. Uses the same MaxMind credentials as the City database; without credentials or a database file the app simply ingests without ASN data.

Logging

Section titled “Logging”
Variable Default Description
LOG_DIR logs Directory for application log files
LOG_LEVEL - Root log level. Falls back to deprecated API_LOG_LEVEL, then INFO.
LOG_MAIN_MAX_BYTES 10485760 Rotate the main JSONL log when it exceeds this size (bytes)
LOG_MAIN_BACKUP_COUNT 5 Number of gzipped main-log archives to keep
LOG_LOGIN_MAX_BYTES 10485760 Rotate the login log when it exceeds this size (bytes)
LOG_LOGIN_BACKUP_COUNT 5 Number of gzipped login-log archives to keep

Log parser

Section titled “Log parser”
Variable Default Description
LOGPARSER_ENABLED true Enable log parser ingestion service
LOGPARSER_LOG_PATHS (computed) Access log files to tail. Env accepts a single path or a JSON list of paths. Default: /var/log/access/access.log
LOGPARSER_LOG_FORMATS (computed) Log format per tailed file: ‘auto’ (default, detected from the file’s content), ‘geometrikks-json’, ‘nginx’, ‘traefik-json’, or ‘caddy-json’. Env accepts a single value applied to every path, or a JSON list matching LOGPARSER_LOG_PATHS by position.
LOGPARSER_POLL_INTERVAL 1.0 Interval in seconds to poll the log file for new entries
LOGPARSER_SEND_LOGS true Send parsed logs to the database
LOGPARSER_HOST_NAME (computed) Source hostname stamped on ingested records. Env accepts a single value applied to every tailed file, or a JSON list matching LOGPARSER_LOG_PATHS by position. Default: this machine’s hostname.
LOGPARSER_BATCH_SIZE 100 Max records before forced commit.
LOGPARSER_COMMIT_INTERVAL 5.0 Maximum time interval in seconds between database commits. This will commit even if batch_size is not reached.
LOGPARSER_SKIP_VALIDATION false Skip validation of log lines.
LOGPARSER_STORE_DEBUG_LINES false Store all raw log lines in AccessLogDebug table. When False, only malformed requests are stored.
LOGPARSER_IGNORE_IPS (computed) IPs/CIDRs the parser drops entirely (no geo event, access log, or debug row). Use for your own traffic hitting the reverse proxy. Env accepts one value, comma-separated values, or a JSON list. Empty (default): nothing is ignored.

Analytics & retention

Section titled “Analytics & retention”
Variable Default Description
ANALYTICS_RAW_RETENTION_DAYS 180 Days to keep raw geo_events and access_logs data. At least 4: the daily aggregates refresh their last 3 days from raw rows, and a shorter retention makes each refresh erase those buckets. Startup refuses lower values.
ANALYTICS_DEBUG_RETENTION_DAYS 30 Days to keep access_log_debug data
ANALYTICS_HOURLY_RETENTION_DAYS 60 Days to keep hourly continuous aggregate data
ANALYTICS_CAGG_REFRESH_INTERVAL_MINUTES 5 Minutes between continuous aggregate refreshes
ANALYTICS_COMPRESSION_AFTER_DAYS 7 Days after which to compress hypertable chunks

Scheduler

Section titled “Scheduler”
Variable Default Description
SCHEDULER_ENABLED true Enable scheduled background tasks
SCHEDULER_LOCATION_REFRESH_INTERVAL_MINUTES 10 Minutes between GeoLocation.last_hit refresh jobs

Map

Section titled “Map”
Variable Default Description
MAP_HOME_LATITUDE - Optional destination latitude for live request routes. Set both home coordinates to override external-IP auto-detection.
MAP_HOME_LONGITUDE - Optional destination longitude for live request routes. Set both home coordinates to override external-IP auto-detection.
MAP_AUTO_DETECT_HOME true Resolve the server’s public IP at startup and geolocate it when home coordinates are unset.
MAP_PUBLIC_IP_URL https://api64.ipify.org?format=json JSON endpoint used for public-IP discovery; the response must contain an ‘ip’ field.
MAP_PUBLIC_IP_TIMEOUT 3.0 Timeout in seconds for public-IP discovery.
MAP_HOME_LOCATIONS (computed) Per-hostname home overrides as a JSON object of {“hostname”: [latitude, longitude]}. Overrides win over agent auto-detection in site_homes; removing an entry deletes its override row at the next startup. Use for sites whose public IP geolocates wrong (CGNAT, VPN) or for hostnames in logs shipped from other machines.
MAP_HOME_REFRESH_HOURS 24 How often this instance re-detects its own public-IP home location and refreshes its site_homes rows (hours).
MAP_CARTO_API_KEY `` CARTO basemaps API key, sent as ?key= on every basemap request the browser makes. CARTO’s terms require one per deployment; keys are free at https://carto.com/basemaps/apikey. Not a secret: it is visible to anyone who can open the map.

CrowdSec

Section titled “CrowdSec”
Variable Default Description
CROWDSEC_LAPI_URL - CrowdSec Local API base URL, e.g. http://crowdsec:8080
CROWDSEC_BOUNCER_API_KEY - Bouncer API key (cscli bouncers add geometrikks) - read access
CROWDSEC_MACHINE_ID - Machine ID (cscli machines add) - enables ban/unban
CROWDSEC_MACHINE_PASSWORD - Machine password - enables ban/unban
CROWDSEC_DEFAULT_BAN_DURATION 4h Default duration for manual bans (Go duration string)
CROWDSEC_REQUEST_TIMEOUT 10.0 LAPI request timeout in seconds
CROWDSEC_VERIFY_TLS true Verify TLS when LAPI uses https
CROWDSEC_STREAM_POLL_INTERVAL 15.0 Seconds between decision-stream polls feeding live ban/unban updates

Vite (development only)

Section titled “Vite (development only)”
Variable Default Description
VITE_DEV_MODE false Start vite development server.
VITE_USE_SERVER_LIFESPAN true Auto start and stop vite processes when running in development mode.
VITE_HOST 0.0.0.0 The host the vite process will listen on. Defaults to 0.0.0.0.
VITE_PORT 5173 The port to start vite on. Default is 5173.
VITE_ENABLE_REACT_HELPERS true Enable React support in HMR.
VITE_HTTP2 true Enable HTTP/2 for the Vite development server.
VITE_EXECUTOR bun JS runtime executor for litestar-vite (defaults to bun).