Settings file and environment variables

Complete reference for configuring ToBeAlert in Docker, Kubernetes, and bare-metal deployments — and how those settings interact with Backend Config in the UI.

Most operators start here

If you only need to change alert retention, timeouts, or SMTP for account emails, use Management → Backend Config in the UI. Use this page when you deploy containers, set secrets, or need the full list of keys.

How configuration really works

ToBeAlert loads settings in this order. Higher layers win only where the backend re-reads that key from the environment.

Priority	Mechanism	What it covers
1	Environment variables (selected keys only)	Keys reloaded through get_config() at backend startup — see Runtime env vars
2	Extra conf file ALERTA_SVR_CONF_FILE	Optional override file loaded after the main conf
3	/tobealert/config/tobealertd.conf	Full backend settings; also what Backend Config writes
4	Built-in defaults (settings.py)	Defaults shipped in the backend image

Env does not override everything

Many important keys — including ALERT_TIMEOUT, CLEANUP_FREQUENCY, ACK_TIMEOUT, SHELVE_TIMEOUT, and ENABLED — are not read from the environment. Setting ALERT_TIMEOUT=60 as a Docker env var has no effect. Put them in tobealertd.conf or change them in Backend Config.

The active settings file path is fixed: /tobealert/config/tobealertd.conf.

On first backend container start the entrypoint:

1. Copies tobealertd.conf.example → tobealertd.conf (if missing)
2. Replaces SECRET_KEY = 'CHANGEME' with a random value
3. Creates the bootstrap UI user from ADMIN_USER / ADMIN_PASSWORD only if that login does not already exist in PostgreSQL

See Bootstrap — ADMIN_PASSWORD is not re-applied on later restarts.

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

Backend Config UI vs env vs conf

Where you change it	Persists to	Applies to running API	Applies to Celery Beat/workers
Docker/K8s env (supported keys)	Process env	On restart	On restart
tobealertd.conf edit	File	On restart (or UI write)	On restart
Backend Config UI	Writes tobealertd.conf + updates API memory	Immediately in the API process	Retention keys trigger worker pool restart; Beat interval may need a Celery Beat restart

If the same key exists as env and in the conf file, at the next backend start the env value wins (for keys in the runtime list below). The UI can still rewrite the file, but the process keeps using the env until you remove the env override.

---

Alert lifecycle: timeout, expiry, and cleanup

This is the section that answers “I set delete after 1 minute — why are alerts still there?”

There are two different clocks:

Setting	What it controls	Default
Alert timeout (ALERT_TIMEOUT)	When an open alert becomes expired (status change, not delete)	86400 s (24 h)
Retain closed/expired (DELETE_EXPIRED_AFTER)	How old a closed or expired alert must be (from last_receive_time) before it is deleted	7200 s (2 h)
Retain informational (DELETE_INFO_AFTER)	Same idea for informational-severity alerts	43200 s (12 h)
Housekeeping interval (CLEANUP_FREQUENCY)	How often the cleaner job wakes up to delete / unack / unshelve	3600 s (1 h)
Housekeeping enabled (ENABLED)	Master switch for the cleaner job only	true

Step by step

1. Receive — An alert is open. Its timeout comes from the payload, or defaults to ALERT_TIMEOUT (24 hours).
2. Expire (status) — Celery task expire_alerts runs about every 5 seconds. When last_receive_time + timeout is in the past, status becomes expired. This does not wait for housekeeping.
3. Delete (retention) — Celery task run_housekeeping runs every CLEANUP_FREQUENCY seconds (default hourly). It deletes rows where:
   • status is closed or expired, and
   • last_receive_time is older than DELETE_EXPIRED_AFTER
   • (separately) informational severity older than DELETE_INFO_AFTER
4. Ack / shelve — The same housekeeping run also auto-unacks / auto-unshelves using ACK_TIMEOUT / SHELVE_TIMEOUT.
5. History cleanup — The same run deletes policy/tool run history older than 30 days (hardcoded; not configurable).

