Configuration Reference¶

Complete reference for configuring Bifolk through environment variables and Docker secrets.

Target Audience: System administrators, DevOps engineers

Configuration Priority¶

Bifolk uses a three-tier configuration system:

Docker Secrets (highest priority) - Files in /run/secrets/
Environment Variables - Set in .env or directly
Default Values (lowest priority) - Safe development defaults

The configuration flow:

Container Startup → docker-entrypoint.sh → generate_config.py
  reads: Secrets → Environment → Defaults
  generates: bifolk.json → Django settings.py

Core Django Settings¶

Variable	Default	Description
`DJANGO_DEBUG`	`True`	Debug mode. Set to `False` in production
`DJANGO_SECRET_KEY`	(auto-generated)	Django cryptographic secret key
`DJANGO_ALLOWED_HOSTS`	`localhost,127.0.0.1`	Comma-separated list of allowed hostnames
`DJANGO_CSRF_TRUSTED_ORIGINS`	(none)	CSRF trusted origins with protocol (e.g., `https://example.com`)
`SITE_DOMAIN`	(first `ALLOWED_HOSTS` entry)	Public hostname of the deployment (e.g., `bee.example.org`). Used in invitation emails, allauth emails, and QR codes. Must be set correctly so links in emails point to the right address.
`TIME_ZONE`	`Europe/Berlin`	Timezone for the application

Database Settings¶

SQLite (Default)¶

When no DB_HOST or DB_NAME is set, Bifolk uses SQLite:

Variable	Default	Description
`DB_ENGINE`	(auto-detected)	Explicitly set to `django.db.backends.sqlite3`
`DB_PATH`	`/bifolk/db/db.sqlite3`	Path to SQLite database file

PostgreSQL¶

Variable	Default	Description
`DB_ENGINE`	(auto-detected)	Set to `django.db.backends.postgresql`
`DB_NAME`	`bifolk`	Database name
`DB_USER`	`bifolk`	Database user
`DB_PASSWORD`	(none)	Database password (use Docker secrets)
`DB_HOST`	`bifolk-db`	Database host
`DB_PORT`	`5432`	Database port

Email Settings¶

Variable	Default	Description
`EMAIL_HOST`	`smtp.example.com`	SMTP server hostname
`EMAIL_PORT`	`587`	SMTP port (587 for STARTTLS, 465 for implicit SSL)
`EMAIL_USE_TLS`	`True`	Use STARTTLS encryption (port 587)
`EMAIL_USE_SSL`	`False`	Use implicit SSL encryption (port 465)
`EMAIL_USER`	`noreply@example.com`	SMTP username
`EMAIL_PASSWORD`	(none)	SMTP password (use Docker secrets)
`DEFAULT_FROM_EMAIL`	`noreply@example.com`	Default "from" address
`SERVER_EMAIL`	`root@localhost`	Server email for error notifications

Warning

EMAIL_USE_TLS and EMAIL_USE_SSL are mutually exclusive. Set exactly one to True:

Port 587 (STARTTLS): EMAIL_USE_TLS=True, EMAIL_USE_SSL=False
Port 465 (implicit SSL): EMAIL_USE_TLS=False, EMAIL_USE_SSL=True

Note

When DJANGO_DEBUG=True, emails are printed to the console regardless of SMTP settings.

Authentication Settings¶

Variable	Default	Description
`ALLOW_SELF_REGISTRATION`	`True`	Allow users to register themselves
`REQUIRE_EMAIL_VERIFICATION`	`True`	Require email verification after registration
`SESSION_TOKEN_LIFETIME_HOURS`	`168`	Session lifetime in hours (default: 7 days)

MFA Settings¶

Variable	Default	Description
`MFA_TOTP_ISSUER`	`Bifolk`	Name shown in authenticator apps
`MFA_REQUIRED`	`none`	MFA enforcement: `none`, `staff`, or `all`
`MFA_GRACE_PERIOD_DAYS`	`7`	Days to set up MFA before enforcement

OIDC / Single Sign-On Settings¶

OIDC is only enabled when OIDC_CLIENT_ID is configured.

