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.