Retention vs interval (the common confusion)

time until delete ≈ DELETE_*_AFTER  +  (0 … CLEANUP_FREQUENCY)  + worker latency

• DELETE_*_AFTER = “how old must the alert be?”
• CLEANUP_FREQUENCY = “how often do we look?”

Example: retain = 60 seconds, interval = 3600 seconds:

• The alert becomes eligible for delete 1 minute after last_receive_time.
• The cleaner only wakes once per hour → in the worst case the row stays until the next hourly run.
• So you can wait up to ~1 hour + 1 minute, not “about 1 minute”.

If you need near-real-time deletion, lower both:

• set a small DELETE_EXPIRED_AFTER, and
• set a small CLEANUP_FREQUENCY (for example 60), then restart Celery Beat so the new schedule is picked up.

Extra delete path in expire_alerts

After marking alerts expired, expire_alerts can also DELETE expired rows where update_time + timeout has elapsed again. With default timeouts (24 h) this path usually fires later than housekeeping retention (2 h). Treat DELETE_EXPIRED_AFTER + CLEANUP_FREQUENCY as the retention controls you care about.

What ENABLED=false does not stop

Turning off housekeeping does not stop expire_alerts. Open alerts still become expired every ~5 seconds based on timeout — they just are not deleted / unacked / unshelved by housekeeping until you enable it again.

Where to configure

Goal	Prefer
Day-to-day retention / timeouts	Backend Config → Housekeeping / Alerts / Timeouts
Deploy-time defaults in GitOps	tobealertd.conf mounted into the backend
Secrets (DB URL, admin password)	Environment variables

---

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. For HTTPS see HTTPS and TLS.
API_URL	Yes	—	URL the browser uses for API calls. Example: http://localhost:9000 or https://alerts.example.com:9000. Do not append /api. For HTTPS this must be https://.
BACKEND_SERVICE	Yes	—	Hostname nginx uses as upstream for /api and /management. In Compose: backend service name. In Kubernetes: backend Service DNS name.
BACKEND_PORT	Yes	9000	TCP port of the backend upstream

Nginx proxies to http://BACKEND_SERVICE:BACKEND_PORT using the env values above. BACKEND_SERVICE must resolve on the same network as the frontend (not localhost unless using host networking).

---

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)

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

---

Backend — overview

Category	Variables / keys	Purpose
Bootstrap	ADMIN_USER, ADMIN_PASSWORD	First UI superadmin
API admin	API_ADMIN_USER, API_ADMIN_PASSWORD	HTTP Basic Auth on selected admin API routes
Runtime env	Subset loaded via get_config()	Safe to set as Docker/K8s env
Additional env	Entrypoint / CLI / webhooks	Read outside the main loader
Conf / Backend Config	Timeouts, housekeeping, logging, templates, …	File or UI — not env unless listed above

Two different “admin” credentials

	UI superadmin	API admin
Variables	ADMIN_USER, ADMIN_PASSWORD	API_ADMIN_USER, API_ADMIN_PASSWORD
Used for	Web UI login; created by entrypoint once (password is not re-read from env)	HTTP Basic Auth on admin API endpoints
Default	Must be set in Compose/K8s	Image default admin / admin — change in production

---

Bootstrap (first container start)

These variables are read by the backend entrypoint, not from tobealertd.conf.

ADMIN_PASSWORD applies only on first user creation

The bootstrap UI user (ADMIN_USER, typically tbadmin) is created once: the first time the backend starts and that login is not already in PostgreSQL.

ADMIN_PASSWORD is hashed into the database at that moment. After the user exists, changing the env var (Compose, Kubernetes, systemd, .env) has no effect — the entrypoint skips creation and never updates the stored password.

Set a strong ADMIN_PASSWORD before the first backend start. To change it later, use Access Control → Users → Change password (Managing users), not the environment variable.

Variable	Required	Description
ADMIN_USER	Yes	Username for the bootstrap superadmin (also seeds ADMIN_USERS at runtime)
ADMIN_PASSWORD	Yes	Password used only when the bootstrap user is first created
CELERY_WORKER_CONCURRENCY	No	Worker concurrency (default 1)

