Configuration

The forum is configured from its environment. This page explains how settings resolve and the essentials to set. For the full list, see Environment variables.

How configuration resolves

On start-up the app builds its configuration in this order (later steps win):

1. Built-in defaults.
2. An optional Python config file (bluset.cfg) if you point the app at one.
3. A file named by the BLUSET_SETTINGS environment variable.
4. Every BLUSET_-prefixed environment variable — the prefix is stripped and the value parsed, then set on the config (so BLUSET_DEBUG=true sets DEBUG).
5. The canonical contract names below are mapped onto the config.

For most self-hosters, setting the canonical names (plus any BLUSET_ overrides you need) is all you require — you don’t have to author a bluset.cfg file.

Canonical settings (the boot contract)

Variable	Required	Purpose
DATABASE_URL	yes (production)	PostgreSQL connection URL. Its presence puts the app in production mode.
SECRET_KEY	yes (production)	Flask secret for sessions/signing. Missing it aborts start-up.
API_KEY	if using the platform API	Bootstrap key for API access.
JWT_SECRET	if using token auth	Secret for JWT signing.

Redis is not one of the prefix-free names — set BLUSET_REDIS_URL and BLUSET_REDIS_ENABLED=True to use it for cache, rate-limiting, and Celery (without BLUSET_REDIS_ENABLED=True the app falls back to in-process cache and an in-memory rate limiter).

Production mode (triggered by DATABASE_URL, or forced with BLUSET_PRODUCTION) changes safe defaults for you: DEBUG is forced off, and session cookies become Secure / HttpOnly / SameSite. If SECRET_KEY or the database URL is missing in production mode, the app refuses to start rather than run insecurely.

Email (SMTP)

Outbound email uses Flask-Mail settings, which take the BLUSET_ prefix:

• BLUSET_MAIL_SERVER, BLUSET_MAIL_PORT, BLUSET_MAIL_USE_TLS / BLUSET_MAIL_USE_SSL
• BLUSET_MAIL_USERNAME, BLUSET_MAIL_PASSWORD
• BLUSET_MAIL_DEFAULT_SENDER

Defaults are localhost:25 with TLS off, so set these for real delivery. Email is required for account activation, password resets, invites, and help-desk notifications.

The bluset.cfg alternative

If you prefer a config file, generate one with:

bluset makeconfig

Keep secrets out of the file and read them from the environment — config files get backed up and copied, which multiplies the places a secret can leak. BLUSET_-prefixed environment variables still override the file, so you can ship a secret-free bluset.cfg and layer real values on top per environment.

Runtime settings worth knowing

• BLUSET_AUTO_MIGRATE — database migrations run on container start by default (True); set it False if you prefer to run migrations explicitly (see Deploy with Docker).
• GUNICORN_BIND — where the web server listens. For a container behind a reverse proxy over TCP, set 0.0.0.0:8000; the default binds a Unix socket.
• BLUSET_SENTRY_DSN / BLUSET_SENTRY_ENVIRONMENT — optional error tracking.
• BLUSET_CELERY_BEAT_ENABLED — enable scheduled background tasks in production.

Feature tiers

The forum’s optional surfaces (the REST API, CMS, and help desk) are gated by feature flags seeded at boot from FORUM_ENABLED, API_ENABLED, and an optional FEATURE_SET allowlist. This is how managed plans map to features; self-hosters can set them directly. See Environment variables and the CLI reference (features, seed-features).