This commit is contained in:
320
docs/setup-guide.md
Normal file
320
docs/setup-guide.md
Normal file
@ -0,0 +1,320 @@
|
||||
<!--
|
||||
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`
|
||||
Reference in New Issue
Block a user