---

API admin (HTTP Basic Auth)

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

---

Backend — runtime environment variables

These keys are reloaded at backend startup from the environment (overriding conf for the same key).

General and security

Variable	Default	Description
DEBUG	false	Debug mode. Prefer this over legacy TOBEALERT_DEBUG / FLASK_DEBUG.
TZ	UTC	Clock for scheduled tasks and timestamps. Set TZ. Default UTC. A leftover TIMEZONE key is ignored.
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-* behind a reverse proxy

Database and Redis

Variable	Default	Description
DATABASE_URL	postgres://tobealert-bbdd:5432 (loader)	PostgreSQL connection URL
DATABASE_NAME	tobealert	Database name
DATABASE_SCHEMA	public	PostgreSQL schema
REDIS_HOST	localhost	Redis hostname (Compose service name, e.g. tobealert-redis)
REDIS_PORT	6379	Redis TCP port
CELERY_RESULT_EXPIRES	300	TTL (seconds) for Celery task results

Redis database indices used by the backend are fixed in code (broker 0, result backend 1, alerts cache 2, healthcheck 3). They are not configurable.

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 settings.py	Allowed browser origins for Flask-CORS (comma-separated in env)

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) — app-internal only

Used for signup verification / password reset — not for alert notification methods (those have their own SMTP in Notifications).

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 / Backend Config only (not as env).

Plugins and retention (env-capable)

Variable	Default	Description
PLUGINS	see conf template	Comma-separated plugin names
WORKFLOWS_ENABLED	false	Enable workflow execution
DELETE_EXPIRED_AFTER	7200	Delete closed or expired after N seconds since last_receive_time (0 = never). See Alert lifecycle.
DELETE_INFO_AFTER	43200	Delete informational-severity alerts after N seconds (0 = never)
TOOL_HISTORY_RETENTION_DAYS	30	Delete tool executions older than N days (0 = never). Also in Backend Config.
POLICY_HISTORY_RETENTION_DAYS	30	Delete policy executions older than N days (0 = never). Also in Backend Config.
NOTIFICATION_HISTORY_RETENTION_DAYS	30	Delete notification rule executions older than N days (0 = never). Also in Backend Config.
DEFAULT_EXPIRED_DELETE_HRS / HK_EXPIRED_DELETE_HRS	0	Legacy hours. If non-zero, they override DELETE_EXPIRED_AFTER (converted to seconds). Prefer seconds.
DEFAULT_INFO_DELETE_HRS / HK_INFO_DELETE_HRS	0	Legacy hours for informational delete — same override behaviour
DEMO_MODE	false	Enable demo mode
DEMO_CLEANUP_HOURS	24	Demo data retention (hours)
QA_MODE	false	Enable QA mode flag
FLAPPING_TIME_WINDOW	60	Flapping detection window (minutes)
FLAPPING_CHANGE_THRESHOLD	4	Status changes before marking flapping
INSTRUCTION_LINK_TEMPLATE	event-based template	Builds the wiki path from alert fields (default uses the alert event; see Instructions from alerts)
NOTIFICATION_DELAY	—	Delay-plugin fallback in minutes (not a notification hold). See Backend Config.

Prefer NOTIFICATION_DELAY (minutes) in conf / Backend Config. An integer minutesDelayed on the alert payload (including 0) overrides this value.

---

Backend — additional environment variables

Read outside (or in addition to) the main configuration loader.

Variable	Default	Description
TOBEALERT_DEBUG	false	Legacy debug alias — prefer DEBUG
FLASK_DEBUG	—	Legacy; can affect log formatting
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 / SSL_KEY	—	PEM paths inside the backend container for HTTPS on port 9000. See HTTPS and TLS.
TOBEALERT_ENDPOINT	http://localhost:9000/api	Default API URL for the CLI client
ALERTA_API_KEY	—	API key for the CLI client
NOTIFY_<name> / NOTIFY_PARAMETER_<name>	—	PostgreSQL NOTIFY script channels / parameters
NO_COLOR / TOBEALERT_STARTUP_NO_COLOR	—	Disable colour in startup logs
FLASK_SKIP_DOTENV	1 (image)	Disable automatic .env loading — leave as-is

