Version: 1.2

Settings file and environment variables

Complete reference for configuring ToBeAlert in Docker, Kubernetes, and bare-metal deployments.

How configuration works

ToBeAlert uses three layers. Higher layers override lower ones:

Priority	Mechanism	Applies to
1	Environment variables	Backend (selected keys), frontend container, PostgreSQL image
2	`/tobealert/config/tobealertd.conf`	Backend only
3	Built-in defaults	Default values shipped in the backend image

The active settings file path is fixed: /tobealert/config/tobealertd.conf. It cannot be changed.

On first backend container start:

Copies /tobealert/config/tobealertd.conf.example → tobealertd.conf (if missing)
Replaces SECRET_KEY = 'CHANGEME' with a random value
Creates the bootstrap UI user from ADMIN_USER / ADMIN_PASSWORD (if that user does not exist)

Environment variable formats

Type	Format in env	Example
Boolean	`true`, `yes`, `on`, `1`, `enabled`, …	`DEBUG=true`
List	Comma-separated	`PLUGINS=delay,notifications`
Integer / string	Plain value	`REDIS_PORT=6379`

Frontend (`tobealert-frontend`)

All frontend runtime configuration is done with environment variables (injected at container start; nginx substitutes them into the config).

Variable	Required	Default	Description
`BASE_URL`	Yes	—	URL the browser uses to open the web UI (scheme + host + port, no trailing path). Example: `http://localhost` or `https://alerts.example.com`
`API_URL`	Yes	—	URL the browser uses for API calls (JavaScript fetch). Example: `http://localhost:9000` or `https://api.example.com`
`BACKEND_SERVICE`	Yes	—	Hostname nginx uses as upstream for `/api` and `/management`. In Docker Compose: backend service name (e.g. `tobealert-backend`). In Kubernetes: backend Service DNS name (e.g. `tobealerta-backend-svc`)
`BACKEND_PORT`	Yes	`9000`	TCP port of the backend upstream

Nginx proxies to:

http://${BACKEND_SERVICE}:${BACKEND_PORT}

BACKEND_SERVICE must resolve on the same network as the frontend pod/container (not localhost unless using network_mode: host).

PostgreSQL (`tobealert-bbdd`)

Standard PostgreSQL Docker image variables.

Variable	Required	Default	Description
`POSTGRES_USER`	Yes	—	Database user created on first init
`POSTGRES_PASSWORD`	Yes	—	Password for `POSTGRES_USER`
`POSTGRES_DB`	Yes	—	Database name created on first init
`TZ`	No	—	Container timezone (e.g. `Europe/Madrid`)
`POSTGRES_HOST_AUTH_METHOD`	No	`scram-sha-256`	Auth method (dev stacks sometimes use `trust`)

DATABASE_URL in the backend must match these credentials and use the DB hostname reachable from the backend (tobealert-bbdd in Compose, not localhost).

Backend — overview

Category	Variables	Purpose
Bootstrap (first start)	`ADMIN_USER`, `ADMIN_PASSWORD`	First UI superadmin
API admin	`API_ADMIN_USER`, `API_ADMIN_PASSWORD`	HTTP Basic Auth on selected admin API routes
Runtime	See full table below	Loaded at backend startup
Additional	`TOBEALERT_`, `SSL_`, …	Read directly from the environment
Image defaults	`FLASK_SKIP_DOTENV`, `TOBEALERT_ENDPOINT`	Set in the backend image
Config file only	Remaining options	Set in `tobealertd.conf`

Two different “admin” credentials

	UI superadmin	API admin
Variables	`ADMIN_USER`, `ADMIN_PASSWORD`	`API_ADMIN_USER`, `API_ADMIN_PASSWORD`
Used for	Login in the web UI; created by entrypoint	HTTP Basic Auth (`Authorization: Basic …`) on admin API endpoints
Default	Must be set in Compose/K8s	`admin` / `admin` (image default — change in production)

Bootstrap (first container start)

Used only when the backend container starts for the first time; not loaded from tobealertd.conf.

Variable	Required	Description
`ADMIN_USER`	Yes	Username for the bootstrap superadmin (also used as default `ADMIN_USERS` entry and `superadmin` flag in the UI)
`ADMIN_PASSWORD`	Yes	Password for that user on first creation

API admin (HTTP Basic Auth)

Applied at backend startup for HTTP Basic Auth on selected admin API routes.

