wirabasalamah/whatsapp-inbox-platform
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
137edc12b7cb12b8ddc490c4aa20670fc4182d09
whatsapp-inbox-platform/docs/setup-guide.md
wirabasalamah 137edc12b7
Some checks are pending
CI - Production Readiness / Verify (push) Waiting to run
Details
fix: lates
2026-04-21 20:37:59 +07:00

7.4 KiB
Raw Blame History

Guide Setup & Deployment (from zero to production)

Dokumen ini berisi urutan setup dari awal, termasuk instalasi dependency, konfigurasi environment, deploy, dan pengecekan.

A. Prasyarat Dasar

  • Linux server Linux Mint/Ubuntu.
  • User deploy dengan sudo tanpa password (sudah disiapkan di server Anda).
  • Akses SSH ke server.
  • Domain yang mengarah ke server, contoh web.zappcare.id.
  • PostgreSQL sudah ada untuk production.

B. Setup Lokal (Developer)

B1. Clone dan install

git clone https://git.iptek.co/wirabasalamah/whatsapp-inbox-platform.git
cd whatsapp-inbox-platform
npm install

B2. Siapkan .env

cp .env.example .env

Edit .env minimal:

  • DATABASE_URL
  • AUTH_SECRET
  • APP_URL=http://localhost:3002
  • SESSION_TTL_SECONDS=86400
  • COOKIE_SECURE=false untuk lokal non-HTTPS

B3. Jalankan DB lokal

npx prisma generate
npm run db:migrate
npm run db:seed

B4. Jalankan aplikasi

npm run dev

Untuk build check:

npm run build

C. Setup Server (Dari Kosong)

C1. Install Node.js + Git + Nginx + PostgreSQL + PM2

sudo apt update
sudo apt install -y curl git nginx postgresql
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pm2

Catatan:

  • Versi Node.js disesuaikan dengan kebutuhan proyek.
  • Gunakan pnpm jika Anda standardize npm/pnpm di server, tapi repo ini diuji dengan npm.

C2. Setup user deploy

Contoh:

sudo adduser --system --group whatsapp-inbox
sudo mkdir -p /var/www/whatsapp-inbox-platform
sudo chown -R whatsapp-inbox:whatsapp-inbox /var/www/whatsapp-inbox-platform

C3. Clone repo dan set permission

sudo -u whatsapp-inbox -H git clone https://git.iptek.co/wirabasalamah/whatsapp-inbox-platform.git /var/www/whatsapp-inbox-platform
sudo chown -R whatsapp-inbox:whatsapp-inbox /var/www/whatsapp-inbox-platform
sudo chmod -R g+rwX /var/www/whatsapp-inbox-platform

C4. Konfigurasi Database PostgreSQL

-- psql as postgres
CREATE DATABASE whatsapp_inbox;
CREATE USER whatsapp_inbox WITH ENCRYPTED PASSWORD 'isi_password_kuat';
GRANT ALL PRIVILEGES ON DATABASE whatsapp_inbox TO whatsapp_inbox;

Pastikan DATABASE_URL mengarah ke:

postgresql://whatsapp_inbox:password@127.0.0.1:5432/whatsapp_inbox?schema=public

C5. Set .env production

Buat .env di /var/www/whatsapp-inbox-platform/.env berdasarkan .env.example.

Wajib isi:

  • NODE_ENV=production
  • PORT=3002
  • DATABASE_URL=...
  • AUTH_SECRET=... (random panjang)
  • APP_URL=https://web.zappcare.id
  • SESSION_TTL_SECONDS=86400
  • COOKIE_SECURE=true
  • SESSION_COOKIE_DOMAIN=web.zappcare.id
  • CAMPAIGN_RETRY_JOB_TOKEN=...
  • WHATSAPP_WEBHOOK_VERIFY_TOKEN=...
  • WHATSAPP_WEBHOOK_SECRET=...

Opsional:

  • OPS_SESSION_CHECK_EMAIL, OPS_SESSION_CHECK_PASSWORD untuk verifikasi otomatis.

C6. Build dan Deploy awal

