OpenFlare/docs/en/reference/configuration.md

# Configuration Reference

You will learn: What configuration sources are supported by OpenFlare Server, frontend builds, and Agents, what the default values of configuration items are, and how common deployment combinations should be configured.

This document summarizes the Server and Agent configuration items supported by OpenFlare `1.0.0`, retaining only the startup, deployment, and runtime parameters that remain valid.

## Configuration Sources

The Server supports three types of configuration sources:

1. Command-line parameters.
2. Environment variables.
3. Runtime configurations in the database `Option` table.

The Agent supports:

1. `-config` command-line parameter.
2. `agent.json` configuration file.
3. A few log-related environment variables.

## Configuration File Locations

| Component | Default Location | Description |
| --- | --- | --- |
| Server SQLite | `openflare.db` | Can be modified via `SQLITE_PATH` |
| Server Uploads Directory | `upload` | Can be modified via `UPLOAD_PATH` |
| Agent Configuration File | `./agent.json` | Can be specified via `-config` |
| One-click Install Agent Config | `/opt/openflare-agent/agent.json` | Default generated by the installation script |
| Agent Data Directory | `data` under the config directory | Can be modified via `data_dir` |

## Server CLI Flags

```bash
cd openflare_server
go run . --port 3000 --log-dir ./logs
```

| Flag | Purpose | Default |
| --- | --- | --- |
| `--port` | Specify the port the Server listens on | `3000` |
| `--log-dir` | Specify the log directory | empty |
| `--version` | Print the current version and exit | `false` |
| `--help` | Print help information and exit | `false` |

## Server Environment Variables

| Variable | Purpose | Default |
| --- | --- | --- |
| `PORT` | Server listen port | `3000` |
| `GIN_MODE` | Gin execution mode | `release` unless `debug` |
| `LOG_LEVEL` | Log level | `info` |
| `SESSION_SECRET` | Session signing secret | randomly generated on startup |
| `SQLITE_PATH` | SQLite database file path | `openflare.db` |
| `DSN` | PostgreSQL DSN, preferred over SQLite when set | empty |
| `SQL_DSN` | Legacy PostgreSQL DSN, lower priority than `DSN` | empty |
| `REDIS_CONN_STRING` | Redis connection string | empty |
| `UPLOAD_PATH` | Upload directory | `upload` |
| `AGENT_TOKEN` | Legacy global Agent token | empty |

Description:

* When both `DSN` and `SQL_DSN` exist, `DSN` takes precedence.
* When `DSN`/`SQL_DSN` and `SQLITE_PATH` exist simultaneously, PostgreSQL takes precedence.
* When the target PostgreSQL database is empty and a local SQLite file exists at `SQLITE_PATH`, the Server automatically migrates SQLite data at startup and prints table-by-table migration progress in the logs.
* `SESSION_SECRET` must be explicitly configured in production.
* When `REDIS_CONN_STRING` is not configured, related capabilities fall back to in-process implementations.

## Runtime Options

The following options are maintained on the settings page of the management console and can be hot-updated:

| Option | Purpose | Default |
| --- | --- | --- |
| `AgentHeartbeatInterval` | Agent heartbeat interval (milliseconds) | `10000` |
| `AgentWebsocketUpgradeEnabled` | Whether to allow Agents to upgrade to WebSockets after successful HTTP heartbeats | `true` |
| `NodeOfflineThreshold` | Node offline threshold (milliseconds) | `120000` |
| `AgentUpdateRepo` | Agent self-update repository | `Rain-kl/OpenFlare` |
| `GeoIPProvider` | Node/IP region lookup provider | `ipinfo` |
| `DatabaseAutoCleanupEnabled` | Whether to enable daily automatic cleanup of observability data | `false` |
| `DatabaseAutoCleanupRetentionDays` | In-database retention days, at least 1 day | `30` |
| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | Global API rate limit count / window | `300` / `180` |
| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | Global Web rate limit count / window | `300` / `180` |
| `UploadRateLimitNum` / `UploadRateLimitDuration` | Upload API rate limit count / window | `50` / `60` |
| `DownloadRateLimitNum` / `DownloadRateLimitDuration` | Download API rate limit count / window | `50` / `60` |
| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | Sensitive API rate limit count / window | `100` / `1200` |

Description:

