WhatsApp Bridge Service

Appearance

🏁 Ultimate Deployment Guide ​

This guide provides everything you need to take your WhatsApp Bridge Service from local code to a 24/7 production environment. No external searching required.

🛠️ Prerequisites ​

Before you start, ensure you have:

  1. WhatsApp Account: A dedicated phone or virtual number for the bridge.
  2. Hosting: A server (VPS) or a cloud platform (Render/Railway).
  3. Domain (Optional): Needed if you want a professional URL like bridge.yourdomain.com.

🏗️ 1. Oracle Cloud (Always Free ARM) - BEST VALUE ​

Oracle offers a "Forever Free" tier that is perfect for this service.

Step 1: Create Your Instance ​

  1. Sign up at Oracle Cloud.
  2. Navigate to Compute > Instances > Create Instance.
  3. Image and Shape: Select Ubuntu 22.04 and for Shape select Ampere (ARM) with 1-4 OCPUs and 6-24GB RAM.
  4. Networking: Ensure "Assign a public IPv4 address" is checked.
  5. SSH Keys: Download your Private Key (.key or .pub).

Step 2: Open Firewall (VCN) ​

By default, Oracle blocks all ports. You MUST open 3001:

  1. Go to your Instance Details > Click the Subnet link.
  2. Click the Default Security List.
  3. Click Add Ingress Rules:
    • Source CIDR: 0.0.0.0/0
    • IP Protocol: TCP
    • Destination Port Range: 3001
    • Description: WhatsApp Bridge API

Step 3: Connect to your Server ​

bash
# On your local machine (using the key you downloaded)
chmod 400 your_oracle_key.key
ssh -i your_oracle_key.key ubuntu@YOUR_INSTANCE_IP

🏰 2. Hostinger VPS (Easiest KVM Setup) ​

Hostinger's KVM VPS is highly optimized for Node.js performance.

  1. Sign Up: Sign Up via Hostinger
  2. Plan: Select "KVM VPS 1" or higher.
  3. Setup: Choose Ubuntu 22.04 during the initial setup wizard.
  4. Login: Hostinger will provide you with a Root Password. SSH in using:
    bash
    ssh root@YOUR_HOSTINGER_IP

⚡ 3. Railway.app & Render.com (No-Server Setup) ​

Perfect for those who don't want to manage a Linux terminal.

  1. Sign Up: Sign Up via Railway
  2. New Project: Create from GitHub Repo.
  3. Variables: Add API_KEY and PORT=3001.
  4. Persistence (CRITICAL):
    • Go to Settings > Volumes.
    • Add a Volume mounted at /app/auth (to keep your WhatsApp login) and /app/logs (for audit logs).

Render.com (Simple Web Services) ​

  1. Sign Up: Sign Up via Render
  2. Web Service: Connect your GitHub repo.
  3. Disk: Add a Persistent Disk mounted at /app/auth. Note: Render does not currently offer a public referral program.

Fly.io (The Modern MicroVM) - HIGH PERFORMANCE ​

  1. Sign Up: Sign Up via Fly.io
  2. Install flyctl: Follow the official guide to install the CLI on your machine.
  3. Deploy:
    bash
    # Login and Launch
fly auth login
fly launch

# Create Volume for Persistence (1GB)
fly volumes create wa_data --size 1

# Deploy (Uses the Project's fly.toml)
fly deploy

Note: Fly.io does not currently offer a public referral program.

🏗️ 4. DigitalOcean (The Developer Standard) ​

DigitalOcean offers both a simple "App Platform" and traditional "Droplets" (VPS).

  1. Sign Up: Sign Up via DigitalOcean
  2. App Platform (Managed):
    • Similar setup to Railway/Render.
    • Add a Volume for /app/auth.
  3. Droplets (VPS):
    • Deploy a $4-6/mo Droplet with Ubuntu.
    • Follow the Server Essentials guide below.

⚙️ 5. Server Essentials (The Zero-to-Live Commands) ​

