whatsapp-inbox-platform/docs/setup-guide.md

<!--
  Setup & Deployment Guide
  Scope: Local and Production
-->

# 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

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

### B2. Siapkan `.env`

```bash
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

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

### B4. Jalankan aplikasi

```bash
npm run dev
```

Untuk build check:

```bash
npm run build
```

## C. Setup Server (Dari Kosong)

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

```bash
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:

```bash
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

```bash
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

```sql
-- 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

```bash
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):

```nginx
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:

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

Reload nginx:

```bash
sudo nginx -t && sudo systemctl reload nginx
```

## D. Deployment Routine Setelah Update

### D0. Alur source code ke Git

Kerjakan perubahan di folder lokal:

```bash
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:

```bash
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:

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

### D1. Pull dan jalankan restart aman

```bash
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:

```bash
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:

```bash
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:

```bash
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

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

### D3. Verifikasi proses berjalan

```bash
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:

```bash
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.

```bash
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`