Variable	Required	Default	Description
`API_ADMIN_USER`	Recommended	`admin`	HTTP Basic Auth username
`API_ADMIN_PASSWORD`	Recommended	`admin`	HTTP Basic Auth password

Change both in production.

Backend — runtime environment variables

These variables are loaded at backend startup. Environment values override matching keys in tobealertd.conf, which in turn override built-in defaults.

General and security

Variable	Default	Description
`DEBUG`	`false`	Debug mode
`TZ`	`UTC`	Timezone for scheduled tasks and internal timestamps. Use this in Docker env (not `TIMEZONE`; see config file)
`SECRET_KEY`	`''`	Signing key for sessions/JWT. Usually auto-generated on first start if conf contains `CHANGEME`
`BASE_URL`	`''`	Public base URL of the backend (absolute links)
`TRUST_PROXY_HEADERS`	`true`	Trust `X-Forwarded-*` headers behind a reverse proxy

Database and Redis

Variable	Default	Description
`DATABASE_URL`	`postgres://tobealert:tobealert@localhost:5432/tobealert`	PostgreSQL connection URL
`DATABASE_NAME`	`tobealert`	Database name (if not only in URL)
`DATABASE_SCHEMA`	`public`	PostgreSQL schema
`REDIS_HOST`	`localhost`	Redis hostname (Compose service name, e.g. `tobealert-redis`)
`REDIS_PORT`	`6379`	Redis TCP port

Redis database indices are fixed (broker 0, backend 1, alerts 2, healthcheck 3).

Authentication and users

Variable	Default	Description
`AUTH_REQUIRED`	`true`	Require authentication for API access
`ADMIN_USERS`	`[ADMIN_USER]`	Comma-separated admin usernames
`SIGNUP_ENABLED`	`true`	Allow user self-registration
`LOCAL_LOGIN_ENABLED`	`true`	Enable local username/password login
`ALLOWED_EMAIL_DOMAINS`	`*`	Comma-separated allowed email domains for signup
`CORS_ORIGINS`	see conf template	Comma-separated allowed CORS origins

LDAP and SAML use external auth providers in the UI / API (auth_providers). They are not configured with global LDAP_* / SAML2_* environment variables.

Mail (SMTP)

Variable	Default	Description
`MAIL_FROM`	—	Sender email address
`SMTP_HOST`	`smtp.office365.com`	SMTP server hostname
`SMTP_PORT`	`587`	SMTP port
`SMTP_PASSWORD`	—	SMTP password
`SMTP_STARTTLS`	`true`	Enable STARTTLS
`SMTP_USE_SSL`	`false`	Use SSL/TLS for SMTP

SMTP_USERNAME is set in tobealertd.conf only (not available as an environment variable).

Plugins, environments, and housekeeping

Variable	Default	Description
`PLUGINS`	see conf template	Comma-separated plugin names
`ALLOWED_ENVIRONMENTS`	`Production`	Comma-separated alert environments accepted
`DEFAULT_ENVIRONMENT`	`Production`	Default environment for webhooks (must be in `ALLOWED_ENVIRONMENTS`)
`ORIGIN_BLACKLIST`	—	Comma-separated origin patterns to reject
`BLACKOUT_DURATION`	`3600`	Default blackout period (seconds)
`NOTIFICATION_BLACKOUT`	`false`	If `true`, set alert status to blackout instead of dropping
`BLACKOUT_ACCEPT`	—	Comma-separated severities still processed during blackout
`DELETE_EXPIRED_AFTER`	`7200`	Delete alerts with status `closed` or `expired` after N seconds since `last_receive_time` (`0` = never)
`DELETE_INFO_AFTER`	`43200`	Delete informational-severity alerts after N seconds (`0` = never)
`DEFAULT_EXPIRED_DELETE_HRS`	—	Legacy: hours, converted to seconds for `DELETE_EXPIRED_AFTER`
`HK_EXPIRED_DELETE_HRS`	—	Legacy alias
`DEFAULT_INFO_DELETE_HRS`	—	Legacy: hours for informational delete
`HK_INFO_DELETE_HRS`	—	Legacy alias
`DELAY_NOTIFICATION`	—	Notification delay in minutes (conf template uses `NOTIFICATION_DELAY`)
`DEMO_MODE`	`false`	Enable demo mode
`DEMO_CLEANUP_HOURS`	`24`	Demo data retention (hours)
`QA_MODE`	`false`	Enable QA mode
`FLAPPING_TIME_WINDOW`	`60`	Flapping detection window (minutes)
`FLAPPING_CHANGE_THRESHOLD`	`4`	Status changes before marking flapping
`CLIPBOARD_TEMPLATE`	—	Template for clipboard copy in the UI
`INSTRUCTION_LINK_TEMPLATE`	`${event}`	Template to resolve instruction paths from alert fields