---

Configuration file (tobealertd.conf)

Python-style KEY = value file. Use for options that are not in the runtime env list, or when you prefer file-based / UI-managed config.

Template: /tobealert/config/tobealertd.conf.example

Many of these are also editable under Management → Backend Config. Prefer the UI for day-to-day changes.

Alert timeouts and housekeeping (file / UI — not env)

Key	Default	Description
ALERT_TIMEOUT	86400	Default alert timeout (s). After last_receive_time + timeout, status → expired.
ACK_TIMEOUT	0	Auto-unack after N seconds (0 = off)
SHELVE_TIMEOUT	7200	Auto-unshelve after N seconds (0 = off)
HEARTBEAT_TIMEOUT	86400	Heartbeat timeout (s)
HEARTBEAT_MAX_LATENCY	2000	Max heartbeat latency (ms)
CLEANUP_FREQUENCY	3600	How often run_housekeeping runs (s). Not the retention age.
ENABLED	true	Master switch for run_housekeeping only
TOOL_HISTORY_RETENTION_DAYS	30	Delete tool executions older than N days (0 = never). Env, conf, or Backend Config.
POLICY_HISTORY_RETENTION_DAYS	30	Delete policy executions older than N days (0 = never). Env, conf, or Backend Config.
NOTIFICATION_HISTORY_RETENTION_DAYS	30	Delete notification rule executions older than N days (0 = never). Env, conf, or Backend Config.
DELETE_EXPIRED_AFTER	7200	Also settable as env — see lifecycle
DELETE_INFO_AFTER	43200	Also settable as env
NOTIFICATION_DELAY	2	Delay-plugin fallback (minutes). Prefer this key in conf/UI. Payload minutesDelayed (integer) overrides it.

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, roles, tokens, audit

Key	Default	Description
ALARM_MODEL	ALERTA	ALERTA or ISA_18_2
DEFAULT_PAGE_SIZE	50	Default page size for paginated APIs
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
TOKEN_EXPIRE_DAYS	14	User JWT lifetime (days)
API_KEY_EXPIRE_DAYS	365	API key lifetime (days)
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_URL	—	Webhook URL for audit events

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

Email (file / UI)

Key	Description
EMAIL_VERIFICATION	Require email verification on signup
SMTP_USERNAME	SMTP username
MAIL_LOCALHOST	HELO/EHLO hostname
SSL_KEY_FILE / SSL_CERT_FILE	SMTP client SSL material

Server version and templates (file)

Alert list chrome — columns, sort, default filter, auto-refresh, site logo, date formats, default sound, font — is not configured in tobealertd.conf. Those choices live in the web console. Old Alerta keys left in a conf file are loaded by Flask but ignored by the product; see What not to keep.

These keys remain valid in the settings file (INSTRUCTION_LINK_TEMPLATE is also runtime env):

Key	Description
SERVER_VERSION	Show server version: full, major, off
INSTRUCTION_LINK_TEMPLATE	Builds the wiki path from alert fields (default uses the alert event; see Instructions from alerts)

Optional limits (file)

Key	Default	Description
SCHEDULED_POLICIES_ALERT_QUERY	internal default	Query used by scheduled policies
SCHEDULED_POLICIES_ALERT_LIMIT	1000	Max alerts per scheduled-policy run
RECURRING_NOTIFICATIONS_ALERT_LIMIT	1000	Max alerts per recurring-notification pass

SNMP traps

SNMP trap ingestion is handled by the ToBeAlert collector, not the API process. Do not put SNMP_TRAP_* keys in tobealertd.conf — the backend ignores them.

---

What not to keep / common mistakes

