# Deploying entirely through the web (no SSH) — cPanel "Setup Node.js App"

This is the fully-web-based alternative to `deploy/WHM_DEPLOY.md` (which uses
SSH + PM2 + a hand-written Apache proxy). Every step here uses a cPanel/WHM
web UI: File Manager, MySQL Databases, Setup Node.js App, and Cron Jobs.

**Prerequisite**: your host's cPanel must have the "Setup Node.js App" icon
(CloudLinux's Node.js Selector). Most cPanel hosts from the last few years
have this. If you don't see it, ask your host to enable it, or use the
SSH/PM2 path instead.

## 1. Create the database (WHM/cPanel → MySQL Databases)

- **MySQL® Databases** → create a database (e.g. `tempmail`) → cPanel
  prefixes it automatically (`youruser_tempmail`)
- Create a database user + strong password → cPanel prefixes this too
  (`youruser_dbuser`)
- **Add User to Database** → grant **All Privileges**
- Write down the full prefixed names — you'll paste them into the install
  wizard in step 5.

## 2. Upload and extract the app (File Manager)

- **File Manager** → navigate to your home directory (one level *above*
  `public_html` — do not extract into `public_html` itself, or your source
  code becomes directly browsable, like the "Index of /tempmail-app" issue)
- Upload `tempmail-app.zip`
- Right-click it → **Extract**
- You should end up with a folder like `/home/youruser/tempmail-app`

## 3. Create the Node.js app (Setup Node.js App)

- **Setup Node.js App** → **Create Application**
- **Node.js version**: 20.x (pick the highest 20.x available)
- **Application mode**: Production
- **Application root**: `tempmail-app` (relative to your home directory)
- **Application URL**: the domain or subdomain you want this on
- **Application startup file**: `server.js` — this repo ships one specifically
  for this deployment path (Passenger needs a plain `http.Server`, not the
  `next` CLI directly)
- **Environment variables** — add exactly one:
  - `NODE_ENV` = `production`

  (Everything else — `DATABASE_URL`, `NEXTAUTH_SECRET`, etc. — is written to
  `.env` automatically by the install wizard in step 5, not set here.)
- Click **Create**

cPanel now shows you the app's detail page with a **Run NPM Install** button.

## 4. Run NPM Install (this also builds the app — no extra step)

Click **Run NPM Install**.

This repo's `package.json` has a `postinstall` hook that automatically:
1. Copies `.env.example` → `.env` (only if `.env` doesn't already exist)
2. Runs `prisma generate && next build`

So this one button click installs dependencies **and** produces the full
production build — you don't need a separate "build" step. Watch the output
panel; it should end without errors. This can take a couple of minutes.

> If this step errors out, it's almost always one of: (a) the account's
> outbound network access is restricted, blocking Prisma's one-time engine
> binary download, or (b) your host's Node Selector runs `npm install
> --ignore-scripts` and skips `postinstall` (uncommon, but some hosts do
> this for security). If you hit either, you'll need SSH for just this one
> step — run `cd ~/tempmail-app && npm run build` — then continue with the
> rest of this guide as normal.

## 5. Visit the domain and run the install wizard

Visit the domain/subdomain you set in step 3. You'll land on `/install`
automatically. Walk through it:

- **Database**: host `localhost`, port `3306`, and the prefixed database
  name/username/password from step 1 — "Test Connection" should succeed
- **Admin account**: your dashboard login — save it somewhere safe
- **Mail provider**: fill in now or skip (add to `.env` later via File Manager)
- **Install Now**

This runs `prisma db push` against your database (creating the tables),
creates your admin account, writes the rest of `.env`, and signals Passenger
to restart the app on its next request — which is exactly what the wizard's
own status check does a couple seconds later. No manual restart needed;
you'll land on `/login` automatically once it's picked up.

## 6. Set up the purge job (WHM/cPanel → Cron Jobs)

Passenger-managed apps aren't well-suited to running a second always-on
background process the way `workers/purge-worker.ts` does under PM2 — so for
this deployment path, use the HTTP-triggered purge route instead, on a real
web-configured cron job:

- **Cron Jobs** → **Add New Cron Job**
- **Common Settings**: Every 15 Minutes
- **Command**:
  ```
  curl -s -X POST https://yourdomain.com/api/cron/purge -H "Authorization: Bearer YOUR_CRON_SECRET"
  ```
  Get `YOUR_CRON_SECRET`'s real value from `.env` via File Manager → Edit
  (search for `CRON_SECRET`) after the install wizard has generated it.

## 7. Inbound mail webhook

If you skipped the "Mail Provider" step in the wizard, add these to `.env`
via File Manager → Edit, then use the Node.js app's **Restart** button
(on its detail page in Setup Node.js App) to apply:
- `INBOUND_WEBHOOK_SIGNING_KEY`
- `INBOUND_MX_HOST` / `INBOUND_MX_HOST_FALLBACK`

Point your inbound mail provider's webhook at `https://yourdomain.com/api/inbound-mail`.

## Redeploying after code changes

- Upload/extract the new files over the old ones (File Manager), keeping `.env`
- **Setup Node.js App** → open the app → **Run NPM Install** again (rebuilds)
- Click **Restart** on the app's detail page

## What's different from the SSH/PM2 path

| | This guide (web-only) | `WHM_DEPLOY.md` (SSH + PM2) |
|---|---|---|
| Process manager | Passenger (built into cPanel) | PM2 |
| Domain → app wiring | Automatic (Setup Node.js App) | Manual Apache reverse-proxy config |
| Restart after install wizard | Automatic (`tmp/restart.txt` signal) | Automatic (`pm2 restart`) |
| Purge job | WHM Cron Jobs → HTTP endpoint | Real `node-cron` worker process |
| Requires SSH | No (except the rare `postinstall` failure case above) | Yes |

Both are legitimate; pick whichever matches what your host actually gives you
access to. Don't mix them — e.g. don't set up both a PM2 process AND a cPanel
Node.js app pointed at the same folder, they'll fight over the port.