Backend — additional environment variables

These are read directly from the environment at startup (not merged through the main configuration loader).

Variable	Default	Description
`TOBEALERT_DEBUG`	`false`	Enable debug behaviour in the app
`TOBEALERT_SKIP_PERMISSION_CHECK`	`false`	Skip filesystem permission checks (development only)
`ALERTA_SVR_CONF_FILE`	—	Path to an additional configuration file loaded after `tobealertd.conf`
`SSL_CERT`	—	TLS certificate file path for the backend server
`SSL_KEY`	—	TLS private key file path
`FLASK_DEBUG`	—	Set to `1` for indented JSON in logs
`TOBEALERT_ENDPOINT`	`http://localhost:9000/api`	Default API URL for the CLI client
`ALERTA_API_KEY`	—	API key for the CLI client
`TELEGRAM_TOKEN`	—	Telegram bot token (Telegram webhook)
`TELEGRAM_CHAT_ID`	—	Telegram chat ID
`DASHBOARD_URL`	—	Dashboard URL linked from Telegram notifications
`NOTIFY_<name>`	—	PostgreSQL `NOTIFY` script: custom channel names
`NOTIFY_PARAMETER_<name>`	—	PostgreSQL `NOTIFY` script: parameters (uppercase suffix)

Backend — image built-in environment

Set in the backend image; normally do not override.

Variable	Value	Description
`FLASK_SKIP_DOTENV`	`1`	Disable automatic `.env` file loading
`TOBEALERT_ENDPOINT`	`http://localhost:9000/api`	Default endpoint for CLI tooling inside the image

Plugins and arbitrary env keys

Plugins can read matching environment variables before falling back to tobealertd.conf. In practice, plugin-specific options are usually set in tobealertd.conf using the same key names as in the shipped template.

Configuration file (`tobealertd.conf`)

Python-style KEY = value file. Use for options that are not listed in runtime environment variables, or when you prefer file-based config (SNMP traps, UI columns, etc.).

Template shipped in the image: /tobealert/config/tobealertd.conf.example

Keys commonly set in the file (not available as env vars)

Below: key name in tobealertd.conf, default, and purpose. Set these in tobealertd.conf unless noted otherwise.

Logging

