Whatsway — Application Update Guide

Before You Begin — Pre-Update Checklist

Complete every item on this checklist before starting the update:

All active campaigns have finished sending (no campaigns in "active" or "queued" status)
You have SSH / terminal access to the server
You know your current application version (check package.json → "version")
Database backup has been created (see Step 1)
Code backup has been created (see Step 1)
You have the new version files ready (Git access or ZIP file)
At least 1 GB of free disk space available
No users are actively sending messages (schedule update during low-traffic hours)

💡

Recommended: Schedule updates during off-peak hours (e.g., early morning or late night) when message traffic is lowest.

Protected Files & Directories

🚨

CRITICAL: The files and directories listed below contain your business data, credentials, and user uploads. Deleting or overwriting any of these will result in permanent data loss.

🔒 NEVER delete or overwrite these:

🚫 .env — Database credentials, API keys, Meta tokens, payment gateway secrets, SMTP settings
🚫 uploads/ — All user-uploaded media: profile photos, campaign images, template media, chat attachments
🚫 PostgreSQL Database — All conversations, contacts, campaigns, templates, subscriptions, user accounts (managed by your DB service, not stored in the app folder)

⚠️

Note: The node_modules/ directory will be regenerated by npm install. It is safe to delete this folder — it does not contain any user data.

Files that ARE safe to replace

Path	Description
`server/`	Backend source code
`client/`	Frontend source code
`shared/`	Shared schemas and types
`packages/`	Internal packages (diploy-core)
`dist/`	Built output (regenerated by `npm run build`)
`package.json`	Dependencies and scripts
`tsconfig.json`	TypeScript configuration
`vite.config.ts`	Frontend build configuration
`drizzle.config.ts`	Database ORM configuration
`tailwind.config.ts`	CSS framework configuration

Step 1 — Backup Your Data

🚨

Do NOT skip this step. Always create a backup before updating. If anything goes wrong, your backup is the only way to restore your data.

1A. Backup the Database

# Replace with your actual database credentials
pg_dump -U your_db_user -h your_db_host -d your_db_name > backup_$(date +%Y%m%d_%H%M%S).sql

If you are using a managed database (e.g., AWS RDS, DigitalOcean, Supabase), you can also create a snapshot from your hosting provider's dashboard.

1B. Backup the Application Code

# Create a timestamped backup of the entire application
cd /path/to/your/app
tar -czf ../whatsway_backup_$(date +%Y%m%d_%H%M%S).tar.gz \
  --exclude='node_modules' \
  --exclude='dist' \
  .

1C. Backup Uploads (if not stored externally)

# If uploads are stored locally on disk
cp -r uploads/ ../uploads_backup_$(date +%Y%m%d_%H%M%S)/

✅

After backup, verify the backup file size is reasonable and the SQL dump is not empty before proceeding.

Step 2 — Update Application Code

Choose the update method that matches how you received the new version:

Method A — Git-Based Update (Recommended)

If your application was deployed using Git, this is the fastest and safest method.

1

Stop the application

pm2 stop all

2

Navigate to the application directory

cd /path/to/your/whatsway-app

3

Pull the latest code

git pull origin main

If you have local changes that conflict, stash them first:

git stash
git pull origin main
git stash pop

💡

Git should not overwrite your .env file or uploads/ directory if they are untracked. Verify before pulling: run git status and confirm these files are not listed as tracked changes.

Method B — ZIP File Update

Use this method if you received the update as a ZIP file (e.g., from CodeCanyon or direct download).

1

Stop the application

pm2 stop all

2

Upload the ZIP file to your server

# From your local machine
scp whatsway-v3.x.x.zip user@your-server:/tmp/

3

Save your protected files

cd /path/to/your/whatsway-app

# Save .env and uploads to a safe location
cp .env /tmp/.env.backup
cp -r uploads/ /tmp/uploads_safe/

⚠️

Custom code warning: If you have made any custom modifications to the application code (server/, client/, shared/), those changes will be lost in the next step. Back up any customized files separately before proceeding.

4

Extract the ZIP (replace code files only)

# Remove old code directories (safe to delete)
rm -rf server/ client/ shared/ packages/ dist/

# Extract new code
unzip -o /tmp/whatsway-v3.x.x.zip -d /path/to/your/whatsway-app/

5

Restore your protected files

# Restore .env if it was overwritten
cp /tmp/.env.backup .env

