> ## Documentation Index
> Fetch the complete documentation index at: https://docs.warnly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Settings

> This document describes how to configure the Warnly server.

# 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:

```bash theme={null}
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.