VPS Deployment & Configuration - Wapi documentation

Welcome to WAPI!

Get an AI summary of this page

Introduction

This guide explains how to deploy the Wapi backend on a VPS (Virtual Private Server). You'll set up the server, install all required tools, configure the database, and run Wapi securely in production. VPS deployment is the recommended method because it gives full control over performance, scaling, security, and custom configurations.

System Setup

After connecting to your VPS via SSH, start by updating your server and installing required packages.

                  sudo apt update && sudo apt upgrade -y
sudo apt install curl wget git unzip -y

This installs essential utilities needed later to fetch and manage Wapi backend files and dependencies.

Install Node.js Runtime

The Wapi backend is built on Node.js. Install the latest LTS version:

                  
                      curl -fsSL https://deb.nodesource.com/setup_22.x | sudo
                      -E bash -
                    
sudo apt-get install -y nodejs
node --version
npm --version

Confirming the version ensures Node.js and npm installed successfully.

Install and Configure Database

Wapi now uses MongoDB for storing user data, messages, calls, posts, media metadata, and other application data.

Install MongoDB Community Edition (recommended version: 8.0 or latest stable)

1. Import the MongoDB public GPG Key (for version 8.0):

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc

                  
                      sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg
                      --dearmor

2. Create the list file (for Ubuntu 22.04 = jammy | 24.04 = noble):

Use 'jammy' for Ubuntu 22.04, 'noble' for Ubuntu 24.04

                  
                      echo "deb [ arch=amd64,arm64
                      signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ]
                      https://repo.mongodb.org/apt/ubuntu
                      noble/mongodb-org/8.0 multiverse" |
                    
                      sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

3. Update and install MongoDB

                  sudo apt update
sudo apt install -y mongodb-org

4. Start and enable MongoDB service

                  sudo systemctl start mongod
sudo systemctl enable mongod

5. Verify installation

                  sudo systemctl status mongod
mongod --version
mongosh --version

                

6. Create MongoDB Admin User

Open MongoDB shell:

mongosh

Switch to admin database:

use admin

Create admin user:

                  
                      db.createUser({
                    
                      user: "admin",
                    
                      pwd: "strongpassword",
                    
                      roles: [ { role: "root", db: "admin" } ]
                    
                      })

Enable authentication (security best practice):

sudo nano /etc/mongod.conf

                  security:
  authorization: "enabled"

Restart MongoDB:

sudo systemctl restart mongod

Connect using authentication:

mongosh -u admin -p --authenticationDatabase admin

Deploy the Application Code

Upload the Wapi backend folder or clone it directly from your repository:

                  git clone <your-repo-url>
cd wapi-backend
npm install --production

                

After installation, create a .env file and add all required backend configuration values.

Detailed Environment Configuration

The .env file is critical for the Wapi backend to interact with third-party services like Stripe, Razorpay, PayPal, and Meta (WhatsApp). Ensure you copy .env.example to .env and fill in the following values.

Category	Variables	Description & Sources
Stripe (Global)	`STRIPE_SECRET_KEY` `STRIPE_PUBLISHABLE_KEY` `STRIPE_WEBHOOK_SECRET`	Supported Currencies: 135+ (USD, EUR, GBP, INR, etc.). How to get: Log in to Stripe Dashboard -> Developers -> API Keys. Webhook secret is in Developers -> Webhooks.
Razorpay (India)	`RAZORPAY_KEY_ID` `RAZORPAY_KEY_SECRET` `RAZORPAY_WEBHOOK_SECRET`	Supported Currencies: INR (Primary), 90+ International. How to get: Go to Razorpay Dashboard -> Settings -> API Keys -> Create Key.
PayPal (Global)	`PAYPAL_MODE` (live/sandbox) `PAYPAL_CLIENT_ID` `PAYPAL_CLIENT_SECRET` `PAYPAL_WEBHOOK_ID`	Supported Currencies: 25+ (USD, EUR, GBP, JPY, AUD, CAD, etc.). How to get: Visit PayPal Developer Portal -> My Apps & Credentials -> Create App.
WhatsApp (Meta) Flow	`WHATSAPP_VERIFY_TOKEN`	How to get: Defined by you in the Meta App Dashboard under the WhatsApp -> Configuration section for webhook verification.
Auth & Google	`JWT_SECRET` `GOOGLE_CLIENT_ID` `GOOGLE_CLIENT_SECRET` `GOOGLE_REDIRECT_URI` `FRONT_REDIRECT_URL` `FRONTEND_URL`	How to get: `JWT_SECRET` is your own random secure string. Google keys are in Google Cloud Console. For detailed Google Integration steps, refer to our Admin Settings Guide.
Database & Cache	`MONGODB_URI` `REDIS_HOST` `REDIS_PORT` `REDIS_PASSWORD` `REDIS_URL`	How to get: `MONGODB_URI` is your connection string from MongoDB Atlas or local install. Redis values depend on your server setup (default: `localhost:6379`).
Email (SMTP)	`SMTP_HOST` `SMTP_PORT` `SMTP_USER` `SMTP_PASS` `MAIL_FROM_NAME` `MAIL_FROM_EMAIL` `SUPPORT_EMAIL`	How to get: Credentials from your email provider (e.g., Gmail App Password or SendGrid API Keys).
App Settings	`PORT` `DEMO` `APP_URL` `ALLOWED_ORIGINS` `MAINTENANCE_MODE`	Basic application configuration. `PORT` defaults to 3000. `DEMO` mode enables/disables public demo features. `APP_URL`: Your backend URL, used for Webhooks (e.g., your ngrok URL for local testing). `ALLOWED_ORIGINS`: Comma-separated list of allowed frontend domains for CORS.