Once logged into your Ubuntu/Linux server, run these in order:

1. Install Node.js (Standard: 18+) ​

The bridge is designed for Node.js 18 or 20. These versions are required for modern security, V8 performance, and long-term ecosystem stability.

bash
# Recommended for standard servers (Node 20)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

2. Setup the Project ​

bash
git clone https://github.com/ahtesham-clcbws/whatsapp-bridge-service.git
cd whatsapp-bridge-service
npm install

3. Configure Environment ​

bash
cp .env.example .env
nano .env
# Edit your API_KEY and PORT here, then CTRL+O (Save) and CTRL+X (Exit)

4. 24/7 Persistence (PM2) ​

bash
sudo npm install -g pm2
pm2 start src/index.js --name "wa-bridge"
pm2 save
pm2 startup
# (Copy and paste the command generated by the startup command)

🌐 5. Advanced: Custom Domain & SSL (HTTPS) ​

If you have a domain, use Nginx to add SSL security.

1. Install Nginx ​

bash
sudo apt update
sudo apt install nginx -y

2. Configure Nginx Proxy ​

bash
sudo nano /etc/nginx/sites-available/wa-bridge

Paste this (Replace bridge.yourdomain.com):

nginx
server {
    server_name bridge.yourdomain.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable it:

bash
sudo ln -s /etc/nginx/sites-available/wa-bridge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

3. Add Free SSL (Certbot) ​

bash
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d bridge.yourdomain.com

🍓 6. Raspberry Pi & ARM Boards (Mini-Computer) ​

This bridge is specifically designed to be Zero-Bloat, making it ideal for 24/7 Raspberry Pi setups.

Performance Tuning for ARM ​

  • Memory: Ensure at least 512MB RAM is free.
  • Node Choice: Use Node 18 if possible; it has the best performance-to-security ratio on ARMv7/v8.
  • SQLite Latency: Use a high-quality (Class 10) SD card to avoid database write lag during session archiving.

24/7 Reliability ​

If your Pi is in a remote location, we recommend setting up a daily automated health check:

bash
# Add to crontab to check every hour
* * * * * curl -f http://localhost:3001/health || pm2 restart wa-bridge

🏰 7. Self-Hosting: MacBook Air (Legacy macOS) ​

If you are using an older Mac (Big Sur 11.7) as your 24/7 server, use Localtunnel to bypass modern library crashes.

Step 1: Install & Start ​

bash
npm install -g localtunnel
pm2 start "lt --port 3001 --subdomain your-name" --name wa-tunnel --max-restarts 10

Step 2: Protocol Bypass (Laravel/API) ​

Localtunnel requires a header to skip its intervention page. Add this to your API requests:

php
'headers' => [
    'bypass-tunnel-reminder' => 'true'
]

🆙 8. Modernizing Your Bridge (v3.7.0 Update) ​

If you are running an older version (v1.x or v2.x), follow these steps to upgrade to the latest enterprise-grade features.

IMPORTANT

Backup your session! Before any update, ensure you have a copy of your auth/ directory. This contains your WhatsApp link data.

We provide a simple script to handle the backup, code pull, and restart automatically.

bash
# Run the official upgrade script
chmod +x scripts/upgrade.sh
./scripts/upgrade.sh

Option B: The Manual Upgrade ​

If you prefer to run commands manually or use a custom git setup:

  1. Stop the Service:
    bash
    pm2 stop wa-bridge
  2. Pull Latest Code:
    bash
    git fetch --all
git reset --hard origin/master
  3. Refresh Dependencies:
    bash
    npm install
  4. Verify & Restart:
    bash
    pm2 start wa-bridge

Post-Update Verification ​

Once updated, visit your Admin Dashboard and check the footer. It should report v3.7.0. Your existing templates and logs will be preserved automatically.

IMPORTANT

Backup your session! Always keep a copy of the auth/ folder. If you move servers, simply copy this folder to the new one to avoid re-scanning the QR code.