Complete reference for all environment variables and configuration options in Burning Ash Protocol.

Configuration Reference

This page documents all environment variables and configuration options for BAP.

Environment Variables

Required Variables

Variable	Description	Example
`JWT_SECRET`	Secret key for signing JWT tokens (minimum 32 characters)	`your-secure-random-string-at-least-32-chars`
`MASTER_KEY`	Master encryption key (32 bytes, hexadecimal)	`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

Server Configuration

Variable	Default	Description
`API_PORT`	8080	API server port
`DB_TYPE`	sqlite	Database type: `sqlite` or `postgres`
`DATABASE_PATH`	./data/bap.db	SQLite database file path
`DATABASE_URL`	-	PostgreSQL connection string (required if DB_TYPE=postgres)
`MIGRATIONS_PATH`	file://migrations	Path to database migrations

Security & CORS

Variable	Default	Description
`CORS_ORIGINS`	http://localhost:3000	Allowed CORS origins (comma-separated)
`FRONTEND_URL`	http://localhost:3000	Frontend URL for redirects
`API_BASE_URL`	http://localhost:8080	Base URL for API (used in emails)

App branding (notification emails)

Optional branding used in HTML notification emails (verification codes, liveness checks, transfer notifications, etc.):

Variable	Default	Description
`APP_NAME`	Burning Ash Protocol	Name shown in email headers and footers
`APP_ICON_URL`	-	Optional URL to an icon or logo image (e.g. your logo) shown in the email header. Leave unset to omit the icon.

OAuth Configuration

Variable	Description	Example
`GOOGLE_OAUTH_CLIENT_ID`	Google OAuth application client ID	`xxxx.apps.googleusercontent.com`
`GOOGLE_OAUTH_CLIENT_SECRET`	Google OAuth application client secret	`your-client-secret`
`GOOGLE_OAUTH_REDIRECT_URL`	Google OAuth callback URL	`https://yourdomain.com/api/storages/oauth/callback`
`DROPBOX_APP_KEY`	Dropbox application key	`your-app-key`
`DROPBOX_APP_SECRET`	Dropbox application secret	`your-app-secret`
`DROPBOX_OAUTH_REDIRECT_URL`	Dropbox OAuth callback URL	`https://yourdomain.com/api/storages/oauth/callback`

Web Configuration

Variable	Default	Description
`NEXT_PUBLIC_API_URL`	http://localhost:8080/api	Public API URL for frontend

Stripe Billing Configuration

These variables enable Stripe subscriptions (Pro plan) and must be set per environment (development, staging, production).

Variable	Description	Example
`STRIPE_ENABLED`	Enable Stripe billing integration (`true` / `false`). When `false`, plan upgrades must be done manually via admin.	`true`
`STRIPE_SECRET_KEY`	Stripe secret API key for the environment (test or live).	`sk_test_...` / `sk_live_...`
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signing secret for the `/api/webhooks/stripe` endpoint.	`whsec_...`
`STRIPE_PRICE_PRO`	Stripe Price ID for the Pro plan billed monthly.	`price_12345_monthly`
`STRIPE_PRICE_PRO_ANNUAL`	(Optional) Stripe Price ID for the Pro plan billed annually.	`price_67890_annual`

When Stripe is enabled, the API exposes the configured price IDs to the frontend via /api/host/plan, and the dashboard uses them to start Stripe Checkout sessions for monthly or annual subscriptions.

For each environment you should:

Use separate Stripe API keys (test vs live).
Configure a separate webhook endpoint in the Stripe Dashboard pointing to POST {API_BASE_URL}/api/webhooks/stripe.
Use the corresponding signing secret (STRIPE_WEBHOOK_SECRET) and price IDs (STRIPE_PRICE_PRO, STRIPE_PRICE_PRO_ANNUAL) for that environment.

Configuration Files

Docker Compose

For Docker deployments, configure via the .env file:

# Required
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
MASTER_KEY=your-master-encryption-key-exactly-32-bytes

# Optional
API_PORT=8080
WEB_PORT=3000
DB_TYPE=sqlite
DATABASE_PATH=/data/bap.db

# For PostgreSQL
DB_TYPE=postgres
DATABASE_URL=postgresql://bap:password@postgres:5432/bap

# Production
CORS_ORIGINS=https://yourdomain.com
FRONTEND_URL=https://yourdomain.com
NEXT_PUBLIC_API_URL=https://yourdomain.com/api

Database Configuration

SQLite

For development or small deployments:

DB_TYPE=sqlite
DATABASE_PATH=/data/bap.db

The database file is created automatically. Ensure the directory is writable.

PostgreSQL

For production deployments:

