Panduan Deploy Toko Online (WHM + CloudLinux)

Gambaran Arsitektur Production

Di lokal Anda menjalankan 2 proses terpisah (:5173 + :5000). Di production, pola yang paling umum di CloudLinux:

Browser (Pengunjung)
  → HTTPS domain.com        → Apache/LiteSpeed (public_html) = Frontend build
  → HTTPS api.domain.com   → Node.js App (Express API)
                                    → MySQL cPanel
                                    → uploads/images
Frontend (public_html) → fetch API → Node.js

Komponen	Di lokal	Di production
Frontend	`npm run dev` (Vite)	Build statis → folder `public_html`
Backend	`npm run dev` (nodemon)	Node.js Selector cPanel (Passenger)
Database	MySQL XAMPP	MySQL cPanel
Upload gambar	`backend/uploads/`	Folder yang sama, harus writable

Prasyarat di WHM / CloudLinux

Pastikan hosting mendukung:

Node.js Selector (CloudLinux) — cPanel → Setup Node.js App
MySQL/MariaDB — cPanel → MySQL Databases
SSL — AutoSSL / Let's Encrypt (WHM atau cPanel)
Node.js 18 atau 20 LTS (hindari versi terlalu lama)

Penting: Paket bcrypt di backend adalah modul native. Jangan upload node_modules dari Windows. Install dependency di server lewat terminal cPanel atau tombol Run NPM Install di Node.js App.

Langkah 1 — Database MySQL

cPanel → MySQL Databases
Buat database, mis. user_toko_online
Buat user MySQL + password kuat → beri All Privileges
phpMyAdmin → Import file SQL:
- backend/database/schema-latihan-toko.sql (struktur tabel)
- backend/database/seed-admin.sql (user admin awal)
Catat: DB_HOST (biasanya localhost), DB_USER, DB_PASS, DB_NAME

Langkah 2 — Backend (Express API)

Opsi A — Domain API (disarankan): api.domainanda.com

cPanel → Subdomains → buat api
cPanel → Setup Node.js App → Create Application
- Node.js version: 18/20
- Application root: mis. api atau nodejs/toko-api
- Application URL: api.domainanda.com
- Application startup file: server.js
- Application mode: Production
Upload isi folder backend/ ke application root (tanpa node_modules)
Terminal cPanel:

cd ~/api   # sesuaikan path application root
npm install --production

Set Environment Variables di panel Node.js App:

NODE_ENV=production
DB_HOST=localhost
DB_USER=user_dbuser
DB_PASS=password_kuat
DB_NAME=user_toko_online
JWT_SECRET=string_acak_panjang_minimal_32_karakter
FRONTEND_URL=https://domainanda.com

Klik Restart aplikasi Node.js
Tes: buka https://api.domainanda.com/ → harus muncul teks "API jalan"

Permission folder upload

chmod 755 ~/api/uploads
chmod 755 ~/api/uploads/images

Pastikan user cPanel bisa menulis ke folder itu (upload gambar produk/profil).

Opsi B — Satu domain (reverse proxy)

Frontend di domainanda.com, API di path yang sama lewat proxy Apache:

/api/* → Node.js
/uploads/* → Node.js

Butuh konfigurasi .htaccess atau include Apache di cPanel. Lebih rumit; subdomain API lebih mudah untuk latihan SMK.

Langkah 3 — Frontend (React build)

3.1 Buat env production

Buat file frontend/.env.production:

VITE_API_URL=https://api.domainanda.com

Proyek memakai variabel ini di frontend/src/api/http.js dan frontend/src/utils/media.js.

3.2 Build di komputer (atau di server jika ada Node)

cd frontend
npm install
npm run build

Hasil ada di folder frontend/dist/.

3.3 Upload ke public_html

Upload isi folder dist/ ke public_html/ (bukan folder dist itu sendiri).

3.4 SPA routing (React Router)

Karena memakai BrowserRouter, halaman seperti /admin/produk harus fallback ke index.html. Buat public_html/.htaccess:

RewriteEngine On

# Jangan arahkan /api dan /uploads ke index.html
RewriteCond %{REQUEST_URI} !^/api
RewriteCond %{REQUEST_URI} !^/uploads
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

Langkah 4 — Penyesuaian Keamanan (Production)

Backend — batasi CORS

Saat ini server.js memakai app.use(cors()) (semua origin). Untuk production, ganti menjadi:

app.use(cors({
  origin: process.env.FRONTEND_URL || 'https://domainanda.com',
  credentials: true,
}));

JWT & admin default

Ganti JWT_SECRET — jangan pakai rahasia_super_aman dari .env latihan
Setelah deploy, ubah password admin lewat database atau fitur profil
Jangan commit .env ke Git

HTTPS

Pastikan frontend dan API sama-sama HTTPS. Mixed content (HTTP API dari HTTPS web) akan diblokir browser.

Checklist Setelah Deploy

Cek	Cara
API hidup	`https://api.domainanda.com/`
Login admin	`/login` → masuk `/admin`
Gambar produk	Upload + tampil di halaman produk
Route SPA	Refresh di `/admin/produk` tidak 404
Database	CRUD produk/pembelian jalan
Error backend	cPanel → Node.js App → log / terminal

Kesalahan Umum di WHM + CloudLinux

Upload node_modules dari Windows → bcrypt error → solusi: npm install di server
VITE_API_URL masih localhost:5000 → build ulang frontend setelah ubah .env.production
Lupa restart Node.js App setelah ubah .env
Folder uploads tidak writable → upload gambar gagal
Import SQL gagal → nama DB/user di .env tidak cocok dengan cPanel (biasanya prefix cpaneluser_)
404 saat refresh halaman → belum ada .htaccess SPA
CORS error → FRONTEND_URL tidak cocok dengan domain frontend

Ringkasan Alur Deploy

1. Buat DB + import SQL di cPanel
2. Deploy backend → Node.js App → npm install di server → set env → restart
3. Build frontend dengan VITE_API_URL=https://api.domainanda.com
4. Upload dist/ ke public_html + .htaccess
5. Aktifkan SSL untuk domain + subdomain API
6. Tes login, CRUD, upload gambar