# Deploying Shiprex Lite on cPanel (Node.js + Passenger)

This deploys the **single Node app** that serves both the JSON API and the built React dashboard.

## Prerequisites
- cPanel with **Setup Node.js App** (Phusion Passenger) and Node 20–22 available.
- A MySQL database + user created in cPanel (**MySQL® Databases**). cPanel prefixes names, e.g.
  `cpuser_shiprexlite` / `cpuser_shipuser`. Grant the user ALL PRIVILEGES on the DB.

## 1. Get the code onto the server
Either:
- **Git** (cPanel → *Git Version Control* → Create, clone your repo), or
- Upload a zip to a folder under your home dir, e.g. `~/shiprex-lite`, and extract.

Do **not** upload `node_modules` or `client/dist` — they are built on the server.

## 2. Create the Node.js application
cPanel → **Setup Node.js App** → **Create Application**:
- **Node.js version**: 20.x or 22.x
- **Application mode**: Production
- **Application root**: `shiprex-lite` (the folder containing `app.js`)
- **Application URL**: your domain/subdomain
- **Application startup file**: `app.js`

Click **Create**. cPanel creates a virtualenv and shows an **"Enter to the virtual environment"**
command — you'll use that for the next steps over SSH (or use the UI's "Run NPM Install" + a Terminal).

## 3. Environment variables
In the Node.js App screen, add these **Environment variables** (do NOT commit a real `.env`):

```
NODE_ENV=production
DB_HOST=localhost
DB_PORT=3306
DB_NAME=cpuser_shiprexlite
DB_USER=cpuser_shipuser
DB_PASSWORD=********
JWT_SECRET=<a long random string>
JWT_EXPIRES_IN=7d
ROOT_ADMIN_EMAIL=admin@yourdomain.com
ROOT_ADMIN_PASSWORD=<strong password>
ROOT_ADMIN_NAME=Shiprex Root
APP_URL=https://yourdomain.com
CORS_ORIGINS=
```

> Single-app deploy = client and API share an origin, so leave `CORS_ORIGINS` empty.

## 4. Install, build, migrate, seed
Enter the app's virtualenv (the command cPanel gave you), then from the app root:

```bash
# install all workspaces, build the React client, run migrations + seed in one go
npm run cpanel:install

# (equivalent to:)
# npm install
# npm run build:client     # produces client/dist (served by Express)
# npm run migrate          # creates tables
# npm run seed             # creates the root super-admin from env vars
```

If `npm` isn't on PATH in SSH, use the full path cPanel prints, or the **Run NPM Install** /
**Run JS Script** buttons in the Node.js App UI (add a `cpanel:install` script run there).

## 5. Start / restart
Click **Restart** in the Node.js App screen (Passenger picks up `app.js`). Visit your domain:
- `/`            → React dashboard (login)
- `/api/health`  → `{ "success": true, "data": { "status": "ok" } }`

## 6. Routing notes (Passenger)
- Passenger sets `PORT`; `app.js` listens on it. Don't hardcode a port.
- The Express SPA fallback returns `index.html` for non-`/api` GET routes, so deep links
  (`/orders`, `/admin`) work on refresh. No custom `.htaccess` rewrites are needed when Passenger
  fronts the Node app.
- If you serve the API on a **subdomain** instead, set `CORS_ORIGINS` to the dashboard origin.

## 7. Updating a deployed instance
```bash
git pull                       # or re-upload changed files
npm install                    # if deps changed
npm run build:client           # if client changed
npm run migrate                # if new migrations
# then Restart in the Node.js App UI
```

## Troubleshooting
- **502 / app won't boot**: check the Passenger log (Node.js App UI → *stderr*), usually a missing
  env var or DB auth failure.
- **DB connection refused**: on cPanel use `DB_HOST=localhost`; confirm the cPanel DB user is added
  to the database with privileges.
- **Blank page, API works**: `client/dist` missing — run `npm run build:client` and restart.
- **`mysql2` / native build issues**: `mysql2` is pure-JS, so this is rare; ensure Node version
  matches and re-run `npm install`.