# Restore uploads if they were overwritten
cp -r /tmp/uploads_safe/* uploads/

🚨

Double-check: After extraction, verify that .env still contains your database URL, API keys, and Meta tokens. Open it with cat .env and confirm the values are present.

Step 3 — Install Dependencies

1

Install/update npm packages

npm install

This reads the new package.json and installs any added or updated packages. Your data is not affected.

2

Build the application

npm run build

This compiles the frontend (React/Vite) and backend (TypeScript) into production-ready files in the dist/ directory.

⚠️

If npm install fails with permission errors, first try fixing directory ownership: sudo chown -R $(whoami) node_modules/. Only as a last resort, use: sudo npm install --unsafe-perm (avoid running npm as root on production systems when possible).

Step 4 — Update Database Schema

The application uses Drizzle ORM with PostgreSQL. New versions may add columns or tables. The update process is non-destructive — it only adds new structures, never deletes existing data.

Option A: Automatic (Recommended)

npm run db:push -- --force

This synchronizes the database schema with the latest code. The --force flag skips interactive prompts. In normal version upgrades, this adds new columns and tables to support new features.

⚠️

Always create a database backup before running db:push. While version upgrades are designed to be additive (adding columns/tables), the --force flag applies all schema changes without confirmation. A backup ensures you can recover if anything unexpected occurs.

Option B: Self-Healing on Startup

The application has a built-in startup migration system that automatically detects and adds any missing columns or tables when the server starts. This is a safety net that only performs additive changes (ADD COLUMN, CREATE TABLE). Running db:push explicitly is still preferred for full schema synchronization.

✅

Standard upgrades are additive. Version updates typically only add new columns and tables. Your existing conversations, contacts, campaigns, templates, and subscriptions are preserved. However, always keep a backup as a precaution.

Step 5 — Restart the Application

# Restart with PM2
pm2 restart all

# View logs to confirm startup
pm2 logs

You should see output similar to:

╔════════════════════════════════════════╗
║   DIPLOY                               ║
║   WhatsApp Marketing Platform  v3.x    ║
║   © Bisht Technologies Pvt Ltd         ║
╚════════════════════════════════════════╝
[Diploy] Server running on port 5000
[startup-migration] All schema checks passed — database is up to date.

💡

If you see [startup-migration] Added X missing column(s), that means the self-healing migration successfully added new database fields. This is normal and expected.

Step 6 — Verify the Update

After restarting, verify everything is working:

Application loads in the browser (login page appears)
You can log in with your admin account
Version number in the app matches the new version
Existing contacts are visible in the Contacts page
Existing conversations appear in the Inbox
Templates are listed and show correct status
WhatsApp channel(s) show "Connected" or "Healthy" status
Uploaded media (logos, profile photos) display correctly
Send a test message to verify WhatsApp connectivity
Check PM2 logs for errors: pm2 logs --lines 100

Rollback — Undo the Update

If something went wrong after updating, follow these steps to restore the previous version:

Rollback Code

# Stop the app
pm2 stop all

# Check your Git log to find the previous version's commit
git log --oneline -5

# Reset to the previous version (replace COMMIT_HASH with the hash you want)
git reset --hard COMMIT_HASH

# Reinstall dependencies and rebuild
npm install
npm run build

# Restart
pm2 restart all

# Stop the app
pm2 stop all

# Restore from your backup archive
cd /path/to/your
tar -xzf whatsway_backup_YYYYMMDD_HHMMSS.tar.gz -C whatsway-app/

# Restore .env and uploads
cp /tmp/.env.backup whatsway-app/.env
cp -r /tmp/uploads_safe/* whatsway-app/uploads/

# Reinstall dependencies and rebuild
cd whatsway-app
npm install
npm run build

# Restart
pm2 restart all

Rollback Database (if needed)

Only restore the database backup if the new version caused data corruption (this is extremely rare):

# WARNING: This replaces ALL current data with the backup
psql -U your_db_user -h your_db_host -d your_db_name < backup_YYYYMMDD_HHMMSS.sql

🚨

Database rollback is destructive. Any new conversations, messages, or contacts received AFTER the backup was created will be lost. Only restore the database as a last resort.

Troubleshooting

Application won't start after update

Check the logs for errors:

pm2 logs --lines 200 --err

Common causes:

Missing environment variable: Compare your .env with the .env.example in the new version. New features may require new environment variables.
Port already in use: Run pm2 delete all then pm2 start npm -- start
Node.js version mismatch: Check required version in package.json. Run node -v to verify. Node.js v18 or later is recommended.

`npm install` fails

Delete node_modules and package-lock.json, then run npm install again
Ensure you have at least 1 GB of free disk space: df -h
Check your Node.js version: node -v (v18 or later recommended)

`npm run build` fails with memory error

# Increase Node.js memory limit
NODE_OPTIONS=--max-old-space-size=2048 npm run build

`db:push` fails or hangs

Verify DATABASE_URL is set correctly in your .env
Test database connectivity: psql $DATABASE_URL -c "SELECT 1"
If it hangs, use the --force flag: npm run db:push -- --force

Login page shows but can't log in

Clear your browser cache and cookies for the site
Check that the SESSION_SECRET in .env hasn't changed
Verify the database is accessible and contains your user records

WhatsApp messages not sending after update

Verify Meta access tokens in your channel settings haven't expired
Check webhook subscription status in Settings → Webhooks
Ensure the WHATSAPP_VERIFY_TOKEN in .env matches your Meta app configuration

Uploaded images/media not showing

Confirm the uploads/ directory exists and has correct permissions: ls -la uploads/
Check file ownership: chown -R www-data:www-data uploads/ (or your app user)
If using cloud storage (S3/DigitalOcean Spaces), verify storage credentials in .env

Still stuck?

Contact support at cs@diploy.in with:

Your current version and the version you're updating to
The error message from pm2 logs
Your Node.js version (node -v) and OS

Quick Reference — One-Line Update (Git)

For experienced users who have done this before, the entire update process can be run as a single command:

cd /path/to/your/app && git pull && npm install && npm run build && npm run db:push -- --force && pm2 restart all && pm2 logs

⚠️

The one-liner above assumes you have already backed up your data. Always create a backup first.

💡

package.json includes a shortcut script npm run update:code, but it does not run npm install. If the new version adds or changes dependencies, use the full command above instead.