Skip to main content

​
Environment Variables

Complete reference guide for all environment variables used in the WhatsApp WAHA Dashboard.
Never commit .env files to version control. Use .env.example as a template and keep your actual credentials secure.

​
Quick Start

Copy the example environment file: 
cp .env.example .env
Then fill in your actual values.

​
Required Variables

​
Database Configuration

​
DATABASE_URL
string
required
MongoDB connection string for storing application data.Format: mongodb+srv://username:[email protected]/database-nameExample:
DATABASE_URL="mongodb+srv://admin:[email protected]/whatsapp-manager"
Notes:
  • Use MongoDB Atlas for hosted database
  • Ensure network access is configured (0.0.0.0/0 for Vercel)
  • Database is automatically created if it doesn’t exist
  • Prisma will manage schema migrations

​
WhatsApp API Configuration

​
WAHA_API_URL
string
required
Base URL for your WAHA (WhatsApp HTTP API) server.Example:
WAHA_API_URL="http://localhost:3000"
WAHA_API_URL="http://your-server-ip:3000"
WAHA_API_URL="https://waha.yourdomain.com"
Notes:
  • Must be accessible from both your web app and scheduler
  • Include protocol (http/https) but no trailing slash
  • Default WAHA port is 3000
​
WAHA_API_KEY
string
required
API key for authenticating with your WAHA server.Example:
WAHA_API_KEY="your-secure-waha-api-key"
Notes:
  • Set this in your WAHA server configuration
  • Use a strong, unique key
  • Same key must be used across all services

​
Authentication Configuration

​
BETTER_AUTH_SECRET
string
required
Secret key used by Better Auth for session encryption and security.Example:
BETTER_AUTH_SECRET="your-super-secret-key-min-32-characters-long"
Requirements:
  • Minimum 32 characters
  • Use random, cryptographically secure string
  • Different for development and production
Generate a secure secret:
# Using OpenSSL
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
​
BETTER_AUTH_URL
string
required
Base URL of your application for authentication callbacks.Development:
BETTER_AUTH_URL="http://localhost:3000"
Production:
BETTER_AUTH_URL="https://your-app.vercel.app"
BETTER_AUTH_URL="https://yourdomain.com"
Notes:
  • Must match your actual domain
  • Include protocol (http/https)
  • No trailing slash
  • Update after deploying to production

​
Email Configuration (Mailgun)

​
MAILGUN_API_KEY
string
required
API key from your Mailgun account for sending emails.Example:
MAILGUN_API_KEY="key-1234567890abcdef1234567890abcdef"
Where to find:
  1. Log in to Mailgun
  2. Go to Settings → API Keys
  3. Copy your Private API key
​
MAILGUN_DOMAIN
string
required
Your verified Mailgun domain for sending emails.Example:
MAILGUN_DOMAIN="mg.yourdomain.com"
MAILGUN_DOMAIN="sandboxXXXX.mailgun.org"  # For testing
Setup:
  1. Add and verify your domain in Mailgun
  2. Configure DNS records (MX, TXT, CNAME)
  3. Wait for verification (usually 24-48 hours)
​
FROM_EMAIL
string
required
Email address to use as sender for system emails.Example:
FROM_EMAIL="[email protected]"
FROM_EMAIL="[email protected]"
Requirements:
  • Domain must match MAILGUN_DOMAIN
  • Use a professional, recognizable address
  • Avoid generic terms like “test” or “admin”

​
Admin Configuration

​
ADMIN_EMAIL
string
required
Email address for receiving admin notifications.Example:
ADMIN_EMAIL="[email protected]"
Used for:
  • New user registration notifications
  • System alerts and errors
  • Password reset notifications
  • Fallback when WhatsApp notifications fail
​
ADMIN_PHONE_NUMBER
string
WhatsApp phone number for receiving admin notifications.Example:
ADMIN_PHONE_NUMBER="+1234567890"
ADMIN_PHONE_NUMBER="+919876543210"
Format:
  • Include country code with + prefix
  • No spaces or special characters
  • Must be registered WhatsApp number
Used for:
  • Real-time new user registration alerts
  • Critical system notifications
  • If not set, only email notifications are sent

​
Optional Variables

​
UI Configuration

​
NEXT_PUBLIC_SHOW_FOOTER
string
default:"true"
Control visibility of the application footer.Example:
NEXT_PUBLIC_SHOW_FOOTER="false"  # Hide footer
NEXT_PUBLIC_SHOW_FOOTER="true"   # Show footer (default)
Notes:
  • Must start with NEXT_PUBLIC_ to be available in browser
  • Defaults to showing footer if not set
  • Any value other than “false” shows the footer

​
Environment File Examples

​
Development (.env)

# Database
DATABASE_URL="mongodb+srv://dev:[email protected]/whatsapp-dev"

# WhatsApp API (local WAHA instance)
WAHA_API_URL="http://localhost:3000"
WAHA_API_KEY="dev-api-key-123"

# Better Auth
BETTER_AUTH_SECRET="dev-secret-min-32-chars-change-in-prod"
BETTER_AUTH_URL="http://localhost:3000"

