> **Using cPanel (shared hosting or VPS with cPanel)?** Follow `OXO-Deployment-Guide.pdf` — no command line needed. This file is for plain Linux VPS servers without cPanel.

# OXO — Deployment guide

## Architecture
```
 Browser ──HTTPS──▶ Nginx (TLS, gzip, rate limit) ──▶ Next.js 15 (Node ≥22.5, one process, port 3000)
                                                         ├─ Public site  /, /products, /pricing, /checkout
                                                         ├─ Customer portal /portal  (orders, licences, chat)
                                                         ├─ Mother dashboard /dashboard  (admin)
                                                         └─ API /api/*  (auth, pay, chat, ingest, dashboard)
                                                                │
                              SQLite file  $DATA_DIR/oxo.db  (WAL)  +  $DATA_DIR/uploads  +  $DATA_DIR/backups
 External:  bKash / Nagad (redirect + callback)   Bank/PSP ──▶ POST /api/pay/qr/webhook (HMAC)   SMTP   SMS API
```
One Node process + one persistent disk. **Not for Vercel/Netlify/serverless** (the database is a file on disk). Use a VPS, Docker host, or a cPanel host with Node 22 support.

## Requirements
- Linux VPS (1 vCPU / 1 GB RAM is enough), a domain pointing to it, Node.js **22.5+**.

## Option A — VPS with PM2 + Nginx (recommended)
1. Upload and unzip: `scp oxo-platform.zip user@server:~` → `unzip oxo-platform.zip -d /var/www && cd /var/www/oxo-platform`
2. Install Node 22: `curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs nginx`
3. Create `.env` from `.env.example`:
   ```
   OXO_SECRET=<run: openssl rand -hex 32>      # never change after launch (encrypts gateway secrets)
   APP_URL=https://yourdomain.com               # exact public URL (used for payment callbacks)
   ADMIN_EMAIL=you@yourdomain.com
   ADMIN_PASSWORD=<strong password, 12+ chars>  # creates the owner on first start
   DATA_DIR=/var/lib/oxo                        # outside the app folder
   SEED_DEMO=false                                  # no sample data in production
   ```
   `sudo mkdir -p /var/lib/oxo && sudo chown $USER /var/lib/oxo`
4. Build & run: `npm ci && npm run build && sudo npm i -g pm2 && pm2 start npm --name oxo -- start && pm2 save && pm2 startup`
5. Nginx site (`/etc/nginx/sites-available/oxo`):
   ```
   server { server_name yourdomain.com; client_max_body_size 5m;
     location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } }
   ```
   `sudo ln -s /etc/nginx/sites-available/oxo /etc/nginx/sites-enabled && sudo nginx -t && sudo systemctl reload nginx`
6. HTTPS: `sudo apt install certbot python3-certbot-nginx && sudo certbot --nginx -d yourdomain.com`
7. Open `https://yourdomain.com/login` → sign in as the owner → **Company & security** → enable 2FA.

## Option B — Docker
`docker build -t oxo .` then `docker run -d --name oxo -p 3000:3000 -v oxo-data:/data --env-file .env oxo` (put Nginx/Caddy in front for HTTPS).

## Option C — cPanel / Node.js app manager
Choose Node 22, app root = unzipped folder, startup file via `npm start`, set the env vars above, run `npm ci && npm run build` in the terminal, set DATA_DIR to a folder outside `public_html`.

## After going live (in the dashboard)
1. **Company & security** → company details, logo, invoice terms; remove demo data.
2. **Orders & payments → Payment methods**:
   - **bKash (tokenized):** app key/secret/username/password, whitelist the shown callback URL, enable tokenized.
   - **Nagad:** merchant ID/number, PG public key, your private key, whitelist the callback URL.
   - **Bangla QR (tokenized):** set merchant ID/account, city, MCC and a **webhook signing secret**. Give your bank/PSP the webhook URL `https://yourdomain.com/api/pay/qr/webhook`. They POST JSON `{token, trx_id, amount, sender}` with header `x-signature: HMAC-SHA256(rawBody, secret)` (hex). Exact amount → auto-activation; wrong amount → admin review. Without a PSP webhook, customers can still submit the TxnID for manual approval.
   - **Manual:** add your bKash/Nagad/Rocket/bank numbers.
3. **Email server / SMS gateway** → enter SMTP and SMS API details, send a test.
4. **Printers & POS** → Chrome/Edge over HTTPS (Web Serial/USB/Bluetooth need a secure context).
5. **Connected projects** → add each site, paste the one-line `track.js` snippet into it.

## Backups & updates
- Dashboard → **Database & backup** → Create backup (keep a copy off-server) or cron: `sqlite3 /var/lib/oxo/oxo.db ".backup '/backup/oxo-$(date +%F).db'"`.
- Update: upload new zip over the folder (keep `.env` and DATA_DIR), `npm ci && npm run build && pm2 restart oxo`.

## Security checklist
HTTPS only · strong owner password + 2FA · `OXO_SECRET` kept private and backed up · firewall: open 80/443 only · DATA_DIR not web-accessible · `SEED_DEMO=false` · regular off-server backups.