# Deploying to cPanel (Truehost or similar)

This follows Truehost's documented process for running Next.js on cPanel
(cPanel doesn't run Next.js natively, it needs a Node.js app wrapper):
https://truehost.com/support/knowledge-base/how-to-deploy-nextjs-on-cpanel/

The project already includes everything this requires, `server.js` (the
custom server cPanel's Node.js Selector needs) and the right `start` script
in `package.json`, so you can skip straight to the cPanel steps below.

**Check first:** in cPanel, under **Setup Node.js App**, confirm Node.js
**18.x or newer** is available. If your plan only offers older versions,
contact your host's support before continuing.

## Step 1, Build the app on your own computer

```bash
npm install
npm run build
```

This creates a `.next` folder with the production build. Do this step
locally (or in any environment with internet access), cPanel shared
hosting often can't run a full Next.js build itself.

## Step 2, Zip the project for upload

Include everything **except**:
- `node_modules` (this gets reinstalled on the server, including it just
  makes the upload huge and can cause the error described below)
- `.git` (if present)
- `.env.local` (never upload this, you'll enter these values directly in
  cPanel instead, see Step 4)

Everything else, including the `.next` folder from Step 1, should go in
the zip.

## Step 3, Create the Node.js App in cPanel

1. Log in to cPanel → **Software** → **Setup Node.js App** → **+ CREATE
   APPLICATION**.
2. Fill in:
   - **Node.js version:** 18.x or newer
   - **Application mode:** Production
   - **Application root:** a folder name, e.g. `shoppgadgets`
   - **Application URL:** `www.shoppgadgets.com` (or the domain/subdomain
     you're pointing here)
   - **Application startup file:** `server.js`
3. Click **CREATE**. cPanel will show a placeholder "It Works!" page at
   your domain, that's expected before you upload anything.

## Step 4, Add environment variables

Still on the Node.js App page, under **Environment Variables**, add the
same four values from `.env.example`:

| Name | Value |
|---|---|
| `NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY` | from Paystack Dashboard |
| `PAYSTACK_SECRET_KEY` | from Paystack Dashboard |
| `ADMIN_PASSWORD` | your own choice |
| `ADMIN_SESSION_SECRET` | a long random string |

Entering them here (rather than uploading a `.env.local` file) keeps your
secret keys out of the zip and file manager entirely.

## Step 5, Upload and extract

1. In cPanel, open **File Manager** and go to the **Application root**
   folder you set in Step 3 (e.g. `shoppgadgets`).
2. Click **Upload**, select the zip from Step 2.
3. Once uploaded, right-click it → **Extract**.

## Step 6, Install dependencies on the server

1. Go back to **Setup Node.js App**, find your app, and copy the command
   it shows for entering the app's virtual environment.
2. Open cPanel's **Terminal**, paste that command, then `cd` into your
   Application root if it doesn't do so automatically.
3. Run:
   ```bash
   npm install
   ```
   This installs production dependencies fresh on the server, this is why
   `node_modules` was excluded from the zip.

   **If you see an error about `node_modules` already existing / not
   being a separate directory:** it means `node_modules` was accidentally
   included in your zip. Delete the uploaded `node_modules` folder via File
   Manager and run `npm install` again.

## Step 7, Start it up

1. Back in **Setup Node.js App**, click **Restart** on your application.
2. Visit your domain, Shopp Gadgets should load.
3. Check that the **admin dashboard** works: go to `/admin`, sign in with
   the `ADMIN_PASSWORD` you set in Step 4, and confirm the dashboard loads.
4. Make sure the `data` folder (inside your Application root) is writable,
   it should be by default since it's owned by your cPanel user, but if
   admin edits don't save, check its permissions are `755` in File Manager.

## Step 8, SSL and the Paystack webhook

Checkout needs the site on **https://**, not http://, if you haven't
already, install SSL for the domain (cPanel's **AutoSSL** under **Security**
does this for free). Once SSL is live, go back to your Paystack Dashboard →
Settings → API Keys & Webhooks, and set the webhook URL to:

```
https://www.shoppgadgets.com/api/paystack/webhook
```

## Updating the site later

Whenever you make code changes: run `npm run build` locally again, re-zip
(same exclusions as Step 2), upload and extract over the old files in File
Manager, then click **Restart** in Setup Node.js App. `npm install` is only
needed again if you added a new dependency.

## Troubleshooting

If the app doesn't start, check the **stderr.log** file that cPanel's
Node.js Setup generates in your Application root, it will show the exact
error.