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`

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 and password reset functionality.

Variable	Description	Default
`RESEND_API_KEY`	Resend API key	None
`FROM_EMAIL`	Sender email address	None
`APP_URL`	Application URL for email links	`http://localhost:5000`

Email Required for Invitations

Without email configured, the "Invite User" button will not appear in the Admin Panel. See Email Setup for configuration details.

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 and Apple) 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_AUTO_REGISTER`	Auto-create accounts for new social login users	`false`
`ENABLE_2FA`	Allow users to enable two-factor authentication	`false`
`ENABLE_PASSKEYS`	Allow passkey/WebAuthn as a 2FA method	`false`

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 or Apple
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...
RESEND_API_KEY=re_...

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 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}
  - RESEND_API_KEY=${RESEND_KEY}
  - [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}
  - RESEND_API_KEY=${RESEND_KEY}
  - [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
  - RESEND_API_KEY=re_your_api_key
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

Required Variables​

Deployment Options​

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 Email​

With Google Login and 2FA​

With Public Registration​