Complete .env Template

                  # APP CONFIG
PORT=3000
DEMO=true
APP_URL=https://yourdomain.com
SERVER_ADDR=
# APP ID (Do not change this)
APP_ID=VVlHTldWMk4wSQ==
ALLOWED_ORIGINS=
FRONTEND_URL=https://your-frontend.com
MAINTENANCE_MODE=false
# ADMIN CONFIG
ADMIN_NAME=Admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_secure_password
# DATABASE & CACHE
MONGODB_URI=mongodb://127.0.0.1:27017/wapi
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_URL=
# SECURITY
JWT_SECRET=your_jwt_secret_here
# STRIPE
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
# RAZORPAY
RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_KEY_SECRET=...
RAZORPAY_WEBHOOK_SECRET=...
# PAYPAL
PAYPAL_MODE=sandbox
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_WEBHOOK_ID=...
# WHATSAPP / META
WHATSAPP_VERIFY_TOKEN=your_custom_token
# GOOGLE AUTH
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=https://yourdomain.com/api/auth/google/callback
FRONT_REDIRECT_URL=https://your-frontend.com/login
# EMAIL
SMTP_HOST=...
SMTP_PORT=...
SMTP_USER=...
SMTP_PASS=...
MAIL_FROM_NAME="Wapi Support"
MAIL_FROM_EMAIL=no-reply@yourdomain.com
SUPPORT_EMAIL=support@yourdomain.com

                    FACEBOOK_LEAD_WEBHOOK_VERIFY_TOKEN=your_custom_token
                  
                

The .env file ensures the backend loads settings securely and consistently across environments.

How to Run Seeding

To seed all data to the database, navigate to your backend directory and run the following command:

npm run seed

Note: Ensure your .env file is correctly configured with your MongoDB connection string before running the seed command.

Process Management

To keep Wapi running continuously and auto-restart on errors, use PM2:

                  sudo npm install -g pm2
pm2 start server.js --name wapi-backend
pm2 save
pm2 startup

                

PM2 ensures uptime, handles crashes, and provides clean logging tools.

Reverse Proxy Setup (Nginx)

Wapi runs on an internal port (e.g., 4000), so you need Nginx to route traffic from your domain.

Create an Nginx config file:

sudo nano /etc/nginx/sites-available/wapi

Add the following configuration:

                  server {
  listen 80;
  server_name your-domain.com;
  location / {

                          proxy_pass
                      http://localhost:4000;
                    
    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 and restart Nginx:

                  
                      sudo ln -s /etc/nginx/sites-available/wapi
                      /etc/nginx/sites-enabled/
                    
sudo nginx -t
sudo systemctl restart nginx

Your Wapi backend will now be available through your domain.

Enable SSL (HTTPS)

Secure your API with a free Let’s Encrypt SSL certificate:

                  sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your-domain.com

Set up auto-renewal:

0 12 * * * /usr/bin/certbot renew --quiet

Setup Cron Job

Cron jobs are used to schedule automatic tasks on your server such as database maintenance, SSL renewal, queue processing, and more.

Type 1: Internal Cron Jobs (node-cron)

Wapi includes internal cron jobs managed via the node-cron library. These tasks are handled directly within the Node.js process and include:

Automatic message status updates
System logs cleanup
Periodic database synchronization
Subscription status updates (Status Cron)
Trial expiry and user cleanup (Trial Cron)

Requirement: These run automatically as long as the PM2 process is active. No manual crontab entry is needed for these internal tasks.

Customization: If you want to change the schedule of internal cron jobs:

Go to your project cron job folder (e.g., /cron or /services/cron)
Locate the relevant file:
- Status Cron (subscription expiry handling)
- Trial Period Cron (trial cleanup and deletion)
Update the schedule inside the cron.schedule() method

Cron Schedule Format:

                  * * * * *
| | | | |
| | | | └── Day of week (0 - 7)
| | | └──── Month (1 - 12)
| | └────── Day of month (1 - 31)
| └──────── Hour (0 - 23)
└────────── Minute (0 - 59)

                

                  Example:
0 0 * * * → Runs daily at 12:00 AM
0 1 * * * → Runs daily at 1:00 AM

                

Important: After modifying the cron schedule, you must restart your application for changes to take effect:

pm2 restart all

Testing and Verification

Visit your domain (e.g., https://your-domain.com/api) to confirm Wapi is running correctly.

Check logs with:

pm2 logs wapi-backend

Verify API responses, media upload paths, authentication, and real-time events.

Maintenance & Updates

To update your Wapi backend in the future:

                  git pull origin main
npm install
pm2 restart wapi-backend

                

It is recommended to monitor CPU, RAM, disk usage, database health, and system logs regularly.

Summary

By following this guide, your Wapi backend will be fully deployed on a VPS with a secure, scalable, and production-ready environment. This deployment method ensures reliable performance, smooth real-time messaging with Socket.io, and fast audio/video calling using WebRTC.

What's Next?

Let’s continue — your social world lives on Wapi!

Deploy on CPanel

Host Wapi using shared hosting

Deploy on Vercel

Frontend deployment instructions

Wapi Installation

Frontend setup and configuration

Chat, collaborate, and create teams effortlessly with Wapi