Item	Why
DELETE_CLOSED_AFTER / DELETE_RESOLVED_AFTER / DELETE_CLEARED_AFTER	Removed from defaults; if still in an old conf file they are ignored. Closed alerts use DELETE_EXPIRED_AFTER.
DEFAULT_*_DELETE_HRS / HK_*_DELETE_HRS	Legacy hour-based overrides. Prefer DELETE_*_AFTER in seconds. If hours ≠ 0 they win and confuse operators.
Alerta leftovers: SITE_LOGO_URL, DATE_FORMAT_LONG_DATE, DATE_FORMAT_MEDIUM_DATE, DATE_FORMAT_SHORT_TIME, DEFAULT_AUDIO_FILE, COLUMNS, SORT_LIST_BY, DEFAULT_FILTER, ASI_SEVERITY, ASI_QUERIES, DEFAULT_FONT, AUTO_REFRESH_INTERVAL, ROUTING_DIST, FWD_DESTINATIONS, CLIPBOARD_TEMPLATE	Removed from defaults. If they remain in an old tobealertd.conf, Flask still loads them but the product ignores them. Do not treat them as live settings. Alert list chrome is not configured here. SPA clipboard copy does not use a server template.
HISTORY_LIMIT, HISTORY_ON_VALUE_CHANGE, DEFAULT_FIELD, ACTIONS	Removed from defaults and from the config loader. Not live settings.
NOTIFICATION_SEVERITIES	Removed. Built-in mail paths do not read this key.
ORIGIN_BLACKLIST	Removed. Not a live reject list.
BLACKOUT_DURATION, NOTIFICATION_BLACKOUT, BLACKOUT_ACCEPT	Removed. Blackout behaviour is not configured with these keys.
GRAFANA_TAGS_AS_ATTRIBUTES, GRAFANA_TAGS_AS_TAGS	Removed Grafana ingest leftovers. Not live settings.
POLICY_CONTAINER_PATH	Removed. Not a live setting.
REDIS_DB_ALERTS (or any REDIS_DB_* override)	Redis indices are fixed (0/1/2/3). This is not a configurable key.
CELERY as a conf dict	Not an editable setting. The process rebuilds the Celery app; use CELERY_WORKER_CONCURRENCY / CELERY_RESULT_EXPIRES only.
SNMP_TRAP_* in backend conf	Ignored by the API — configure traps on the collector.
TIMEZONE (conf or TIMEZONE= env)	Removed from defaults and the loader. Leftover only — do not use. Set TZ.
ALLOWED_ENVIRONMENTS, DEFAULT_ENVIRONMENT	Removed from defaults and the loader. Leftover Flask/env only — the product ignores them.
QUERY_LIMIT	Removed. Runtime lists use DEFAULT_PAGE_SIZE (50). GET /config does not expose query_limit.
DELAY_NOTIFICATION	Removed alias. Leftover Flask/env only — the product ignores it. Use NOTIFICATION_DELAY.
TELEGRAM_TOKEN, TELEGRAM_CHAT_ID, DASHBOARD_URL	Removed. The inbound Alerta Telegram webhook is gone. Leftover Flask/env only — the product ignores them. Notifications Telegram is configured as UI methods, not these env keys.
ALERT_TIMEOUT= / CLEANUP_FREQUENCY= as Docker env	Not read from env — use conf or Backend Config.
Global LDAP_* / SAML2_*	Replaced by External auth providers in the UI.
Expecting ENABLED=false to stop expiry	Only stops housekeeping deletes; expire_alerts still runs.

---

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
      # Retention CAN be set as env (these keys are in get_config):
      # DELETE_EXPIRED_AFTER: "7200"
      # DELETE_INFO_AFTER: "43200"
      # Alert timeout / cleanup frequency: set in tobealertd.conf or Backend Config — NOT here.

  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 before production use.

---

Related guides

• HTTPS and TLS
• License setup
• Docker · Linux · Windows · Kubernetes
• Backend Config — configuration settings (UI for housekeeping, timeouts, auth, SMTP)