Configuration Reference
All runtime settings are environment variables prefixed with BANGUI_. Values are validated at startup — missing required fields or invalid values cause the application to refuse to start.
For setup instructions, see Instructions.md. For deployment, see Deployment.md.
Database
| Variable |
Type |
Default |
Description |
BANGUI_DATABASE_PATH |
string |
bangui.db |
Filesystem path to the SQLite application database. Parent directory must exist and be writable at startup. |
Session & Security
| Variable |
Type |
Default |
Description |
BANGUI_SESSION_SECRET |
string |
(required) |
Secret key for signing session tokens. Must be ≥ 32 characters. Generate with python -c "import secrets; print(secrets.token_hex(32))". Never reuse across environments. |
BANGUI_SESSION_SECRET_PREVIOUS |
string |
null |
Previous session secret used during rotation. Set to the old secret while rotating; unset once all old tokens expire. |
BANGUI_SESSION_DURATION_MINUTES |
int |
60 |
Session lifetime in minutes. Must be ≥ 1. |
BANGUI_SESSION_CACHE_ENABLED |
bool |
false |
Enable in-memory session validation cache. Disable in multi-worker deployments to avoid stale revoked sessions. |
BANGUI_SESSION_CACHE_TTL_SECONDS |
float |
10.0 |
TTL for cached session entries. Ignored when BANGUI_SESSION_CACHE_ENABLED is false. Must be ≥ 0. |
BANGUI_SESSION_COOKIE_HTTPONLY |
bool |
true |
Mark the session cookie as HttpOnly (JavaScript cannot access it). |
BANGUI_SESSION_COOKIE_SAMESITE |
string |
lax |
SameSite policy for the session cookie. Valid values: lax, strict, none. |
BANGUI_SESSION_COOKIE_SECURE |
bool |
true |
Set the Secure flag on the session cookie. true required for HTTPS. Set to false only for local HTTP development. |
fail2ban Integration
| Variable |
Type |
Default |
Description |
BANGUI_FAIL2BAN_SOCKET |
string |
/var/run/fail2ban/fail2ban.sock |
Path to the fail2ban Unix domain socket. Socket must exist and be readable at startup (warning issued if not). |
BANGUI_FAIL2BAN_CONFIG_DIR |
string |
/config/fail2ban |
Path to the fail2ban configuration directory. Must contain jail.d/, filter.d/, and action.d/. |
BANGUI_FAIL2BAN_START_COMMAND |
string |
fail2ban-client start |
Shell command to start the fail2ban daemon (no shell interpretation). Used during recovery rollback. Must be parseable by shlex.split. |
BANGUI_ALLOWED_LOG_DIRS |
list |
/var/log,/config/log |
Allowed directory prefixes for jail log paths. Any log path must resolve within one of these directories. |
BANGUI_TRUSTED_PROXIES |
list |
[] |
Trusted reverse proxy IP addresses or CIDR ranges (e.g., 192.168.1.1,10.0.0.0/8). Only these sources can set X-Forwarded-For and X-Real-IP. |
HTTP Client
These settings control outbound HTTP requests made by the backend (geolocation fallback, blocklist downloads).
| Variable |
Type |
Default |
Description |
BANGUI_HTTP_REQUEST_TIMEOUT_SECONDS |
float |
20.0 |
Maximum total time for an outbound HTTP request. Must be ≥ 0. |
BANGUI_HTTP_CONNECT_TIMEOUT_SECONDS |
float |
5.0 |
Maximum time to establish a TCP connection. Must be ≥ 0. |
BANGUI_HTTP_MAX_CONNECTIONS |
int |
10 |
Maximum concurrent outbound HTTP connections. Must be ≥ 1. |
BANGUI_HTTP_KEEPALIVE_TIMEOUT_SECONDS |
float |
15.0 |
How long idle keepalive connections are retained. Must be ≥ 0. |
Geolocation
| Variable |
Type |
Default |
Description |
BANGUI_GEOIP_DB_PATH |
string |
null |
Path to a MaxMind GeoLite2-Country .mmdb file. Primary resolver for IP geolocation when set. Download from https://dev.maxmind.com/geoip/geolite2-country. |
BANGUI_GEOIP_ALLOW_HTTP_FALLBACK |
bool |
false |
Allow HTTP fallback to ip-api.com when the MMDB is unavailable. Warning: sends IP addresses unencrypted. Only enable when MMDB cannot be mounted. |
Cross-Origin (CORS)
| Variable |
Type |
Default |
Description |
BANGUI_CORS_ALLOWED_ORIGINS |
list |
http://localhost:5173,http://127.0.0.1:5173,https://localhost:5173,https://127.0.0.1:5173 |
Allowed CORS origins. Comma-separated string or YAML list. Empty list disables CORS. Never use "*" in production when credentials are enabled. |
Display
| Variable |
Type |
Default |
Description |
BANGUI_TIMEZONE |
string |
UTC |
IANA timezone name used when displaying timestamps in the UI (e.g., America/New_York, Europe/London). |
External Logging
Enable with BANGUI_EXTERNAL_LOGGING_ENABLED=true, then set the provider and provider-specific variables.
| Variable |
Type |
Default |
Description |
BANGUI_EXTERNAL_LOGGING_ENABLED |
bool |
false |
Send logs to a centralized logging platform instead of stdout only. |
BANGUI_EXTERNAL_LOGGING_PROVIDER |
string |
null |
Logging provider: datadog, papertrail, or elasticsearch. Required when external logging is enabled. |
BANGUI_EXTERNAL_LOGGING_BUFFER_SIZE |
int |
1000 |
Max log records buffered in memory before dropping oldest. Must be ≥ 10. |
BANGUI_EXTERNAL_LOGGING_FLUSH_INTERVAL_SECONDS |
float |
5.0 |
Max seconds before flushing a log batch. Must be > 0. |
Datadog
| Variable |
Type |
Default |
Description |
BANGUI_DATADOG_API_KEY |
string |
null |
Datadog API key. Required when provider is datadog. |
BANGUI_DATADOG_SITE |
string |
datadoghq.com |
Datadog site: datadoghq.com (US) or datadoghq.eu (EU). |
BANGUI_DATADOG_BATCH_SIZE |
int |
10 |
Number of log records per batch. Must be ≥ 1. |
Papertrail
| Variable |
Type |
Default |
Description |
BANGUI_PAPERTRAIL_HOST |
string |
null |
Papertrail host address (e.g., logs1.papertrailapp.com). Required when provider is papertrail. |
BANGUI_PAPERTRAIL_PORT |
int |
null |
Papertrail port. Required when provider is papertrail. Range: 1–65535. |
BANGUI_PAPERTRAIL_PROGRAM_NAME |
string |
bangui |
Program name in Syslog messages sent to Papertrail. |
Elasticsearch
| Variable |
Type |
Default |
Description |
BANGUI_ELASTICSEARCH_HOSTS |
list |
[] |
Elasticsearch host URLs (e.g., http://elasticsearch:9200). Required when provider is elasticsearch. |
BANGUI_ELASTICSEARCH_INDEX_PREFIX |
string |
bangui |
Prefix for Elasticsearch indices. |
BANGUI_ELASTICSEARCH_BATCH_SIZE |
int |
10 |
Number of log documents per batch. Must be ≥ 1. |
Rate Limiting
Per-IP rate limits applied to API endpoints.
| Variable |
Type |
Default |
Description |
BANGUI_RATE_LIMIT_BANS_PER_MINUTE |
int |
100 |
Max ban/unban requests per IP per minute. |
BANGUI_RATE_LIMIT_BLOCKLIST_IMPORT_PER_HOUR |
int |
10 |
Max blocklist import requests per IP per hour. |
BANGUI_RATE_LIMIT_CONFIG_UPDATE_PER_MINUTE |
int |
50 |
Max config update requests per IP per minute. |
Observability
| Variable |
Type |
Default |
Description |
BANGUI_LOG_LEVEL |
string |
info |
Application log level. Valid values: debug, info, warning, error, critical. |
BANGUI_ENABLE_DOCS |
bool |
false |
Enable FastAPI interactive docs at /api/docs (Swagger UI) and /api/redoc (ReDoc). Enable only in development. |
Quick Reference
Cross-References
