# Deploy LaunchPad LMS frontend on cPanel (CloudLinux Node.js Selector)

This is a **Next.js** app (not static HTML). Use cPanel **Setup Node.js App**.

## Critical CloudLinux rules

1. **Never upload a `node_modules` folder.** CloudLinux creates a **symlink** named `node_modules` that points at its virtualenv. A real folder/file with that name breaks install.
2. If you already uploaded `node_modules`, delete it on the server first:
   ```bash
   cd ~/dplmsfrontend.digitalpathshalanepal.com   # your Application root
   rm -rf node_modules
   ```
   Then use cPanel **Run NPM Install** (or the commands below) so the symlink is recreated.
3. Use **`next.config.mjs`** (not `.ts`) so the build does not need to transpile the config file.

## 1) Create the Node.js app in cPanel

1. Open **Software → Setup Node.js App → Create Application**.
2. Set:
   - **Node.js version:** **20.x** (project needs `>=20.9.0`)
   - **Application mode:** `Production`
   - **Application root:** e.g. `dplmsfrontend.digitalpathshalanepal.com`
   - **Application URL:** your domain / subdomain
   - **Application startup file:** `server.js`
3. Click **Create**.

cPanel sets `PORT` automatically. Do not hardcode it.

## 2) Upload the project (no node_modules)

Upload frontend sources into the Application root:

- `package.json`, `package-lock.json`
- `app/`, `components/`, `lib/`, `public/`, `scripts/`
- `next.config.mjs`, `server.js`, `app.js`, `middleware.ts`, `tsconfig.json`, etc.

**Do not** upload:

- `node_modules/`
- `.next/` (build on the server)
- local `.env` with secrets you do not want on the host (prefer cPanel env UI)

## 3) Environment variables (before build)

In the Node.js app → **Environment variables** (see `.env.cpanel.example`):

| Variable | Example for your host |
|----------|------------------------|
| `HOSTNAME` | `0.0.0.0` |
| `NEXT_PUBLIC_API_URL` | `https://your-api…/api` |
| `NEXT_PUBLIC_APP_URL` | `https://dplmsfrontend.digitalpathshalanepal.com` |
| `NEXT_PUBLIC_SAAS_PLATFORM_DOMAIN` | `digitalpathshalanepal.com` |
| `NEXT_PUBLIC_USE_WORKSPACE_SUBDOMAINS` | `false` |
| `GOOGLE_CLIENT_ID` | (optional) |

You can leave `NODE_ENV=production` (cPanel default). Build tools (`typescript`, Tailwind, etc.) are in **`dependencies`** so Production install still gets them.

**Critical:** any `NEXT_PUBLIC_*` change requires a **new build**.

Allow this frontend origin on the **backend** CORS / `FRONTEND_URL`.

## 4) Install + build (SSH / Terminal)

Enter the app virtualenv (exact path is shown in the Node.js app UI), then:

```bash
cd ~/dplmsfrontend.digitalpathshalanepal.com

# Fix CloudLinux symlink if a real folder was uploaded
rm -rf node_modules

# Activate venv (path from cPanel — adjust version folder if needed)
source ~/nodevenv/dplmsfrontend.digitalpathshalanepal.com/20/bin/activate

npm install

# Clears a partial Turbopack failure, then builds with webpack (low workers)
rm -rf .next
npm run build:cpanel
```

`build:cpanel` uses **`next build --webpack`** (not Turbopack) with 1 CPU worker, then copies static/public into standalone for `server.js`.

If TypeScript is still missing:

```bash
npm install --save-exact typescript@5.9.2
npm run build:cpanel
```

## 5) Restart

In **Setup Node.js App**, click **Restart**. Startup file: **`server.js`**.

## 6) Verify

```bash
curl -sS https://dplmsfrontend.digitalpathshalanepal.com/api/health
```

Expect `{ "ok": true, ... }`.

## Common issues

| Problem | Fix |
|---------|-----|
| CloudLinux “must not contain node_modules” | `rm -rf node_modules` in app root, then `npm install` via cPanel venv |
| Failed to transpile `next.config.ts` | Use `next.config.mjs` (already in repo); remove old `next.config.ts` if still on server |
| Failed to install TypeScript | `npm install typescript` after activate; or re-upload updated `package.json` where typescript is a dependency |
| `EAGAIN` / `ERR_WORKER_INIT_FAILED` | Do **not** run plain `npm run build`. Use `rm -rf .next && npm run build:cpanel` (webpack + 1 worker). Close other Node apps; ask host to raise LVE nproc if it still fails |
| CSS / pages missing after build | Run `npm run build:cpanel`, not only `next build` |
| Wrong API URL in browser | Rebuild after setting `NEXT_PUBLIC_*` |
| CORS errors | Add frontend URL to backend allowlist |

## Note on Docker / DigitalOcean

Docker still uses standalone `server.js` inside the image. Root `server.js` is for **cPanel** only.