DB_TYPE=postgres
DATABASE_URL=postgresql://username:password@host:5432/database

Connection string format:

postgresql://[user[:password]@][netloc][:port][/dbname][?params...]

Example:

postgresql://bap:[email protected]:5432/bap?sslmode=require

Connection Pooling

For high-traffic deployments, configure PostgreSQL connection pool:

# Add to DATABASE_URL
DATABASE_URL=postgresql://bap:password@localhost:5432/bap?pool_max_conns=25&pool_min_conns=5

Security Configuration

JWT Token Lifetimes

Configure token expiry durations (Go duration format: 1h, 30m, 168h, etc.):

Variable	Default	Description
`JWT_ACCESS_TOKEN_EXPIRY`	`1h`	Access token lifetime
`JWT_REFRESH_TOKEN_EXPIRY`	`168h`	Refresh token lifetime (default 7 days)

Rate Limiting

Rate limiting is enabled by default. Configure thresholds (requests per minute):

Variable	Default	Description
`RATE_LIMIT_GENERAL`	`100`	Global rate limit per IP
`RATE_LIMIT_AUTH`	`5`	Auth endpoints (login, register) per IP
`RATE_LIMIT_OTP`	`5`	OTP-related endpoints per IP

Storage Configuration

Local Storage

Default SQLite and file storage:

DATABASE_PATH=/var/lib/bap/bap.db

S3-Compatible Storage

For S3-compatible providers (AWS, MinIO, DigitalOcean Spaces):

# In storage configuration (per storage)
{
  "type": "s3",
  "config": {
    "access_key_id": "AKIA...",
    "secret_access_key": "...",
    "bucket": "my-bap-wills",
    "region": "us-east-1",
    "endpoint": "https://nyc3.digitaloceanspaces.com",  # Optional: for S3-compatible
    "path_style": true  # Optional: for MinIO/DO Spaces
  }
}

Connector Configuration

Email (SMTP)

{
  "type": "email",
  "config": {
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "username": "your-username",
    "password": "your-password",
    "from_address": "[email protected]"
  }
}

Requirements:

Any SMTP provider (SendGrid, Resend, Postmark, Mailgun, etc.)
Verified sender email address (or domain)

SMS (Twilio)

{
  "type": "sms",
  "provider": "twilio",
  "config": {
    "api_key_sid": "SK...",
    "api_key_secret": "...",
    "from_number": "+1234567890"
  }
}

Requirements:

Twilio account
Verified phone number for sending

WhatsApp (Meta Cloud API)

{
  "type": "whatsapp",
  "provider": "whatsapp",
  "config": {
    "access_token": "...",
    "phone_number_id": "...",
    "business_account_id": "..."
  }
}

Requirements:

Meta Business account
WhatsApp Business API enabled
Phone number registered

{
  "type": "telegram",
  "provider": "telegram",
  "config": {
    "bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
  }
}

Requirements:

Telegram Bot created via @BotFather
Bot token obtained

Encryption Configuration

Master Key Generation

Generate a secure master key:

# Generate 32-byte key (64 hex characters)
openssl rand -hex 32

# Or using Python
python3 -c "import secrets; print(secrets.token_hex(32))"

Important:

Store this key securely — it's required to decrypt all will data
If lost, no one can recover the data
Key rotation is documented in Production Checklist

Key Derivation

BAP uses HKDF for deriving keys:

Host-specific keys: HKDF(master_key, host_id)
Survivor share keys: HKDF(survivor_secret, survivor_id)

This provides isolation between hosts even if the master key is compromised.

Logging Configuration

Log Level

# Options: debug, info, warn, error
LOG_LEVEL=info

Log Format

# Options: json, text
LOG_FORMAT=json

For production, use JSON format for log aggregation.

Health Checks

Configure health check endpoints:

HEALTH_CHECK_PATH=/api/health
HEALTH_CHECK_INTERVAL=10s

Backup Configuration

For automated backups, see Production Checklist.

Example: Production Environment

Complete production .env file:

# Required
JWT_SECRET=change-this-to-a-secure-random-string-at-least-32-characters
MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# Server
API_PORT=8080
DB_TYPE=postgres
DATABASE_URL=postgresql://bap:[email protected]:5432/bap?sslmode=require

# Security
CORS_ORIGINS=https://yourdomain.com
FRONTEND_URL=https://yourdomain.com

# OAuth (if using Google Drive or Dropbox)
GOOGLE_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-secret
GOOGLE_OAUTH_REDIRECT_URL=https://yourdomain.com/api/storages/oauth/callback

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

Next Steps

Installation Guide — Initial setup
Docker Compose Deployment — Complete Docker setup
Production Checklist — Security hardening

Configuration Reference

On this page