Configuration

Warnly is configured using environment variables.

Core Server Setup

Server

Server configuration controls how Warnly listens for and serves HTTP and HTTPS connections.

Property	Description	Default	Required
SERVER_HOST	The host address on which to serve the Warnly application	localhost	No
SERVER_PORT	The HTTP port on which to serve the Warnly REST API and UI	8080	No
SCHEME	The protocol to use (http or https)	http	No
CERT_FILE	Path to the certificate file (required if SCHEME is https)		No
CERT_KEY	Path to the certificate key file (required if SCHEME is https)		No
CLOSE_TIMEOUT	Timeout for graceful shutdown	5s	No
PUBLIC_INGEST_URL	Public URL for ingest endpoints (used for generating DSNs)		No

Database

Database configuration defines how Warnly connects to MySQL for primary data storage.

Property	Description	Default	Required
MYSQL_DSN	MySQL connection string with credentials and database name		Yes

Example DSN: warnly:root@tcp(localhost:3306)/warnly?interpolateParams=true&parseTime=true&timeout=2s&loc=UTC

Admin

Initial administrator account configuration.

Property	Description	Default	Required
ADMIN_EMAIL	Email address for the initial admin user		Yes
ADMIN_PASSWORD	Password for the initial admin user		Yes

Authentication

OIDC

OpenID Connect authentication provider configuration.

Property	Description	Default	Required
OIDC_PROVIDER_NAME	Name of the OIDC provider (e.g., ‘google’, ‘keycloak’)		No
OIDC_ISSUER_URL	OIDC issuer URL		No
OIDC_CLIENT_ID	OIDC client ID		No
OIDC_CLIENT_SECRET	OIDC client secret		No
OIDC_REDIRECT_ADDRESS	Public URL on which Warnly instance is reachable		No
OIDC_SCOPES	Space-separated list of OIDC scopes		No
OIDC_EMAIL_MATCHES	Space-separated list of email regex patterns for user filtering		No
OIDC_USE_PKCE	Enable PKCE for OIDC authentication flow	true	No

Sessions

Session management configuration.

Property	Description	Default	Required
SESSION_KEY	Secret key for signing session cookies (32 bytes)		Yes
REMEMBER_SESSION_DAYS	Number of days to remember user sessions	30	No

Observability

Logging

Logging configuration controls the format and destination of Warnly’s application logs.

Property	Description	Default	Required
LOG_OUTPUT	Where to output logs (stderr, stdout, or file path)	stderr	No
LOG_TEXT	Use text format instead of JSON	false	No

Tracing

OpenTelemetry tracing configuration.

Property	Description	Default	Required
TRACING_REPORTER_URI	OTLP gRPC endpoint for sending traces		No
TRACING_SERVICE_NAME	Service name for traces	warnly	No
TRACING_PROBABILITY	Sampling probability for traces (0.0 to 1.0)	1.0	No

Metrics

Prometheus metrics configuration.

Property	Description	Default	Required
METRICS_ENABLED	Enable Prometheus metrics endpoint	false	No
METRICS_PORT	Port for metrics server	8081	No
METRICS_PATH	Path for metrics endpoint	/metrics	No

Analytics

ClickHouse

ClickHouse configuration for analytics and event storage.

Property	Description	Default	Required
CLICKHOUSE_DSN	ClickHouse connection string with credentials and database name		Yes

Example DSN:

clickhouse://root:root@clickhouse:9000/warnly?dial_timeout=900ms&connection_open_strategy=in_order&compress=true&max_open_conns=55&max_idle_conns=50&conn_max_lifetime=5m&max_execution_time=10

Additional Settings

Migration

Database migration settings.

Property	Description	Default	Required
FORCE_MIGRATE	Force database migrations to run on startup	false	No

Environment Variable Override

All configuration options can be overridden using environment variables. The naming convention follows the struct tags in the source code (uppercase with underscores replacing camelCase). For example, to override the server port:

export SERVER_PORT=9090

Configuration Validation

Warnly validates configuration at startup. Required fields will cause the application to exit with an error if not provided. Optional fields use sensible defaults.

Getting started

Configuration

Global Settings

Configuration

Core Server Setup

Server

Database

Admin

Authentication

OIDC

Sessions

Observability

Logging

Tracing

Metrics

Analytics

ClickHouse

Additional Settings

Migration

Environment Variable Override

Configuration Validation

​Configuration

​Core Server Setup

​Server

​Database

​Admin

​Authentication

​OIDC

​Sessions

​Observability

​Logging

​Tracing

​Metrics

​Analytics

​ClickHouse

​Additional Settings

​Migration

​Environment Variable Override

​Configuration Validation

Configuration

Core Server Setup

Server

Database

Admin

Authentication

OIDC

Sessions

Observability

Logging

Tracing

Metrics

Analytics

ClickHouse

Additional Settings

Migration

Environment Variable Override

Configuration Validation