Key	Default	Description
`LOG_CONFIG_FILE`	`''`	External logging config file
`LOG_HANDLERS`	`console,file`	Log handlers
`LOG_FILE`	`/tobealert/logs/tobealertd.log`	Main log file path
`TASKS_LOG_FILE`	`/tobealert/logs/tasks.log`	Background tasks log
`PLUGINS_LOG_FILE`	`/tobealert/logs/plugins.log`	Plugins log
`NOTIFICATIONS_LOG_FILE`	`/tobealert/logs/notifications.log`	Notifications log
`LOG_LEVEL`	`WARNING`	`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`LOG_MAX_BYTES`	`10485760`	Max log file size before rotation
`LOG_BACKUP_COUNT`	`2`	Rotated log files to keep
`LOG_FORMAT`	`default`	Log format name
`LOG_FACILITY`	`local7`	Syslog facility
`LOG_METHODS`	HTTP methods list	Methods to log

API and alerts

Key	Default	Description
`ALARM_MODEL`	`ALERTA`	`ALERTA` or `ISA_18_2`
`QUERY_LIMIT`	`50`	Max alerts per query
`DEFAULT_PAGE_SIZE`	`50`	Default page size
`HISTORY_LIMIT`	`100`	Max alert history entries
`HISTORY_ON_VALUE_CHANGE`	`true`	History on duplicate with value change
`DATABASE_RAISE_ON_ERROR`	`true`	Raise on DB errors
`DEFAULT_FIELD`	`text`	Default Postgres search field

Roles and scopes

Key	Default	Description
`ADMIN_ROLES`	`admin`	Role names treated as admin
`DEFAULT_USER_ROLE`	`user`	Default role for new users
`USER_ROLES`	`user`	Valid roles
`USER_DEFAULT_SCOPES`	`read,write`	Default API scopes
`CUSTOM_SCOPES`	—	Additional scopes
`DELETE_SCOPES`	—	Scopes required to delete alerts
`ALLOW_READONLY`	`false`	Allow read-only mode
`READONLY_SCOPES`	`read`	Read-only scopes
`BASIC_AUTH_REALM`	`ToBeAlert`	Basic auth realm string

Auth proxy

Key	Default	Description
`AUTH_PROXY`	`false`	Enable reverse-proxy authentication
`AUTH_PROXY_USER_HEADER`	`X-Proxy-User`	Header with authenticated username
`AUTH_PROXY_ROLES_HEADER`	`X-Proxy-Roles`	Header with role list
`AUTH_PROXY_ROLES_SEPARATOR`	`,`	Separator for roles header
`AUTH_PROXY_AUTO_SIGNUP`	`true`	Auto-create users from proxy auth

LDAP and SAML (external auth providers only)

LDAP and SAML are configured in the UI or via the auth_providers API. Do not set legacy global keys (LDAP_*, SAML2_*, etc.) for login — they are not used.

Tokens and audit

Key	Default	Description
`TOKEN_EXPIRE_DAYS`	`14`	User token lifetime
`API_KEY_EXPIRE_DAYS`	`365`	API key lifetime
`AUDIT_TRAIL`	`admin`	Audit categories: `admin`, `write`, `auth`
`AUDIT_LOG`	—	Log audit events to application log
`AUDIT_LOG_REDACT`	`true`	Redact sensitive fields in audit log
`AUDIT_LOG_JSON`	`false`	Log alert payload as JSON
`AUDIT_URL`	—	Webhook URL for audit events

CORS and severity

Key	Description
`CORS_ALLOW_HEADERS`	Allowed request headers
`CORS_SUPPORTS_CREDENTIALS`	Allow credentials in CORS
`SEVERITY_MAP`	Custom severity mapping
`DEFAULT_NORMAL_SEVERITY`	Default normal severity
`DEFAULT_INFORM_SEVERITY`	Default informational severity
`DEFAULT_PREVIOUS_SEVERITY`	Default previous severity
`COLOR_MAP`	Severity → colour mapping

Alert timeouts and housekeeping (file)

Key	Default	Description
`ALERT_TIMEOUT`	`86400`	Alert auto-close timeout (s)
`HEARTBEAT_TIMEOUT`	`86400`	Heartbeat timeout (s)
`HEARTBEAT_MAX_LATENCY`	`2000`	Max heartbeat latency (ms)
`ACK_TIMEOUT`	`0`	Auto-unack after N seconds (`0` = off)
`SHELVE_TIMEOUT`	`7200`	Auto-unshelve after N seconds
`CLEANUP_FREQUENCY`	`3600`	Celery Beat interval for `run_housekeeping` (s)
`ENABLED`	`true`	Master switch for housekeeping tasks
`DELETE_CLOSED_AFTER`	`86400`	Legacy / unused — closed alerts are deleted by `DELETE_EXPIRED_AFTER`; kept for old conf files
`DELETE_RESOLVED_AFTER`	`604800`	Legacy / unused — no `resolved` status delete path
`DELETE_CLEARED_AFTER`	`259200`	Legacy / unused — no cleared-severity delete path

Email (file)

Key	Description
`EMAIL_VERIFICATION`	Require email verification on signup
`SMTP_USERNAME`	SMTP username
`MAIL_LOCALHOST`	HELO/EHLO hostname
`SSL_KEY_FILE`	SMTP SSL key
`SSL_CERT_FILE`	SMTP SSL cert
`NOTIFICATION_SEVERITIES`	Severities that trigger email

Web console (file)

Key	Description
`SITE_LOGO_URL`	Company logo URL
`DATE_FORMAT_LONG_DATE`	Long date format string
`DATE_FORMAT_MEDIUM_DATE`	Medium date format
`DATE_FORMAT_SHORT_TIME`	Short time format
`DEFAULT_AUDIO_FILE`	Default alert sound path/URL
`COLUMNS`	Alert list columns
`SORT_LIST_BY`	Default sort order
`DEFAULT_FILTER`	Default alert filter
`ASI_SEVERITY`	Alert Status Indicator severities
`ASI_QUERIES`	ASI preset queries
`DEFAULT_FONT`	Alert list font settings
`ACTIONS`	Custom alert actions
`SERVER_VERSION`	Show server version: `full`, `major`, `off`
`AUTO_REFRESH_INTERVAL`	UI refresh interval (ms)

Routing, plugins, webhooks (file)

Key	Description
`ROUTING_DIST`	Routing distribution name
`PLUGINS_RAISE_ON_ERROR`	Stop on first plugin error
`FWD_DESTINATIONS`	Northbound forward destinations
`GRAFANA_TAGS_AS_ATTRIBUTES`	Grafana webhook: tags as attributes
`GRAFANA_TAGS_AS_TAGS`	Grafana webhook: tags as tags
`POLICY_CONTAINER_PATH`	Policies directory path

Timezone (file)

Key	Default	Description
`TIMEZONE`	`Europe/Madrid`	Display and time formatting in the UI. For Docker env prefer `TZ`

SNMP trap receiver (file)

Key	Default	Description
`SNMP_TRAP_ENABLED`	`false`	Enable built-in SNMP trap receiver
`SNMP_TRAP_BIND_ADDRESS`	`0.0.0.0`	Listen address
`SNMP_TRAP_BIND_PORT`	`162` / `1162` in template	Listen UDP port
`SNMP_TRAP_ALLOWED_IPS`	`[]`	Allowed source IPs/CIDRs
`SNMP_TRAP_RATE_LIMIT_REQUESTS`	`100`	Max traps per window
`SNMP_TRAP_RATE_LIMIT_WINDOW`	`60`	Rate limit window (s)
`SNMP_TRAP_COMMUNITY_STRINGS`	`public`	SNMPv1/v2c communities
`SNMP_TRAP_V3_USERS`	`[]`	SNMPv3 user definitions
`SNMP_TRAP_MIBS_PATH`	—	MIBs directory (template)
`SNMP_TRAP_MIBS`	`ALL`	MIB modules to load (template)
`SNMP_TRAP_DEFAULT_ENVIRONMENT`	—	Default alert environment
`SNMP_TRAP_DEFAULT_SERVICE`	`SNMP`	Default service name
`SNMP_TRAP_DEFAULT_GROUP`	`Network`	Default group

Redis (file)

Key	Default	Description
`REDIS_DB_ALERTS`	`2`	Redis DB index for alerts cache

Minimal Docker Compose example

services:
  tobealert-bbdd:
    image: postgres:17.5-alpine
    environment:
      POSTGRES_USER: tobealert
      POSTGRES_PASSWORD: tobealert
      POSTGRES_DB: tobealert
      TZ: Europe/Madrid

  tobealert-redis:
    image: redis:latest

  tobealert-backend:
    image: tobek8s/tobealert-backend:latest
    environment:
      ADMIN_USER: tbadmin
      ADMIN_PASSWORD: changeme
      API_ADMIN_USER: apiadmin
      API_ADMIN_PASSWORD: changeme-api
      DATABASE_URL: postgres://tobealert:tobealert@tobealert-bbdd:5432/tobealert
      REDIS_HOST: tobealert-redis
      REDIS_PORT: "6379"
      TZ: Europe/Madrid

  tobealert-frontend:
    image: tobek8s/tobealert-frontend:latest
    environment:
      BASE_URL: http://localhost
      API_URL: http://localhost:9000
      BACKEND_SERVICE: tobealert-backend
      BACKEND_PORT: "9000"

Replace placeholder passwords (changeme, changeme-api) and default API admin credentials before production use.

How configuration works​

Environment variable formats​

Frontend (tobealert-frontend)​

PostgreSQL (tobealert-bbdd)​

Backend — overview​

Two different “admin” credentials​

Bootstrap (first container start)​

API admin (HTTP Basic Auth)​

Backend — runtime environment variables​

General and security​

Database and Redis​

Authentication and users​

Mail (SMTP)​

Plugins, environments, and housekeeping​

Backend — additional environment variables​

Backend — image built-in environment​

Plugins and arbitrary env keys​

Configuration file (tobealertd.conf)​

Keys commonly set in the file (not available as env vars)​

Logging​

API and alerts​

Roles and scopes​

Auth proxy​

LDAP and SAML (external auth providers only)​

Tokens and audit​

CORS and severity​

Alert timeouts and housekeeping (file)​

Email (file)​

Web console (file)​

Routing, plugins, webhooks (file)​

Timezone (file)​

SNMP trap receiver (file)​

Redis (file)​

Minimal Docker Compose example​

Related guides​