cd /var/www/whatsapp-inbox-platform
npm ci
npm run build
npm run db:deploy
npm run ops:safe-restart

ops:safe-restart juga melakukan install+build+migrate jika dipanggil dari state normal.

C7. Nginx + SSL

Konfigurasi Nginx (contoh sederhana):

server {
  listen 80;
  server_name web.zappcare.id;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl http2;
  server_name web.zappcare.id;

  ssl_certificate /etc/letsencrypt/live/web.zappcare.id/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/web.zappcare.id/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:3002;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Setup Let’s Encrypt:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d web.zappcare.id

Reload nginx:

sudo nginx -t && sudo systemctl reload nginx

D. Deployment Routine Setelah Update

D0. Alur source code ke Git

Kerjakan perubahan di folder lokal:

cd /home/wira/work/whatsapp-inbox-platform

Pastikan file sensitif seperti .env tidak ikut di-commit. Repo ini sudah meng-ignore .env.

Command Git manual dari lokal:

cd /home/wira/work/whatsapp-inbox-platform
git status
git add .
git commit -m "fix: deskripsi perubahan"
git push origin main

Jika ingin cek commit terakhir yang sudah siap diambil server:

cd /home/wira/work/whatsapp-inbox-platform
git log --oneline -n 5

D1. Pull dan jalankan restart aman

cd /var/www/whatsapp-inbox-platform
git pull origin main
npm run ops:safe-restart

Jika app di server dijalankan dengan user deploy whatsapp-inbox, gunakan:

sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && git pull origin main && npm run ops:safe-restart'

Command di atas adalah jalur patch utama untuk update source di server.

D1.1. Patch manual di server langkah demi langkah

Gunakan ini jika ingin melihat proses satu per satu:

sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && git status'
sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && git pull origin main'
sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && npm ci'
sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && npm run build'
sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && npm run db:deploy'
sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && npm run ops:safe-restart'

Gunakan jalur manual ini jika:

  • ada perubahan dependency baru
  • ada migration baru
  • ingin memastikan step build berhasil sebelum restart

D1.2. Patch cepat tanpa perubahan dependency

Kalau hanya ubah source biasa dan package-lock.json tidak berubah:

sudo -u whatsapp-inbox -H bash -lc 'cd /var/www/whatsapp-inbox-platform && git pull origin main && npm run build && npm run ops:safe-restart'

D2. Verifikasi pasca deploy

cd /var/www/whatsapp-inbox-platform
npm run ops:readiness
npm run ops:session-check
npm run ops:healthcheck

D3. Verifikasi proses berjalan

pm2 list
sudo ss -ltnp | grep 3002

E. Checklist Pasca Login Issue

Jika masih kena loop ke login:

  • cek cookie wa_inbox_session di browser.
  • cek domain/cookie secure.
  • cek header:
    • X-Auth-Session
    • X-Auth-Session-Has-Cookie
    • X-Auth-Base-Url
  • cek logs:
pm2 logs whatsapp-inbox-platform --lines 200
  • cek ENV:
    • COOKIE_SECURE=true untuk HTTPS.
    • APP_URL harus https://web.zappcare.id.
    • SESSION_COOKIE_DOMAIN kalau lintas subdomain.

F. Jalur Emergency/Recovery

Jika app tidak start:

  • npm run ops:readiness
  • cek DB connect.
  • jalankan ulang migration jika schema mismatch.
  • run npm run ops:safe-restart.
  • jika perlu rollback, checkout commit sebelumnya lalu restart ulang.
git log --oneline -n 10
git checkout <commit_id_aman>
npm run ops:safe-restart

G. Reference Command Cepat

  • Health app: npm run ops:healthcheck
  • Session check: npm run ops:session-check
  • Ready check: npm run ops:readiness
  • Restart aman: npm run ops:safe-restart
  • View process: pm2 list
  • Tail logs: pm2 logs
  • Folder kerja lokal: /home/wira/work/whatsapp-inbox-platform
  • Folder deploy server: /var/www/whatsapp-inbox-platform