* When `DatabaseAutoCleanupEnabled` is enabled, the Server automatically cleans up three types of observability data (`node_access_logs`, `node_metric_snapshots`, `node_request_reports`) at 3:00 AM every day.
* `DatabaseAutoCleanupRetentionDays` is the unified retention count and must be greater than or equal to 1.
* The management console supports leaving the retention days blank during manual cleanup to directly delete all history of the corresponding datasets.
* The GitHub Release pointed to by `AgentUpdateRepo` must provide a matching `.sha256` checksum file for each Agent binary, such as `openflare-agent-linux-amd64.sha256`; the self-update validates this SHA-256 digest before replacing the executable.
* Third-party logins no longer use `GitHubOAuthEnabled`, `GitHubClientId`, or `GitHubClientSecret` as primary configuration entries; these legacy options are only used for migration to the default GitHub authentication source during upgrades.
* Legacy options for WeChat login are retained for compatibility, but the management console no longer provides WeChat login configuration entries.
* Legacy options for Turnstile and backend verification remain, and existing configurations will continue to take effect.

## OpenResty Parameters

OpenResty performance and caching parameters continue to be stored uniformly in the `Option` table. Currently common items include:

* `OpenRestyWorkerProcesses`
* `OpenRestyWorkerConnections`
* `OpenRestyWorkerRlimitNofile`
* `OpenRestyKeepaliveTimeout`
* `OpenRestyProxyConnectTimeout`
* `OpenRestyProxySendTimeout`
* `OpenRestyProxyReadTimeout`
* `OpenRestyProxyBufferingEnabled`
* `OpenRestyGzipEnabled`
* `OpenRestyCacheEnabled`
* `OpenRestyCachePath`
* `OpenRestyCacheMaxSize`

These parameters must be validated, saved, and participate in version rendering in a structured way.

Constraints:

* The management console no longer exposes `resolver` configuration.
* Upstreams are uniformly rendered as named `upstream` blocks with keepalives enabled.
* A single upstream carrying a base path or query will append the original URI in `proxy_pass`.
* Multiple upstreams still require each upstream to be pure `scheme://host[:port]`, and the protocol must be consistent within the same rule.
* `OpenRestyCacheEnabled` is used to enable the caching infrastructure and global default parameters; the actual caching enablement and hit policies (based on URL, suffix, or path) are decided separately by each individual `proxy_routes`.
* The default cache key is `$scheme$host$request_uri`.
* The default `keepalive_timeout` is `20` seconds, and the default `proxy_connect_timeout` is `3` seconds.
* The default event model is `epoll`, and `multi_accept` is enabled by default.
* HTTPS listeners use the independent `http2 on;` directive by default to avoid deprecation warnings for `listen ... http2` in newer Nginx/OpenResty versions.

## Frontend Build Variables

| Variable | Purpose | Default |
| --- | --- | --- |
| `NEXT_PUBLIC_API_BASE_URL` | Frontend API request base path | `/api` |
| `NEXT_PUBLIC_APP_VERSION` | Frontend displayed version number | `dev` |
| `NEXT_DEV_BACKEND_URL` | Dev backend proxy target | `http://127.0.0.1:3000` |

## Agent Environment Variables

| Variable | Purpose | Default |
| --- | --- | --- |
| `LOG_LEVEL` | Agent log level | `info` |
| `OPENFLARE_SERVER_URL` | Control plane URL, can override `agent.json` | empty |
| `OPENFLARE_AGENT_TOKEN` | Node-exclusive auth token, can override `agent.json` | empty |
| `OPENFLARE_DISCOVERY_TOKEN` | Global token for first registration, can override `agent.json` | empty |
| `OPENFLARE_NODE_NAME` | Node name, can override `agent.json` | empty |
| `OPENFLARE_NODE_IP` | Node IP, can override `agent.json` | empty |
| `OPENFLARE_DATA_DIR` | Agent data directory, can override `agent.json` | empty |
| `OPENFLARE_OPENRESTY_PATH` | OpenResty binary path, can override `agent.json` | empty |
| `OPENFLARE_HEARTBEAT_INTERVAL` | Heartbeat interval, can override `agent.json` | empty |
| `OPENFLARE_REQUEST_TIMEOUT` | Request timeout, can override `agent.json` | empty |
| `OPENFLARE_OPENRESTY_OBSERVABILITY_PORT` | Local observability port, can override `agent.json` | empty |
| `OPENFLARE_MMDB_PATH` | WAF GeoIP mmdb path, can override `agent.json` | empty |
| `OPENFLARE_MMDB_UPDATE_INTERVAL` | WAF GeoIP mmdb update interval, can override `agent.json` | empty |
| `OPENFLARE_MMDB_DOWNLOAD_URL` | WAF GeoIP mmdb download URL, can override `agent.json` | empty |

## Agent CLI Flags

| Flag | Purpose | Default |
| --- | --- | --- |
| `-config` | Specify the path to the Agent configuration file | `./agent.json` |

## Agent Configuration Fields

