Skip to main content

​
Environment Variables

Budget Bee uses environment variables for configuration. This guide covers all available variables and their purposes.

​
Getting Started

Copy the example environment file: 
cp .env.example .env
Then edit .env with your configuration.
Never commit .env to version control. It contains sensitive secrets and credentials.

​
Application URLs

Core application URL configuration:
​
NEXT_PUBLIC_SITE_URL
string
default:"http://localhost:3001"
required
URL for the marketing/landing siteExample values:
  • Development: http://localhost:3001
  • Production: https://budget-bee.site
​
NEXT_PUBLIC_APP_URL
string
default:"http://localhost:3000"
required
URL for the main applicationExample values:
  • Development: http://localhost:3000
  • Production: https://app.budget-bee.site
This is used for authentication callbacks and email links.
​
NEXT_PUBLIC_CURRENCY_API_URL
string
default:"http://localhost:8787"
URL for the currency conversion API serviceExample values:
  • Development: http://localhost:8787
  • Production: https://currency-api.budget-bee.site
​
NEXT_PUBLIC_PG_REST_URL
string
default:"http://localhost:5101"
required
URL for the PostgREST API endpointExample values:
  • Development: http://localhost:5101
  • Production: https://api.budget-bee.site
​
NEXT_PUBLIC_CLOUDINARY_URL
string
Cloudinary URL for image uploads (optional)Format: cloudinary://api_key:api_secret@cloud_name

​
Authentication

Better Auth configuration for authentication:
​
BETTER_AUTH_SECRET
string
required
Secret key for Better Auth encryption and signingGeneration:
openssl rand -base64 32
Must be kept secret. Changing this will invalidate all existing sessions.

​
OAuth Providers

​
GOOGLE_CLIENT_ID
string
Google OAuth client ID for Google Sign-InHow to get:
  1. Go to Google Cloud Console
  2. Create or select a project
  3. Enable Google+ API
  4. Create OAuth 2.0 credentials
  5. Add authorized redirect URIs:
    • http://localhost:3000/api/auth/callback/google (development)
    • https://your-domain.com/api/auth/callback/google (production)
​
GOOGLE_CLIENT_SECRET
string
Google OAuth client secret (paired with client ID)
​
GOOGLE_ANALYTICS_ID
string
Google Analytics measurement ID for tracking (optional)Format: G-XXXXXXXXXX

​
Email Configuration

Resend email service configuration:
​
RESEND_API_KEY
string
required
Resend API key for sending emailsHow to get:
  1. Sign up at resend.com
  2. Create an API key in the dashboard
  3. Copy the key (starts with re_)
Resend is used for verification emails, password resets, and invitations.
​
SMTP_SENDER_NAME
string
default:"Budget Bee"
required
Display name for email senderThis appears as the “From” name in emails.
​
SMTP_MAIL
string
required
Email address for sending emailsRequirements:
  • Must be verified in Resend
  • Should be a no-reply or support email
Example: [email protected]

​
Database Configuration

PostgreSQL database connection settings:
​
POSTGRES_DATABASE
string
default:"budgetbee"
required
Name of the PostgreSQL database
​
POSTGRES_USER
string
default:"root"
required
Main PostgreSQL user for application connections
Use a dedicated user rather than the postgres superuser.
​
POSTGRES_HOST
string
default:"localhost"
required
PostgreSQL server hostname or IP addressExample values:
  • Development: localhost
  • Docker: postgres (service name)
  • Production: your-db-host.com
​
POSTGRES_PORT
number
default:5100
required
PostgreSQL server portDefault PostgreSQL port is 5432, but can be customized.
​
POSTGRES_PASSWORD
string
required
Password for the main PostgreSQL user
Use a strong, unique password. Never use default passwords in production.

​
Special Database Users

Budget Bee uses separate database users for different operations:
​
POSTGRES_AUTH_ADMIN_USER
string
default:"auth_admin"
required
Database user for Better Auth operationsThis user has permissions to manage:
  • users table
  • sessions table
  • accounts table
  • verifications table
  • organizations, members, invitations
​
POSTGRES_AUTH_ADMIN_PASSWORD
string
required
Password for the auth_admin user
​
POSTGRES_SUBSCRIPTION_ADMIN_USER
string
default:"subscription_admin"
required
Database user for subscription managementThis user has permissions to:
  • Read users table
  • Manage app_subscriptions table
​
POSTGRES_SUBSCRIPTION_ADMIN_PASSWORD
string
required
Password for the subscription_admin user

​
PostgREST Configuration

​
PGRST_JWT_SECRET
string
required
JWT secret for PostgREST API authenticationGeneration:
openssl rand -base64 32
This should be different from BETTER_AUTH_SECRET.

​
Billing & Subscriptions

Polar integration for subscription billing:
​
POLAR_ACCESS_TOKEN
string
Polar API access token for subscription managementHow to get:
  1. Sign up at polar.sh
  2. Create an organization
  3. Generate an API token in settings
​
POLAR_WEBHOOK_SECRET
string
Secret for verifying Polar webhook signaturesFound in Polar dashboard under Webhooks settings.

​
Polar Product IDs

