Watchflare docs

On this page

Hub environment variables

Quick-reference table of all Watchflare Hub environment variables with types and defaults. For full explanations and usage context, see the Configuration guide.

All Hub configuration is done through environment variables. When using Docker Compose, place them in a .env file next to docker-compose.yml.

For full explanations and usage guidance, see Configuration.

Required

Variable	Min length	Description
`POSTGRES_PASSWORD`	—	Database password. The binary falls back to `watchflare_dev` if unset — always set this in production. Docker Compose enforces it via `:?`.
`JWT_SECRET`	32 chars	Signs user session cookies and encrypts TOTP secrets for 2FA. Hub exits at startup if missing or too short. Changing this value invalidates all active sessions and disables 2FA for enrolled users.
`NOTIFICATION_ENCRYPTION_KEY`	32 chars	Encrypts SMTP credentials and notification channel URLs (Discord, Slack, etc.) at rest. Optional for the Hub binary: if not set, notification storage is disabled. Required by the Docker Compose file (set via `:?` syntax) so it is always generated upfront, even if you don’t plan to use notifications yet. If set, must be at least 32 characters (Hub exits otherwise).

Database

Variable	Default	Description
`POSTGRES_HOST`	`localhost`	PostgreSQL hostname. Docker Compose sets this to `postgres`.
`POSTGRES_PORT`	`5432`	PostgreSQL port
`POSTGRES_USER`	`watchflare`	Database user
`POSTGRES_PASSWORD`	`watchflare_dev`	Database password
`POSTGRES_DB`	`watchflare`	Database name
`POSTGRES_SSLMODE`	`disable`	PostgreSQL SSL mode

Ports

Variable	Default	Description
`HUB_PORT`	`8080`	Docker only. External port for the HTTP server. The internal container port is always `8080`.
`GRPC_PORT`	`50051`	gRPC port for agent connections

TLS

Variable	Default	Description
`TLS_MODE`	`auto`	`auto` — Hub generates its own CA and server certificate. `custom` — provide your own files.
`TLS_PKI_DIR`	`/var/lib/watchflare/pki`	Directory for auto-generated certificates (`auto` mode only)
`TLS_CERT_FILE`	—	Server certificate path (`custom` mode only)
`TLS_KEY_FILE`	—	Server private key path (`custom` mode only)
`TLS_CA_FILE`	—	CA certificate path, sent to agents at registration (`custom` mode only)

Variable	Default	Description
`COOKIE_SECURE`	(auto)	Force `Secure` flag: `true` or `false`. Omit to use auto-detection (recommended).
`COOKIE_DOMAIN`	(empty)	Cookie domain — set to your domain when using a reverse proxy
`TRUSTED_PROXIES`	`127.0.0.1,::1`	Comma-separated IPs allowed to set `X-Forwarded-Proto`

gRPC security

Variable	Default	Description
`GRPC_TIMESTAMP_WINDOW`	`300`	HMAC timestamp window in seconds (±window). Requests outside this range are rejected.

Environment

Variable	Default	Description
`ENV`	`development`	Set to `production` in deployed instances. Switches Gin to release mode. Docker Compose sets this automatically.
`CORS_ORIGINS`	`http://localhost:5173`	Comma-separated allowed CORS origins. Not needed for Docker or binary installs.

Quick-start `.env`

POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
NOTIFICATION_ENCRYPTION_KEY=$(openssl rand -base64 32)

All other variables have sensible defaults for a standard Docker Compose deployment.