Configuration¶

OpenWatch follows a 12-factor approach: everything is configured through environment variables, read from your .env file. This page lists the variables that matter for a self-hosted deployment. Start from .env.example, which ships with sensible defaults and inline comments.

Required¶

Variable	Purpose
`SECRET_KEY`	Flask signing key for sessions and CSRF tokens. Generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`.
`MASTER_KEY`	Fernet key used to encrypt stored credentials at rest. Generate with `python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`.
`DATABASE_URL`	PostgreSQL connection string, for example `postgresql://explorer:explorer@db:5432/openwatch`. With the bundled compose file the host is the `db` service.
`FLOWER_PASSWORD`	Basic-auth password for the Flower dashboard. The compose file refuses to start Flower without it.

MASTER_KEY is unrecoverable if lost

Every *_cipher value (OpenStack passwords, SMTP passwords, OAuth and OIDC secrets, TOTP secrets, and more) is encrypted with MASTER_KEY. If you lose it, those values cannot be decrypted and must be re-entered. Back it up securely and do not rotate it casually.

Common¶

Variable	Default	Purpose
`TALISMAN_FORCE_HTTPS`	`false`	Set to `true` in production behind an HTTPS reverse proxy. Leave `false` for local HTTP.
`OPENSTACK_CACHE_TTL`	`300`	Seconds a cost-cache entry stays fresh before a background refresh.
`ALERT_CHECK_INTERVAL`	`300`	Seconds between cost-alert evaluations.
`DATA_REFRESH_INTERVAL`	`3600`	Seconds between full background refreshes of all projects.
`CELERY_BROKER_URL`	`redis://redis:6379/0`	Redis broker for the Celery task queue.
`CELERY_RESULT_BACKEND`	`redis://redis:6379/0`	Redis backend for task results.
`RATELIMIT_STORAGE_URI`	`redis://redis:6379/1`	Redis store for rate-limit counters (uses DB 1 to avoid clashing with Celery on DB 0).
`FLOWER_USER`	`admin`	Basic-auth user for the Flower dashboard.

Edition and licensing¶

Variable	Purpose
`OPENWATCH_EDITION`	Build-time argument (`community`, `enterprise`, or `saas`) baked into the image. It cannot be overridden at runtime. See Editions and plan limits.
`LICENSE_KEY`	Enterprise only. The signed Ed25519 licence that unlocks your plan limits. Without it, an Enterprise image falls back to the `essential` plan.

Admin console¶

The super-admin console runs as a separate container for isolation.

Variable	Purpose
`ADMIN_SECRET_KEY`	Distinct signing key for the admin console sessions and CSRF, so a stolen main-app session can never authenticate there. Set it in production; if unset, the console falls back to `SECRET_KEY` and is no longer isolated.
`ADMIN_DATABASE_URL`	Optional. A least-privilege PostgreSQL role for the admin console. When set, the console connects with it instead of the full-privilege main DSN.

At-rest encryption provider¶

By default OpenWatch encrypts with the local MASTER_KEY (the fernet provider). It can optionally use HashiCorp Vault Transit instead.

Variable	Purpose
`CRYPTO_PROVIDER`	`fernet` or `vault`. Leave empty to auto-derive (`vault` when `VAULT_ADDR` is set, otherwise `fernet`).
`VAULT_ADDR`, `VAULT_TRANSIT_MOUNT`, `VAULT_TRANSIT_KEY`	Vault Transit endpoint and key, when using the `vault` provider.
`VAULT_TOKEN` or `VAULT_ROLE_ID` + `VAULT_SECRET_ID`	Vault authentication: a static token for development, or an AppRole for production.

Most deployments use Fernet

Vault is optional and aimed at deployments that want encrypt and decrypt to happen server-side. If you are not sure, leave the Vault variables empty and use MASTER_KEY.

OAuth, OIDC and Turnstile¶

These are configured through the web interface, not environment variables:

Google and Microsoft sign-in: set in the super-admin site settings.
Per-organisation OIDC: set by an org admin under Single sign-on.
Turnstile (bot protection) keys: set in site settings.

Database migrations¶

Schema migrations run automatically when the stack starts, before the app serves requests, so a running deployment never sees a stale schema. You do not run migrations by hand for a normal upgrade; pull the new image, rebuild, and start.

SMTP (outgoing email)¶

Email delivery (verification, invitations, alerts by email) is configured in the app: globally in the super-admin site settings, or per organisation by an org admin. Passwords entered there are encrypted at rest with the active provider.