​
POLAR_PRODUCT_PRO
string
Product ID for Pro monthly subscriptionCreate products in Polar dashboard and copy their IDs.
​
POLAR_PRODUCT_PRO_YEARLY
string
Product ID for Pro yearly subscription
​
POLAR_PRODUCT_TEAMS
string
Product ID for Teams monthly subscription
​
POLAR_PRODUCT_TEAMS_YEARLY
string
Product ID for Teams yearly subscription

​
Development & Testing

​
DEV_ONLY_TEST_USER_ID
string
User ID for testing in development
Only use in development environments. Never set in production.

​
Complete Example

# Application URLs
NEXT_PUBLIC_SITE_URL=https://budget-bee.site
NEXT_PUBLIC_APP_URL=https://app.budget-bee.site
NEXT_PUBLIC_CURRENCY_API_URL=https://currency-api.budget-bee.site
NEXT_PUBLIC_PG_REST_URL=https://api.budget-bee.site
NEXT_PUBLIC_CLOUDINARY_URL=cloudinary://key:secret@cloud_name

# Better Auth
BETTER_AUTH_SECRET=your-generated-secret-key-here

# Email (Resend)
RESEND_API_KEY=re_123456789abcdefghijklmnop
SMTP_SENDER_NAME=Budget Bee
SMTP_MAIL=[email protected]

# Database
POSTGRES_DATABASE=budgetbee
POSTGRES_USER=budgetbee_user
POSTGRES_HOST=db.example.com
POSTGRES_PORT=5432
POSTGRES_PASSWORD=strong-database-password

POSTGRES_AUTH_ADMIN_USER=auth_admin
POSTGRES_AUTH_ADMIN_PASSWORD=auth-admin-password
POSTGRES_SUBSCRIPTION_ADMIN_USER=subscription_admin
POSTGRES_SUBSCRIPTION_ADMIN_PASSWORD=subscription-admin-password

PGRST_JWT_SECRET=another-generated-secret-key

# Polar Billing
POLAR_ACCESS_TOKEN=polar_secret_key_abc123
POLAR_WEBHOOK_SECRET=whsec_abc123xyz789
POLAR_PRODUCT_PRO=prod_abc123
POLAR_PRODUCT_PRO_YEARLY=prod_def456
POLAR_PRODUCT_TEAMS=prod_ghi789
POLAR_PRODUCT_TEAMS_YEARLY=prod_jkl012

# Google OAuth
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123xyz789
GOOGLE_ANALYTICS_ID=G-ABCDEFGHIJ

​
Environment-Specific Configuration

​
Development

# Use localhost for all services
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SITE_URL=http://localhost:3001
NEXT_PUBLIC_PG_REST_URL=http://localhost:5101
NEXT_PUBLIC_CURRENCY_API_URL=http://localhost:8787

# Local database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

​
Production

# Use production domains
NEXT_PUBLIC_APP_URL=https://app.budget-bee.site
NEXT_PUBLIC_SITE_URL=https://budget-bee.site
NEXT_PUBLIC_PG_REST_URL=https://api.budget-bee.site
NEXT_PUBLIC_CURRENCY_API_URL=https://currency-api.budget-bee.site

# Production database with SSL
POSTGRES_HOST=prod-db.example.com
POSTGRES_PORT=5432

​
Docker Compose

# Use service names for inter-container communication
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# External URLs for browser access
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_PG_REST_URL=http://localhost:5101

​
Security Best Practices

Use Strong Secrets

Generate secrets with openssl rand -base64 32 or similar tools.

Different Per Environment

Use different secrets for development, staging, and production.

Never Commit

Add .env to .gitignore. Never commit secrets to version control.

Rotate Regularly

Rotate secrets periodically, especially after team member changes.

​
Validation

Budget Bee validates environment variables on startup. Missing required variables will cause startup failures: 
// Example validation
if (!process.env.BETTER_AUTH_SECRET) {
  throw new Error('BETTER_AUTH_SECRET is required');
}

if (!process.env.NEXT_PUBLIC_APP_URL) {
  throw new Error('NEXT_PUBLIC_APP_URL is required');
}

​
Troubleshooting

Check:
  • All required environment variables are set
  • No typos in variable names
  • Values are properly quoted if they contain special characters
  • .env file is in the correct directory
Verify:
  • BETTER_AUTH_SECRET is set and not empty
  • NEXT_PUBLIC_APP_URL is correct and accessible
  • OAuth client IDs and secrets are correct
  • Callback URLs are properly configured in OAuth provider
Ensure:
  • Database server is running
  • POSTGRES_HOST and POSTGRES_PORT are correct
  • POSTGRES_USER has proper permissions
  • POSTGRES_PASSWORD is correct
  • Database POSTGRES_DATABASE exists
Check:
  • RESEND_API_KEY is valid and not expired
  • SMTP_MAIL is verified in Resend dashboard
  • API key has send permissions
  • Check Resend dashboard for delivery logs

​
Next Steps

Database Setup

Configure PostgreSQL with users and roles.

Authentication Setup

Configure Better Auth and OAuth providers.

Build docs developers (and LLMs) love

Get started for freeTalk to us