# Whatsway — Application Update Guide

Safely update your application without losing any data

By Bisht Technologies Pvt Ltd • diploy.in

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