Environment Variables

Complete reference of all environment variables required for WhatsApp WAHA Dashboard

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:[e-mail]/database-name

Example:

DATABASE_URL="mongodb+srv://admin:[e-mail]/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="[e-mail]"
FROM_EMAIL="[e-mail]"

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="[e-mail]"

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="[phone]"
ADMIN_PHONE_NUMBER="[phone]"

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)

.env (Development)

# Database
DATABASE_URL="mongodb+srv://dev:[e-mail]/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="[e-mail]"

# Admin Configuration
ADMIN_EMAIL="[e-mail]"
ADMIN_PHONE_NUMBER="[phone]"

# UI Configuration
NEXT_PUBLIC_SHOW_FOOTER="true"

Production (Vercel)

Vercel Environment Variables

# Database (MongoDB Atlas)
DATABASE_URL="mongodb+srv://prod:[e-mail]/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="[e-mail]"

# Admin Configuration
ADMIN_EMAIL="[e-mail]"
ADMIN_PHONE_NUMBER="[phone]"

# UI Configuration
NEXT_PUBLIC_SHOW_FOOTER="true"

Scheduler (.env.production on VPS)

.env.production (VPS Scheduler)

# Only scheduler needs these three variables
DATABASE_URL="mongodb+srv://prod:[e-mail]/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:

Variable	Purpose
DATABASE_URL	Database connection
WAHA_API_URL	WhatsApp API access
WAHA_API_KEY	WhatsApp API authentication
BETTER_AUTH_SECRET	Session encryption
BETTER_AUTH_URL	Auth callbacks
MAILGUN_API_KEY	Email sending
MAILGUN_DOMAIN	Email domain
FROM_EMAIL	Sender address
ADMIN_EMAIL	Admin notifications
ADMIN_PHONE_NUMBER	WhatsApp notifications (optional)
NEXT_PUBLIC_SHOW_FOOTER	UI configuration (optional)

Message Scheduler (VPS)

Required for the background scheduler:

Variable	Purpose
DATABASE_URL	Database connection
WAHA_API_URL	WhatsApp API access
WAHA_API_KEY	WhatsApp API authentication

The scheduler only needs database and WAHA access. It doesn’t need auth or email configuration.

Security Best Practices

Secret Generation

OpenSSL

# 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:

Check Required Variables

# 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