Configuration

Complete reference for all environment variables and configuration options.

Required Variables

These must be set for the application to function:

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/dbname`
`JWT_SECRET_KEY`	JWT signing key for authentication	`openssl rand -hex 32`
`FLASK_SECRET_KEY`	Session encryption key (fallback for JWT if not set)	`openssl rand -hex 32`

Production Requirement

In production, at least one of JWT_SECRET_KEY or FLASK_SECRET_KEY must be explicitly set. The application will fail to start otherwise to prevent insecure deployments.

Deployment Options

Variable	Description	Default
`DEPLOYMENT_MODE`	`self-hosted` or `saas`	`self-hosted`
`ENABLE_REGISTRATION`	Allow public user registration	`false`
`REQUIRE_EMAIL_VERIFICATION`	Require email verification for new users	`false`

Language, Currency, and Mobile Compatibility

Variable	Description	Default
`DEFAULT_LOCALE`	BCP 47 locale used for deployment-level number and date formatting	`en-US`
`MINIMUM_MOBILE_VERSION`	Optional minimum compatible mobile client version advertised by the server	Unset
`OAUTH_REDIRECT_URIS`	Additional comma-separated OAuth callback URIs, such as development-client or universal links	Unset

Currency is now a per-user setting selected in the web or mobile Settings screen. New users begin with USD and may choose from USD, EUR, JPY, GBP, CNY, CHF, AUD, CAD, HKD, SGD, INR, KRW, SEK, NZD, and MXN.

DEFAULT_CURRENCY is no longer a runtime setting. During the upgrade that introduced personal currencies, existing users inherited its former value once; changing or retaining that environment variable afterward has no effect. Currency selection changes formatting and validation, not the numeric value of stored amounts.

Enable social sign-in providers and generic OIDC SSO.

Variable	Description	Default
`OAUTH_AUTO_REGISTER`	Auto-create users on first social login	`true` (self-hosted)
`OAUTH_GOOGLE_ENABLED`	Enable Google login	`false`
`OAUTH_APPLE_ENABLED`	Enable Apple login	`false`
`OAUTH_MICROSOFT_ENABLED`	Enable Microsoft login	`false`
`OAUTH_OIDC_ENABLED`	Enable generic OIDC login	`false`

Provider-specific credentials and advanced OIDC claim mapping are documented in Social Login (OIDC).

Email Configuration

Required for user invitations, password resets, email verification, and email OTP.

Variable	Description	Default
`EMAIL_PROVIDER`	Outbound provider: `smtp`, `resend`, or `none`	Auto-detects Resend/SMTP config
`SMTP_HOST`	SMTP server hostname	None
`SMTP_PORT`	SMTP server port	`587` or `465` when SSL is enabled
`SMTP_USERNAME`	SMTP username, optional for relays	None
`SMTP_PASSWORD`	SMTP password, optional for relays	None
`SMTP_USE_TLS`	Use STARTTLS	`true` unless SSL is enabled
`SMTP_USE_SSL`	Use implicit SSL/TLS	`false`
`SMTP_TIMEOUT`	SMTP connection timeout in seconds	`10`
`RESEND_API_KEY`	Resend API key for Resend provider	None
`FROM_EMAIL`	Sender email address	`[email protected]`
`APP_URL`	Application URL for email links	`http://localhost:5000`

Email Required for Invitations

Without email configured, invitation emails, password reset emails, and email OTP codes cannot be sent. See Email Setup for SMTP and Resend examples.

CORS Configuration

Control which domains can access your BillManager API.

Variable	Description	Default
`ALLOWED_ORIGINS`	Comma-separated list of allowed origins	Uses `APP_URL` or localhost

Priority Order

The application determines allowed CORS origins using this priority:

ALLOWED_ORIGINS - Explicit comma-separated list (recommended for multiple frontends)
APP_URL - Single origin (typical for production)
Localhost defaults - Development only (http://localhost:5173, http://localhost:5001, http://127.0.0.1:5173, http://127.0.0.1:5001)

Examples

Single production domain:

environment:
  - APP_URL=https://bills.yourdomain.com

Multiple domains (e.g., mobile app + web):

environment:
  - ALLOWED_ORIGINS=https://bills.yourdomain.com,https://app.yourdomain.com,https://mobile.yourdomain.com

Development (automatically uses localhost):

environment:
  # No CORS configuration needed - automatically allows localhost
  - DATABASE_URL=postgresql://...
  - FLASK_SECRET_KEY=dev-key

When to Use ALLOWED_ORIGINS vs APP_URL

Use ALLOWED_ORIGINS when you have multiple frontends (web app, mobile app, admin panel, etc.)
Use APP_URL for simple single-domain deployments
Don't set either for local development (localhost is allowed by default)

BillManager supports social login (Google, Apple, Microsoft, and generic OIDC providers) and two-factor authentication (email OTP, passkeys, recovery codes). All providers and 2FA are disabled by default.

For full setup instructions, see Social Login Setup.

Quick reference:

Variable	Description	Default
`OAUTH_GOOGLE_ENABLED`	Enable Google login	`false`
`OAUTH_APPLE_ENABLED`	Enable Apple login	`false`
`OAUTH_MICROSOFT_ENABLED`	Enable Microsoft login	`false`
`OAUTH_OIDC_ENABLED`	Enable generic OIDC login	`false`
`OAUTH_OIDC_TOKEN_AUTH_METHOD`	Generic OIDC token endpoint auth method	`client_secret_post`
`OAUTH_AUTO_REGISTER`	Auto-create accounts for new social login users	`true` (self-hosted)
`ENABLE_2FA`	Allow users to enable two-factor authentication	`false`
`ENABLE_PASSKEYS`	Allow passkey/WebAuthn as a 2FA method	`false`
`WEBAUTHN_RP_ID`	WebAuthn relying-party domain	Derived from `APP_URL`
`WEBAUTHN_RP_NAME`	Name shown by passkey prompts	`BillManager`
`WEBAUTHN_ORIGIN`	Exact web origin accepted for passkeys	`APP_URL`
`WEBAUTHN_ANDROID_ORIGINS`	Comma-separated `android:apk-key-hash:` origins for trusted Android signing certificates	Unset

Built-in Security Features

BillManager includes comprehensive security protections enabled by default:

Feature	Description
JWT Authentication	Secure token-based authentication with access + refresh tokens
Rate Limiting	Tiered rate limits: 60/min for reads, 30/min for writes
Content Security Policy	Strict CSP headers prevent XSS and injection attacks
CORS Protection	Configurable allowed origins for API security
Input Validation	Server-side validation for all user inputs
Password Enforcement	Strong password requirements (8+ chars, mixed case, digit)
Two-Factor Authentication	Optional email OTP, passkeys, and recovery codes
Social Login	Sign in with Google, Apple, Microsoft, or generic OIDC
Row-Level Isolation	Complete data separation between user groups

No Configuration Needed

These security features are enabled automatically. No additional configuration is required.

Security Best Practices

1. Generate Strong Secrets

Always use cryptographically secure random values:

openssl rand -hex 32

2. Use Environment Files

Keep secrets out of docker-compose.yml:

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:latest
    env_file:
      - .env

Create a .env file (never commit this to version control):

DATABASE_URL=postgresql://billsuser:securepassword@db:5432/billmanager
FLASK_SECRET_KEY=abc123...
JWT_SECRET_KEY=def456...
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_USERNAME=billmanager
SMTP_PASSWORD=...

3. Use Docker Secrets (Production)

For production deployments, consider using Docker secrets:

services:
  billmanager:
    secrets:
      - flask_secret
      - jwt_secret
    environment:
      - FLASK_SECRET_KEY_FILE=/run/secrets/flask_secret
      - JWT_SECRET_KEY_FILE=/run/secrets/jwt_secret

secrets:
  flask_secret:
    file: ./secrets/flask_secret.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt

Example Configurations

Minimal (Development)

environment:
  - DEPLOYMENT_MODE=self-hosted
  - DATABASE_URL=postgresql://billsuser:password@db:5432/billmanager
  - FLASK_SECRET_KEY=development-only-key

Production with SMTP Email

environment:
  - DEPLOYMENT_MODE=self-hosted
  - DATABASE_URL=postgresql://billsuser:${DB_PASSWORD}@db:5432/billmanager
  - FLASK_SECRET_KEY=${FLASK_SECRET}
  - JWT_SECRET_KEY=${JWT_SECRET}
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=smtp.example.com
  - SMTP_PORT=587
  - SMTP_USERNAME=${SMTP_USERNAME}
  - SMTP_PASSWORD=${SMTP_PASSWORD}
  - SMTP_USE_TLS=true
  - SMTP_USE_SSL=false
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

environment:
  - DEPLOYMENT_MODE=self-hosted
  - DATABASE_URL=postgresql://billsuser:${DB_PASSWORD}@db:5432/billmanager
  - FLASK_SECRET_KEY=${FLASK_SECRET}
  - JWT_SECRET_KEY=${JWT_SECRET}
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=smtp.example.com
  - SMTP_PORT=587
  - SMTP_USERNAME=${SMTP_USERNAME}
  - SMTP_PASSWORD=${SMTP_PASSWORD}
  - SMTP_USE_TLS=true
  - [email protected]
  - APP_URL=https://bills.yourdomain.com
  - OAUTH_GOOGLE_ENABLED=true
  - OAUTH_GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
  - OAUTH_GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
  - ENABLE_2FA=true

See Social Login Setup for detailed provider configuration and passkey setup.

With Public Registration

environment:
  - DEPLOYMENT_MODE=self-hosted
  - ENABLE_REGISTRATION=true
  - REQUIRE_EMAIL_VERIFICATION=true
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=smtp.example.com
  - SMTP_PORT=587
  - SMTP_USERNAME=${SMTP_USERNAME}
  - SMTP_PASSWORD=${SMTP_PASSWORD}
  - SMTP_USE_TLS=true
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

Required Variables​

Deployment Options​

Language, Currency, and Mobile Compatibility​

Social Login (OAuth/OIDC)​

Email Configuration​

CORS Configuration​

Priority Order​

Examples​

Social Login & Two-Factor Authentication​

Built-in Security Features​

Security Best Practices​

1. Generate Strong Secrets​

2. Use Environment Files​

3. Use Docker Secrets (Production)​

Example Configurations​

Minimal (Development)​

Production with SMTP Email​

With Google Login and 2FA​

With Public Registration​