| Field | Purpose | Required | Default / Behavior |
| --- | --- | --- | --- |
| `server_url` | Control plane URL | yes | none |
| `agent_token` | Node-exclusive auth token | one of `agent_token`/`discovery_token` | empty |
| `discovery_token` | Global token for first registration | one of `agent_token`/`discovery_token` | empty |
| `node_name` | Node name | no | automatically uses host name |
| `node_ip` | Node IP | no | auto-detected; prioritizes obtaining the real public egress IP via third-party APIs, falling back to local interfaces on failure |
| `openresty_path` | OpenResty binary path | no | `openresty` |
| `openresty_observability_port` | Local observability and OpenResty health-check port | no | `18081` |
| `data_dir` | Agent data directory | no | `data` under the config file directory |
| `main_config_path` | OpenResty main config write path | no | `data_dir/etc/nginx/nginx.conf` |
| `route_config_path` | Route config write path | no | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
| `access_log_path` | OpenResty access log path | no | `data_dir/var/log/openflare/access.log` |
| `cert_dir` | Certificate write directory | no | `data_dir/etc/nginx/certs` |
| `openresty_cert_dir` | Certificate read directory in OpenResty config | no | same as `cert_dir` |
| `lua_dir` | Lua scripts and static resources write directory | no | `data_dir/etc/nginx/lua` |
| `openresty_lua_dir` | Lua read directory in OpenResty config | no | same as `lua_dir` |
| `runtime_config_dir` | Agent runtime config write directory, e.g., `pow_config.json` | no | `data_dir/etc/openflare` |
| `mmdb_path` | WAF GeoIP mmdb file path | no | `data_dir/etc/openflare/GeoLite2-Country.mmdb` |
| `mmdb_update_interval` | WAF GeoIP mmdb update interval | no | `86400000` milliseconds |
| `mmdb_download_url` | WAF GeoIP mmdb download URL | no | built-in GeoLite2 Country download URL |
| `observability_buffer_path` | Observability buffering file path | no | `data_dir/var/lib/openflare/observability-buffer.json` |
| `observability_replay_minutes` | Minutes to automatically replay recent observability data | no | `15` |
| `state_path` | Agent local state file path | no | `data_dir/var/lib/openflare/agent-state.json` |
| `heartbeat_interval` | Heartbeat interval | no | `10000` milliseconds |
| `request_timeout` | HTTP request timeout | no | `10000` milliseconds |

Description:

* `agent_token` and `discovery_token` cannot both be empty.
* `heartbeat_interval` and `request_timeout` support integer milliseconds or Go duration strings.
* When the Server runtime option `AgentWebsocketUpgradeEnabled` is enabled, the Agent will attempt to upgrade to a WebSocket after a successful HTTP heartbeat; it automatically falls back to HTTP heartbeats when connection fails or is disconnected.
* When `openresty_path` is not configured, `openresty` is called by default.
* The Agent's periodic health checks request `http://127.0.0.1:<openresty_observability_port>/openflare/stub_status`, no longer judging runtime health via high-frequency `openresty -t`; validation before configuration application, startup recovery, and reloads will still execute `openresty -t -c <main_config_path>`.
* The Agent initializes and periodically updates `mmdb_path` for OpenResty WAF Lua to execute country-level geographical rules; update failures only record warnings, and do not block sync or reloads.
* If `agent.json` does not exist but environment variables such as `OPENFLARE_SERVER_URL` and tokens are sufficient, the Agent can start directly; environment variables take precedence when both exist.
* When the Agent is not configured with `node_ip`, it first queries `https://realip.cc` for the real public egress IP, adapting to Docker/NAT scenarios; it falls back to local interface detection on failure, preferring a public IPv4 address.
* When the Agent automatically detects a private `node_ip`, the Server prioritizes retaining the public address of the Agent's direct connection during registration/heartbeat phases, avoiding misregistering internal interface addresses in NAT or multi-interface scenarios.

## Common Configuration Combinations

### Production Server + PostgreSQL

```bash
export SESSION_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable'
export GIN_MODE='release'
export LOG_LEVEL='info'
```

### Local Server + SQLite

```bash
export SESSION_SECRET='dev-session-secret'
export SQLITE_PATH='./openflare-dev.db'
export LOG_LEVEL='debug'
go run .
```

### Agent + Default OpenResty

```json
{
  "server_url": "http://your-server:3000",
  "agent_token": "replace-with-node-auth-token",
  "data_dir": "/opt/openflare-agent/data",
  "openresty_path": "openresty",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}
```

### Agent + Customized OpenResty Path

```json
{
  "server_url": "http://your-server:3000",
  "agent_token": "replace-with-node-auth-token",
  "data_dir": "/var/lib/openflare-agent",
  "openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
  "main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
  "route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
  "access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
  "cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
  "lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
  "runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}
```

## Maintenance Requirements

When the following contents change, this document must be updated in sync:

* Server command-line parameters.
* Server environment variables.
* Agent command-line parameters.
* Agent configuration fields.
* Default values, purposes, or examples of any configuration items.