Variable	Default	Description
`OIDC_PROVIDER_ID`	`authentik`	Provider ID (used in URLs)
`OIDC_PROVIDER_NAME`	`Single Sign-On`	Display name on login page
`OIDC_CLIENT_ID`	(none)	OAuth2 client ID
`OIDC_CLIENT_SECRET`	(none)	OAuth2 client secret (use Docker secrets)
`OIDC_SERVER_URL`	(none)	OIDC discovery base URL
`DISABLE_STANDARD_LOGIN`	`False`	Hide username/password login form

PWA Settings¶

Variable	Default	Description
`PWA_ENABLED`	`True`	Enable Progressive Web App functionality

Variable	Default	Description
`COOKIE_CONSENT_VERSION`	`1.0`	Increment to force re-consent
`COOKIE_CONSENT_ANALYTICS_ENABLED`	`False`	Show analytics cookie options

Logging Settings¶

Variable	Default	Description
`LOG_LEVEL`	`INFO`	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
`LOG_RETENTION_DAYS`	`14`	Days to keep rotated log files (rotated daily at midnight)
`LOG_TO_CONSOLE`	`True`	Output logs to Docker logs
`LOG_TO_FILE`	`True`	Write logs to `/bifolk/logs/`

Proxy Settings¶

Variable	Default	Description
`TRUSTED_PROXIES`	(none)	Comma-separated list of proxy IP addresses trusted to set `X-Forwarded-For` / `X-Real-IP` headers
`TRUST_X_FORWARDED_PROTO`	`False`	Set to `True` when Bifolk runs behind an HTTPS-terminating reverse proxy. Tells Django to read the `X-Forwarded-Proto` header so that invitation links and all other generated URLs use `https://` instead of `http://`. Only enable when you control the proxy.

Important

Only set TRUSTED_PROXIES if you run Bifolk behind a reverse proxy (e.g. Traefik, Nginx). Leave it empty for direct deployments.

When empty (default), proxy headers are ignored and the raw TCP connection address (REMOTE_ADDR) is always used as the client IP. This is the safe default.

When set, proxy headers are trusted only when the connection comes from one of the listed IPs — preventing clients from spoofing their IP address in audit logs.

Example (single Traefik container on a Docker network):

TRUSTED_PROXIES=172.17.0.1

Multiple proxies:

TRUSTED_PROXIES=172.17.0.1,10.0.0.1

Error Tracking Settings¶

Bifolk can report unhandled exceptions to a Sentry-compatible error tracking service such as a self-hosted GlitchTip instance. Error tracking is disabled by default and only activated when SENTRY_DSN is set.

Variable	Default	Description
`SENTRY_DSN`	(none)	DSN from your Sentry/GlitchTip project settings. Leave unset to disable error tracking.
`SENTRY_TRACES_SAMPLE_RATE`	`0.0`	Fraction of requests to record as performance traces (0.0 = disabled, 1.0 = all requests).

Note

No personally identifiable information is sent to the error tracker. User IPs, email addresses, and session cookies are excluded (send_default_pii=False).

Tip

For production deployments, use the SENTRY_DSN_FILE Docker secret variant instead of setting the DSN directly in the environment file. See Docker Secrets for details.

Application Server Settings¶

Variable	Default	Description
`GUNICORN_WORKERS`	`3`	Number of Gunicorn worker processes. Rule of thumb: 2–4 × number of CPU cores.

Documentation Settings¶

Variable	Default	Description
`DOCS_URL`	(none)	If set, a "Docs" link appears in the navigation bar

Docker Compose Settings¶

Variable	Default	Description
`APP_PORT`	`8000`	External port for the application
`APP_DOCS_PORT`	`8001`	External port for the documentation server
`TIME_ZONE`	`Europe/Berlin`	Container timezone

Docker Secrets¶

For sensitive values, use Docker secrets instead of environment variables:

Secret File	Environment Variable	Purpose
`secrets/secret_key.txt`	`DJANGO_SECRET_KEY`	Django SECRET_KEY
`secrets/db_password.txt`	`DB_PASSWORD`	Database password
`secrets/email_password.txt`	`EMAIL_PASSWORD`	SMTP password
`secrets/oidc_client_secret.txt`	`OIDC_CLIENT_SECRET`	OIDC client secret
`secrets/sentry_dsn.txt`	`SENTRY_DSN`	Sentry/GlitchTip DSN

See Docker Secrets for details.

Installation - Installation guide
Docker Secrets - Secure configuration
Troubleshooting - Common issues