# Deploying to cPanel (Node.js App)

## 0. Database setup (do this first, before anything else)

1. In cPanel -> **MySQL Databases**, create a new database and a new database user, and add that
   user to the database with **All Privileges**. Note the three values cPanel generates (it
   prefixes them with your cPanel username, e.g. `youruser_zmbshop`, `youruser_zmbuser`).
2. Upload `api/` and `database/` (minus `auto-setup.php` — see step 2 below) to the PHP hosting
   location (same domain's `public_html`, or wherever Option A/B below puts the PHP side).
3. Create `api/config.local.php` (do **not** edit `api/config.php` directly — it holds this dev
   machine's local values as defaults, and `config.local.php` is the designed override point) with:
   ```php
   <?php
   return [
       'db_host' => 'localhost',
       'db_name' => 'youruser_zmbshop',
       'db_user' => 'youruser_zmbuser',
       'db_pass' => 'the real password you set in step 1',
       'admin_email' => 'your-real-admin-email@example.com',
       'admin_password' => 'pick a strong password here, not the dev default',
   ];
   ```
4. Visit `https://yourdomain.com/database/setup.php` once in a browser — it creates every table
   and seeds the starter catalog. **Delete `database/setup.php` from the server right after** (it
   has no login check — leaving it reachable lets anyone re-run it).
5. Log into `/admin` with the `admin_email`/`admin_password` you set in step 3, and change the
   password from there as your first action.

This app runs as a real Node.js process — cPanel's **"Setup Node.js App"** feature (Phusion
Passenger) supports that, so no static-export compromises are needed; every feature built during
the migration (Server Components, ISR, dynamic sitemap/robots, generateMetadata) works as-is.

## 1. Decide the domain layout first

The PHP backend (`api/`, `uploads/`) currently lives on the same domain as the storefront. On
cPanel there are two ways to keep that working — **pick one before proceeding**:

- **Option A — same domain, Node app at a sub-path or the PHP files at a sub-path.** cPanel's
  Node.js Selector auto-generates a `.htaccess` with `PassengerAppRoot`/Passenger rules that route
  matching requests to the Node app. You will need to add exclusion rules for `/api/` and
  `/uploads/` in that generated `.htaccess` so those keep hitting PHP directly — this is the exact
  same problem this local dev setup just solved (see the root project's `.htaccess` and the
  `ProxyPass ... !` exclusions in `httpd.conf` for the pattern to mirror). (Google/Bing/Pinterest
  site-verification files are a separate concern and need **no** `.htaccess` rule either way —
  `app/[filename]/route.ts` serves those directly from inside the Node app now.)
- **Option B — separate subdomain for the API** (e.g. `api.yourdomain.com` pointing at the
  existing `api/` folder), and the Node app owns the main domain entirely with no path conflicts
  to manage. Simpler to get right; requires updating `API_BASE_URL`/`PHP_BACKEND_URL` below to the
  new subdomain and re-pointing any hardcoded `/api/...` paths that assume same-origin (the
  `NEXT_PUBLIC_BASE_PATH` mechanism already used for local dev handles a path *prefix*, not a
  different *origin* — if you go this route, `lib/api-client.ts`'s `withBasePath()` would need to
  become a full origin prefix instead; ask for this change if you pick Option B).

## 2. What to upload

Upload everything in `nextjs-migration/` **except**:
- `node_modules/` (reinstall on the server instead — different OS/architecture than this dev machine)
- `.next/` (rebuild on the server — see step 4)
- `.env.local` (this has local dev values; create a fresh `.env` or set env vars via cPanel's UI instead — see step 3)
- `*.log` files and `tsconfig.tsbuildinfo` (local dev artifacts, harmless but pointless to upload)

Separately, for the PHP side (project root, not `nextjs-migration/`) — upload `api/`, `uploads/`,
`database/schema.sql`, `database/seed-catalog.sql`, `database/policy_settings.sql`, and
`database/setup.php`, but **do not upload `database/auto-setup.php`** — it brute-force-tries a
list of common local-dev MySQL root passwords and has no place anywhere near a real server. Also
replace `api/config.php`'s hardcoded local dev DB credentials — see step 0 below.

## 3. Environment variables

In cPanel's Node.js App settings, add these (do **not** set `NEXT_BASE_PATH` /
`NEXT_PUBLIC_BASE_PATH` at all — leave them unset so the app serves from the domain root):

```
API_BASE_URL=https://yourdomain.com/api          (or https://api.yourdomain.com/api if Option B)
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
PHP_BACKEND_URL=https://yourdomain.com            (or https://api.yourdomain.com if Option B)
```

## 4. Install, build, start

Via cPanel's Node.js App page (it gives you an "Enter to the virtual environment" terminal command) or SSH:

```
npm install
npm run build
```

Set the **Application startup file** to `server.js` (already included — Passenger needs a plain
HTTP server it can hand `PORT` to; `server.js` boots Next.js in production mode on that port).
Then use cPanel's **Restart** button to launch it.

## 5. After every future code change

```
git pull   (or re-upload changed files)
npm install    (only if package.json changed)
npm run build
```
Then hit **Restart** in cPanel's Node.js App page — Passenger won't pick up a new build until restarted.

## 6. Local dev vs. this deployment — what's different

| | Local (this dev machine) | cPanel |
|---|---|---|
| Base path | `/zahid` (`NEXT_BASE_PATH` set) | none — app owns the domain root |
| Process manager | manual `npm start` in background | Passenger (auto-restarts, managed by cPanel) |
| Reverse proxy | Apache `ProxyPass` in `httpd.conf` | cPanel's auto-generated Passenger `.htaccess` |

Nothing in the application code itself differs between the two — only these three pieces of
hosting glue, all environment/config-driven.