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

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 APP_AUTH_DISABLED=true or OpenID Connect (OIDC_*) is configured)
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

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).
APP_INSTANCE_NAME	-	Name this instance goes by on Settings > Agents, where the head lists every instance that reports in. Unset, agents show as “agent” and the head as “head”. Set it on every agent. Two unnamed agents share one name and overwrite each other’s status. Up to 255 characters, no slashes, no control characters, and not “.” or “..”.

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

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
DB_STARTUP_WAIT_SECONDS	30	How long startup waits for the database before serving in degraded mode. 0 probes once. The app keeps re-probing in the background after this window and recovers on its own when the database answers.

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

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

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_SERVER_NAME	(computed)	Name recorded on every request this server ingests. It is a name you choose for this server, not your nginx server_name. Env accepts one value for every tailed file, or a JSON list matching LOGPARSER_LOG_PATHS by position. Default: this machine’s hostname. Formerly LOGPARSER_HOST_NAME, which still works until 1.0.
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.

Loki

Variable	Default	Description
LOKI_URL	-	Base URL of the Loki server, e.g. http://loki:3100. http or https. Unset (default): no Loki source.
LOKI_QUERIES	(computed)	LogQL stream selectors, one source each, e.g. {job=“traefik”}. Env accepts a single selector or a JSON list. Empty (default): no Loki source.
LOKI_FORMATS	(computed)	Log format per query, same values as LOGPARSER_LOG_FORMATS. Env accepts one value for every query, or a JSON list matching LOKI_QUERIES by position.
LOKI_SERVER_NAMES	(computed)	Server name per query. Env accepts one value or a JSON list matching LOKI_QUERIES by position. Empty (default): the first LOGPARSER_SERVER_NAME.
LOKI_TENANT_ID	-	Sent as X-Scope-OrgID, for a multi-tenant Loki. Unset (default): no header.
LOKI_USERNAME	-	Basic auth username, with LOKI_PASSWORD.
LOKI_PASSWORD	-	Basic auth password, with LOKI_USERNAME.
LOKI_POLL_INTERVAL	5.0	Seconds between reads of each query. LOGPARSER_POLL_INTERVAL paces the file tail separately.
LOKI_LOOKBACK	60.0	Seconds each read looks back for lines that reached Loki late. Every poll re-reads this whole window. The window never reaches back more than an hour, so values above 3600 behave as 3600.

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

Variable	Default	Description
SCHEDULER_ENABLED	true	Enable scheduled background tasks
SCHEDULER_LOCATION_REFRESH_INTERVAL_MINUTES	10	Minutes between GeoLocation.last_hit refresh jobs

Map

Variable	Default	Description
MAP_SERVER_LATITUDE	-	Latitude of this server on the map, where live request routes end. Set it with MAP_SERVER_LONGITUDE to skip public-IP detection. Formerly MAP_HOME_LATITUDE, which still works until 1.0.
MAP_SERVER_LONGITUDE	-	Longitude of this server on the map, where live request routes end. Set it with MAP_SERVER_LATITUDE to skip public-IP detection. Formerly MAP_HOME_LONGITUDE, which still works until 1.0.
MAP_AUTO_DETECT_SERVER_LOCATION	true	Look up this server’s public IP at startup and geolocate it when MAP_SERVER_LATITUDE and MAP_SERVER_LONGITUDE are unset. Formerly MAP_AUTO_DETECT_HOME, which still works until 1.0.
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_SERVER_LOCATIONS	(computed)	Fixed map locations per server name, as a JSON object of {“server”: [latitude, longitude]}. An entry here wins over the location that server detects for itself. Removing an entry deletes its row at the next startup. Use it for a server whose public IP geolocates wrong (CGNAT, VPN), or whose logs are shipped from another machine. Formerly MAP_HOME_LOCATIONS, which still works until 1.0.
MAP_SERVER_LOCATION_REFRESH_HOURS	24	Hours between re-detecting this server’s public-IP location and updating its stored server locations. Formerly MAP_HOME_REFRESH_HOURS, which still works until 1.0.
MAP_DEFAULT_VIEW	-	Where the map opens, as latitude,longitude or latitude,longitude,zoom (zoom 0-22, default 3). Example: 71.129982,27.653369,15 opens on northern Norway at zoom 15. When unset, the map opens on the server locations, or on the whole world if there are none.
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

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

OpenID Connect

Variable	Default	Description
OIDC_ISSUER	-	Issuer URL of the identity provider, e.g. https://auth.example.com. Discovery is read from {issuer}/.well-known/openid-configuration and the iss claim must equal this value exactly. Must be https unless the host is localhost.
OIDC_CLIENT_ID	-	Client id registered at the identity provider.
OIDC_CLIENT_SECRET	-	Client secret registered at the identity provider.
OIDC_REDIRECT_URI	-	The exact callback URL registered at the identity provider: the public https address of this app plus /api/v1/auth/oidc/callback. Plain http is only allowed on localhost.
OIDC_ALLOWED_USERS	(computed)	People allowed to sign in, each a verified email address or a subject identifier. One value, comma-separated values, or a JSON list. At least one of OIDC_ALLOWED_USERS and OIDC_ALLOWED_GROUPS is required.
OIDC_ALLOWED_GROUPS	(computed)	Groups allowed to sign in; membership in any one is enough. Same formats as OIDC_ALLOWED_USERS.
OIDC_GROUPS_CLAIM	groups	Claim that carries group membership, read from the ID token and the userinfo endpoint.
OIDC_SCOPES	openid profile email groups	Space-separated scopes requested at login. Must include openid.
OIDC_PROVIDER_NAME	SSO	Label on the login button: “Sign in with {name}”.
OIDC_LOGOUT_IDP	false	On logout, also end the identity provider session when discovery advertises an end_session_endpoint. Register {app origin}/signed-out as the post-logout redirect URI before enabling it. When the endpoint is absent, logout still clears the GeoMetrikks session but cannot end the provider session.
OIDC_CA_BUNDLE	-	PEM file with the CA that signed the identity provider’s certificate, for providers behind an internal CA. There is no switch to turn verification off.

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).