# Mailgun (use sandbox for testing)
MAILGUN_API_KEY="key-1234567890abcdef"
MAILGUN_DOMAIN="sandbox12345.mailgun.org"
FROM_EMAIL="[email protected]"

# Admin Configuration
ADMIN_EMAIL="[email protected]"
ADMIN_PHONE_NUMBER="+1234567890"

# UI Configuration
NEXT_PUBLIC_SHOW_FOOTER="true"

​
Production (Vercel)

# Database (MongoDB Atlas)
DATABASE_URL="mongodb+srv://prod:[email protected]/whatsapp-prod"

# WhatsApp API (production WAHA server)
WAHA_API_URL="https://waha.yourdomain.com"
WAHA_API_KEY="prod-secure-api-key-xyz789"

# Better Auth (CRITICAL: Use strong secret)
BETTER_AUTH_SECRET="production-secret-generated-with-openssl-rand-base64-32"
BETTER_AUTH_URL="https://your-app.vercel.app"

# Mailgun (verified domain)
MAILGUN_API_KEY="key-prod1234567890abcdef"
MAILGUN_DOMAIN="mg.yourdomain.com"
FROM_EMAIL="[email protected]"

# Admin Configuration
ADMIN_EMAIL="[email protected]"
ADMIN_PHONE_NUMBER="+1234567890"

# UI Configuration
NEXT_PUBLIC_SHOW_FOOTER="true"

​
Scheduler (.env.production on VPS)

# Only scheduler needs these three variables
DATABASE_URL="mongodb+srv://prod:[email protected]/whatsapp-prod"
WAHA_API_KEY="prod-secure-api-key-xyz789"
WAHA_API_URL="https://waha.yourdomain.com"

# Note: Scheduler doesn't need auth or email variables

​
Environment Variables by Service

​
Web Application (Vercel)

Required for the Next.js web app:
VariablePurpose
DATABASE_URLDatabase connection
WAHA_API_URLWhatsApp API access
WAHA_API_KEYWhatsApp API authentication
BETTER_AUTH_SECRETSession encryption
BETTER_AUTH_URLAuth callbacks
MAILGUN_API_KEYEmail sending
MAILGUN_DOMAINEmail domain
FROM_EMAILSender address
ADMIN_EMAILAdmin notifications
ADMIN_PHONE_NUMBERWhatsApp notifications (optional)
NEXT_PUBLIC_SHOW_FOOTERUI configuration (optional)

​
Message Scheduler (VPS)

Required for the background scheduler:
VariablePurpose
DATABASE_URLDatabase connection
WAHA_API_URLWhatsApp API access
WAHA_API_KEYWhatsApp API authentication
The scheduler only needs database and WAHA access. It doesn’t need auth or email configuration.

​
Security Best Practices

​
Secret Generation

# Generate secure random secret
openssl rand -base64 32

​
Environment File Security

  1. Never commit secrets 
    # Add to .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo ".env.production" >> .gitignore
  2. Use different secrets per environment
    • Development and production must have different secrets
    • Never reuse API keys across environments
  3. Restrict file permissions 
    # On VPS, restrict .env file access
chmod 600 .env.production
  4. Rotate secrets regularly
    • Update BETTER_AUTH_SECRET quarterly
    • Rotate API keys if compromised
    • Update admin credentials periodically

​
MongoDB Security

  1. Network Access
    • For Vercel: Allow 0.0.0.0/0 (Vercel uses dynamic IPs)
    • For VPS: Whitelist specific VPS IP address
  2. Strong Passwords
    • Use generated passwords (20+ characters)
    • Include uppercase, lowercase, numbers, special chars
    • Never use common passwords
  3. Database User Permissions
    • Create separate users for dev/prod
    • Grant minimum required permissions
    • Use read-only users for analytics

​
Troubleshooting

​
Common Issues

“BETTER_AUTH_SECRET must be set” 
# Ensure variable is set and at least 32 characters
echo $BETTER_AUTH_SECRET | wc -c
# Should output 33 or more (includes newline)
“Failed to connect to MongoDB” 
# Check connection string format
# Ensure username/password are URL-encoded
# Verify network access in MongoDB Atlas
“Mailgun authentication failed” 
# Verify API key is correct (starts with 'key-')
# Check domain is verified in Mailgun
# Ensure FROM_EMAIL domain matches MAILGUN_DOMAIN
“WAHA API connection refused” 
# Verify WAHA server is running
curl http://your-waha-server:3000/api/server/status

# Check WAHA_API_URL format (no trailing slash)
# Verify WAHA_API_KEY matches server configuration

​
Validation

Validate your environment configuration: 
# On Unix/Linux/Mac
for var in DATABASE_URL WAHA_API_URL WAHA_API_KEY BETTER_AUTH_SECRET BETTER_AUTH_URL MAILGUN_API_KEY MAILGUN_DOMAIN FROM_EMAIL ADMIN_EMAIL; do
  if [ -z "${!var}" ]; then
    echo "❌ $var is not set"
  else
    echo "✅ $var is set"
  fi
done

​
Next Steps

Deploy to Vercel

Deploy the web application

Scheduler Setup

Set up the background scheduler

Build docs developers (and LLMs) love

Get started for freeTalk to us