Installation

Complete guide to installing and deploying WhatsApp Group Manager in development and production environments

This comprehensive guide covers everything you need to install, configure, and deploy WhatsApp Group Manager. Follow the sections relevant to your use case.

Prerequisites

Before installing WhatsApp Group Manager, ensure you have the following:

Required Software

Node.js 18+

JavaScript runtime required for Next.js

Download Node.js

pnpm

Fast, disk-efficient package manager

npm install -g pnpm@10.4.0

MongoDB

NoSQL database for data storage

MongoDB Atlas (Cloud) or local installation

WAHA Server

WhatsApp HTTP API for connectivity

WAHA Documentation

Required Services

MongoDB Database

Option 1: MongoDB Atlas (Recommended for beginners)

1. Create a free account at MongoDB Atlas
2. Create a new cluster (free tier available)
3. Add your IP to the whitelist (or allow access from anywhere for development)
4. Create a database user with read/write permissions
5. Get your connection string (looks like mongodb+srv://user:[e-mail]/dbname)

Option 2: Local MongoDB

# macOS (with Homebrew)
brew install mongodb-community
brew services start mongodb-community

# Ubuntu/Debian
sudo apt install mongodb
sudo systemctl start mongodb

# Windows
# Download installer from mongodb.com

WAHA (WhatsApp HTTP API)

WAHA provides the WhatsApp connectivity layer. You have several options:

Option 1: Docker (Recommended)

docker run -d \
  --name waha \
  -p 3000:3000 \
  -e WHATSAPP_API_KEY=your-secret-key \
  devlikeapro/waha

Option 2: Cloud Hosted

Use a cloud-hosted WAHA instance from providers or deploy to your own VPS.

Option 3: NPM

npm install -g @waha/waha
waha start

Make note of your WAHA URL (default: http://localhost:3000) and API key for configuration.

Mailgun Account

Required for password reset and admin notification emails:

1. Sign up at Mailgun
2. Verify your email domain (or use sandbox domain for testing)
3. Get your API key from the dashboard
4. Note your domain name (e.g., mg.yourdomain.com)

Mailgun offers 5,000 free emails per month, perfect for most use cases.

Local Development Setup

1. Clone Repository

   Clone the WhatsApp Group Manager repository from GitHub:

   git clone https://github.com/jevil25/whatsapp-group-manager.git
   cd whatsapp-group-manager
   
2. Install Dependencies

   Install all project dependencies using pnpm:

   pnpm install
   

   This command will:

   • Install all packages from package.json
   • Run the postinstall script to generate Prisma client
   • Set up the development environment
3. Configure Environment Variables

   Create your environment configuration file:

   cp .env.example .env
   

   Edit .env with your actual configuration:

   Complete Configuration

   # Database Configuration
   DATABASE_URL="mongodb+srv://username:[e-mail]/whatsapp-manager"
   
   # WhatsApp API (WAHA) Configuration
   WAHA_API_URL="http://localhost:3000"
   WAHA_API_KEY="your-waha-api-key"
   
   # Better Auth Configuration
   BETTER_AUTH_SECRET="generate-random-secret-here"
   BETTER_AUTH_URL="http://localhost:3001"
   
   # Mailgun Configuration for Email
   MAILGUN_API_KEY="key-xxxxxxxxxxxxxxxxxxxxxxxx"
   MAILGUN_DOMAIN="mg.yourdomain.com"
   FROM_EMAIL="[e-mail]"
   
   # Admin Notification Configuration
   ADMIN_EMAIL="[e-mail]"
   ADMIN_PHONE_NUMBER="[phone]"
   
   # Optional: Footer Configuration
   NEXT_PUBLIC_SHOW_FOOTER="true"
   

   DATABASE_URL="mongodb://localhost:27017/whatsapp-manager"
   WAHA_API_URL="http://localhost:3000"
   WAHA_API_KEY="dev-key-123"
   BETTER_AUTH_SECRET="dev-secret-change-in-production"
   BETTER_AUTH_URL="http://localhost:3001"
   MAILGUN_API_KEY="your-mailgun-key"
   MAILGUN_DOMAIN="sandbox123.mailgun.org"
   FROM_EMAIL="[e-mail]"
   ADMIN_EMAIL="[e-mail]"
   ADMIN_PHONE_NUMBER="[phone]"
   

   Never commit your .env file to version control. It contains sensitive credentials.

4. Generate Secure Secrets

   Generate a cryptographically secure secret for Better Auth:

   # Using OpenSSL (macOS/Linux)
   openssl rand -base64 32
   
   # Using Node.js
   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
   

   Use the output as your BETTER_AUTH_SECRET value.

5. Set Up Database

   Push the Prisma schema to your MongoDB database:

   pnpm db:push
   

   This creates all necessary collections:

   • user - User accounts and authentication
   • session - User sessions
   • account - OAuth accounts and passwords
   • WhatsAppSession - WhatsApp connection sessions
   • WhatsAppGroup - Synced WhatsApp groups
   • MessageCampaign - Message campaigns
   • Message - Individual scheduled messages
   • Verification - Email verification tokens

   Run pnpm db:studio to open Prisma Studio and visually inspect your database.

6. Start Development Server

   Launch the Next.js application:

   pnpm dev
   

   The application will start on http://localhost:3001

7. Start Message Scheduler

   In a separate terminal, start the background scheduler:

   pnpm scheduler:start
   

   The scheduler:

   • Runs independently of the Next.js app
   • Checks for pending messages every 30 seconds
   • Automatically sends messages at scheduled times
   • Logs all activity to the console

   The scheduler must run continuously for automated message delivery. In production, use PM2 or similar process manager.

Production Deployment

Frontend Deployment (Vercel)

Deploy the Next.js application to Vercel for optimal performance:

1. Push to GitHub

   Ensure your code is committed and pushed to GitHub:

   git add .
   git commit -m "Ready for deployment"
   git push origin main
   
2. Import to Vercel

   1. Visit Vercel
   2. Click “Add New Project”
   3. Import your GitHub repository
   4. Configure project settings:
      • Framework Preset: Next.js
      • Build Command: pnpm build (default)
      • Output Directory: .next (default)
3. Configure Environment Variables

   Add these environment variables in Vercel dashboard:

   DATABASE_URL=mongodb+srv://user:[e-mail]/whatsapp-manager
   BETTER_AUTH_SECRET=your-production-secret-key
   BETTER_AUTH_URL=https://your-app.vercel.app
   WAHA_API_URL=http://your-waha-server:3000
   WAHA_API_KEY=your-production-waha-key
   MAILGUN_API_KEY=your-mailgun-key
   MAILGUN_DOMAIN=mg.yourdomain.com
   FROM_EMAIL=[e-mail]
   ADMIN_EMAIL=[e-mail]
   ADMIN_PHONE_NUMBER=[phone]
   

   Use different secrets and API keys for production. Never use development credentials in production.

4. Deploy

   Click “Deploy” and wait for the build to complete. Vercel will:

   • Install dependencies
   • Run Prisma generation
   • Build the Next.js application
   • Deploy to CDN

   Your app will be available at https://your-app.vercel.app

Backend Scheduler (DigitalOcean VPS)

The message scheduler needs to run on a server 24/7. Here’s how to deploy it to a VPS:

1. Create DigitalOcean Droplet

   Create a VPS to run the scheduler:

   1. Get $200 in credits (referral link)
   2. Create a new Droplet:
      • Distribution: Ubuntu 22.04 LTS
      • Plan: Basic ($6/month, 1GB RAM is sufficient)
      • Datacenter: Choose closest to your WAHA server
      • Authentication: SSH keys recommended (or password for beginners)

   A basic 1GB RAM droplet can handle thousands of scheduled messages efficiently.

2. Initial Server Setup

   Connect to your server and set up the environment:

   # Connect via SSH
   ssh root@your-server-ip
   
   # Update system packages
   apt update && apt upgrade -y
   
   # Install Node.js 18+
   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
   apt-get install -y nodejs
   
   # Install pnpm globally
   npm install -g pnpm@10.4.0
   
   # Install PM2 for process management
   npm install -g pm2
   
   # Install Git
   apt install -y git
   
3. Deploy Application

   Clone your repository and set up the scheduler:

   # Clone repository
   cd /opt
   git clone https://github.com/jevil25/whatsapp-group-manager.git
   cd whatsapp-group-manager
   
   # Install dependencies
   pnpm install
   
   # Create production environment file
   nano .env.production
   

   Add your production environment variables:

   DATABASE_URL="mongodb+srv://user:[e-mail]/whatsapp-manager"
   WAHA_API_URL="http://your-waha-server:3000"
   WAHA_API_KEY="your-production-waha-key"
   

   Save and exit (Ctrl+X, then Y, then Enter).

4. Generate Prisma Client

   Generate the Prisma client for production:

   pnpm prisma:generate
   
5. Start with PM2

   Use PM2 to run the scheduler as a persistent background service:

   # Start scheduler with PM2
   pm2 start src/scripts/messageScheduler.ts \
     --interpreter ./node_modules/.bin/tsx \
     --name whatsapp-scheduler \
     --env production
   
   # Save PM2 process list
   pm2 save
   
   # Configure PM2 to start on system boot
   pm2 startup
   

   The scheduler will now:

   • Run automatically on server restart
   • Restart automatically if it crashes
   • Log all activity for monitoring
6. Monitor Scheduler

   Useful PM2 commands for managing the scheduler:

   # Check status
   pm2 status
   
   # View real-time logs
   pm2 logs whatsapp-scheduler
   
   # View last 100 lines
   pm2 logs whatsapp-scheduler --lines 100
   
   # Restart scheduler
   pm2 restart whatsapp-scheduler
   
   # Stop scheduler
   pm2 stop whatsapp-scheduler
   
   # View detailed metrics
   pm2 monit
   

Updating Production Deployment

To update your production scheduler:

# SSH into your server
ssh root@your-server-ip

# Navigate to project directory
cd /opt/whatsapp-group-manager

# Pull latest changes
git pull origin main

# Install any new dependencies
pnpm install

# Regenerate Prisma client if schema changed
pnpm prisma:generate

# Restart scheduler
pm2 restart whatsapp-scheduler

Environment Variables Reference

DATABASE_URL · string · required

MongoDB connection string

Format: mongodb+srv://username:[e-mail]/database-name

Example: mongodb+srv://admin:[e-mail]/whatsapp-prod

WAHA_API_URL · string · required

Base URL of your WAHA server

Example: http://localhost:3000 or https://waha.yourdomain.com

WAHA_API_KEY · string · required

API key for authenticating with WAHA

Example: abc123xyz789

BETTER_AUTH_SECRET · string · required

Secret key for Better Auth session encryption

Generate with: openssl rand -base64 32

Example: xK8vN2mP9qR4sT5uV6wX7yZ8aB1cD2eF3gH4iJ5kL6==

BETTER_AUTH_URL · string · required

Base URL of your application

Development: http://localhost:3001

Production: https://your-app.vercel.app

MAILGUN_API_KEY · string · required

Mailgun API key for sending emails

Format: key-xxxxxxxxxxxxxxxxxxxxxxxx

Find in: Mailgun Dashboard → Settings → API Keys

MAILGUN_DOMAIN · string · required

Your verified Mailgun domain

Example: mg.yourdomain.com or sandboxxxxx.mailgun.org

FROM_EMAIL · string · required

Email address to send from (must use Mailgun domain)

Example: [e-mail]

ADMIN_EMAIL · string · required

Admin email for receiving notifications

Example: [e-mail]

ADMIN_PHONE_NUMBER · string

Admin WhatsApp number for notifications

Format: Include country code with +

Example: [phone]

NEXT_PUBLIC_SHOW_FOOTER · string

Show or hide footer in application

Default: true

Options: true or false

Database Schema Overview

The application uses these main collections:

User & Authentication

• user: User accounts with roles (ADMIN, USER, GUEST)
• session: Active user sessions with expiry
• account: Password hashes and OAuth provider data
• verification: Email verification tokens

WhatsApp Connections

• WhatsAppSession: Connected WhatsApp accounts
  • sessionName: Unique session identifier
  • phoneNumber: Connected phone number
  • status: CONNECTED or DISCONNECTED
• WhatsAppGroup: Synced WhatsApp groups
  • groupName: Display name
  • groupId: WhatsApp group ID

Campaign Management

• MessageCampaign: Scheduled campaigns
  • title: Campaign name
  • template: Message template with placeholders
  • sendTimeUtc: Scheduled send time
  • status: DRAFT, SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED, FAILED
• Message: Individual messages to send
  • content: Processed message content
  • scheduledAt: When to send
  • sentAt: When actually sent
  • isSent: Delivery status

Available Scripts

Development

# Start development server (Next.js on port 3001)
pnpm dev

# Start message scheduler
pnpm scheduler:start

# Open Prisma Studio (database GUI)
pnpm db:studio

# Build for production (includes db:push and prisma:generate)
pnpm build

# Start production server
pnpm start

# Build and start
pnpm preview

# Push schema to database
pnpm db:push

# Generate Prisma Client
pnpm prisma:generate

# Open Prisma Studio
pnpm db:studio

# Run ESLint
pnpm lint

# Fix ESLint issues automatically
pnpm lint:fix

# Run TypeScript type checking
pnpm typecheck

# Run both lint and typecheck
pnpm check

# Check code formatting
pnpm format:check

# Format code with Prettier
pnpm format:write

Troubleshooting

Prisma Client Generation Failed

Error: @prisma/client did not initialize yet

Solution:

# Manually generate Prisma client
pnpm prisma:generate

# If that fails, try
rm -rf node_modules/.prisma
pnpm install

MongoDB Connection Issues

Error: Error connecting to database or ECONNREFUSED

Solutions:

• Verify DATABASE_URL is correctly formatted
• For MongoDB Atlas:
  • Whitelist your IP address in Network Access
  • Check username/password are URL-encoded
  • Ensure database user has read/write permissions
• For local MongoDB:
  • Ensure MongoDB service is running
  • Try mongodb://localhost:27017/whatsapp-manager

WAHA Connection Failed

Error: Cannot connect to WAHA server

Solutions:

• Verify WAHA is running: curl http://localhost:3000/health
• Check WAHA_API_URL points to correct address
• Verify WAHA_API_KEY matches WAHA configuration
• Ensure no firewall blocking the connection

Email Sending Fails

Error: Failed to send email or Mailgun errors

Solutions:

• Verify Mailgun API credentials are correct
• Check domain is verified in Mailgun dashboard
• Ensure FROM_EMAIL uses your Mailgun domain
• For sandbox domain, add recipient email to authorized recipients

Messages Not Sending Automatically

Issue: Scheduled messages remain in SCHEDULED status

Solutions:

• Ensure scheduler is running: pnpm scheduler:start
• Check scheduler logs for errors
• Verify scheduled time is in the past (UTC)
• Check WhatsApp session is CONNECTED
• Ensure WAHA server is accessible from scheduler

Port 3001 Already in Use

Error: Port 3001 is already in use

Solution:

# Find process using port 3001
lsof -i :3001

# Kill the process (replace PID with actual process ID)
kill -9 PID

# Or use a different port
PORT=3002 pnpm dev

Security Best Practices

Follow these security guidelines for production deployments:

• Never commit .env file to version control
• Use strong, unique secrets for BETTER_AUTH_SECRET in production
• Rotate API keys regularly (Mailgun, WAHA)
• Enable MongoDB authentication and use strong passwords
• Restrict MongoDB network access to your server IPs only
• Use HTTPS for production deployments (Vercel provides this automatically)
• Set up IP whitelisting for WAHA if possible
• Regularly update dependencies with pnpm update
• Monitor logs for suspicious activity
• Backup database regularly (MongoDB Atlas has automated backups)

Next Steps

After successful installation:

User Guide

Learn how to use the dashboard and manage campaigns

API Documentation

Explore tRPC API endpoints and integration options

Contributing

Contribute to the project on GitHub

Support

Get help and report issues