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
FLASK_SECRET_KEY	Flask session encryption key	openssl rand -hex 32
JWT_SECRET_KEY	JWT signing key for API tokens	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

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:

1. ALLOWED_ORIGINS - Explicit comma-separated list (recommended for multiple frontends)
2. APP_URL - Single origin (typical for production)
3. 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)

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

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