# Deploy CediForge Academy on Namecheap (cPanel)

This app is **Next.js + Node.js**, not WordPress/PHP. Namecheap shared hosting can run it with **cPanel → Setup Node.js App**.

You need:

- A Namecheap plan that includes **Setup Node.js App** (usually **Stellar Business** / similar — not the cheapest Starter plan).
- **Node.js 22 or 24** in the version dropdown.
- A domain already pointed at the hosting.

Official Namecheap guide: [Deploy Next.js in cPanel](https://www.namecheap.com/support/knowledgebase/article.aspx/10686/29/how-to-deploy-reactjs-vitejs-react-native-and-nextjs-applications-in-cpanel/).

---

## 1. Build on this machine (do this first)

```bash
cd cediforge-academy
npm install
npm run build
```

Fix any build errors before uploading.

Create an upload zip (skips `node_modules`, `.git`, local sqlite):

```bash
npm run pack:namecheap
```

That writes `cediforge-namecheap.zip` in the parent folder.

---

## 2. Upload to cPanel

1. Log in to **cPanel**.
2. **File Manager** → go to your home directory (`/home/USERNAME/`).
3. Create a folder, e.g. `cediforge` (**do not** put the Node app inside `public_html` — Namecheap will not start Node from there).
4. Upload `cediforge-namecheap.zip` into `cediforge`.
5. Extract it so you see `server.js`, `package.json`, `.next`, `src`, `public`, `data` in that folder.

Database:

- This version uses the MySQL/MariaDB database in Namecheap cPanel. No local SQLite database is required.
- Namecheap shared hosting provides MariaDB/MySQL; the database host is normally `127.0.0.1`/`localhost` and port `3306`.

---

## 3. Create the Namecheap MySQL database

In cPanel go to **Databases → Database Wizard** (or Manage My Databases). Create:

- Database: `kwetswws_cediforge`
- User: `kwetswws_cediforge`
- Password: the password supplied for this deployment
- Assign the user to the database with **All Privileges**. Namecheap documents this workflow in its cPanel database guide.

The application will automatically create its required tables when it starts. You do **not** need to import a separate SQLite file.

Namecheap's shared hosting database server uses MariaDB/MySQL and local database connections use port `3306`; `127.0.0.1` is the standard local host value shown in Namecheap's documentation.

## 4. Create the Node.js application

**cPanel → Software → Setup Node.js App → Create application**

| Field | Value |
| --- | --- |
| Node.js version | **22.x or 24.x** |
| Application mode | **Production** |
| Application root | `cediforge` (the folder you uploaded to) |
| Application URL | your domain (or a subdomain) |
| Application startup file | **`server.js`** |

Add **environment variables** (same names as `.env.example`). For the Namecheap database, use these exact values:

| Variable | Example |
| --- | --- |
| `NODE_ENV` | `production` |
| `AUTH_SECRET` | a long random string (not the local default) |
| `NEXT_PUBLIC_SITE_URL` | `https://yourdomain.com` |
| `PAYSTACK_SECRET_KEY` | live `sk_live_…` |
| `NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY` | live `pk_live_…` |
| `XAI_API_KEY` | tutor key |
| `NEXT_PUBLIC_COACH_WHATSAPP` | `23324…` |
| `STAFF_PIN` | staff inbox pin |
| `SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` | mail |
| `MAIL_FROM` | `CediForge Academy <hello@yourdomain.com>` |
| `ABANDONED_MINUTES` | `10` |
| `CRON_SECRET` | random string for the reminder cron |
| `DB_HOST` | `127.0.0.1` |
| `DB_PORT` | `3306` |
| `DB_DATABASE` | `kwetswws_cediforge` |
| `DB_USERNAME` | `kwetswws_cediforge` |
| `DB_PASSWORD` | the database password supplied for this deployment |

Click **Create**.

**Application URL must be the domain root** (`cediforge.academy` with path `/`).  
If it is `/cediforge` or the app root is `public_html`, the site will show a folder listing.

Then **do not use the cPanel “NPM Install” button**. CloudLinux often crashes with:

`AttributeError: 'NoneType' object has no attribute 'lower'`

That is a Namecheap/CloudLinux bug. It probes the website for a MIME type, gets nothing (folder listing or the app not running), and dies. Install packages from **Terminal** instead.

### Install packages from cPanel Terminal (required)

**cPanel → Advanced → Terminal** (or SSH), then:

```bash
# 1. See the venv CloudLinux created (folder name = your application root)
ls ~/nodevenv

# 2. Activate it (change 22 → 24 if you picked Node 24)
source ~/nodevenv/cediforge/22/bin/activate

# 3. Install into the app
cd ~/cediforge
npm install --omit=dev
```

If `source` fails, list `~/nodevenv/cediforge/` and use the version folder that exists (`20`, `22`, `24`).

Then go back to **Setup Node.js App** → **Start App**. Do **not** click NPM Install again.

Open `https://cediforge.academy`. You should see the academy, not a file list.

If the page is blank, check **cPanel → Errors** and the Node.js **stderr** log.

---

## If cediforge.academy “opens the folder”

Apache is serving files. The Node app is not attached to `/`.

### Fix A — files are inside `public_html`

You will see `server.js`, `src`, `package.json`, `.next` when you visit the site.

1. **File Manager** → create `/home/USERNAME/cediforge` (home directory, **beside** `public_html`, not inside it).
2. Move **all** app files from `public_html` into `cediforge`.
3. Leave `public_html` almost empty except `.htaccess`.
4. In **Setup Node.js App**, set:
   - Application root: `cediforge`
   - Application URL: `cediforge.academy` **/**
   - Startup file: `server.js`
5. Run **NPM Install**, **Start App**.

### Fix B — domain document root points at the app folder

**cPanel → Domains** → `cediforge.academy` → **document root** must be `public_html`, **not** `cediforge`.

### Fix C — Passenger `.htaccess` missing in `public_html`

1. File Manager → `public_html` → **Settings → Show Hidden Files**.
2. Create/edit `.htaccess`.
3. Paste the contents of `deploy/public_html.htaccess`.
4. Change `USERNAME` to your cPanel user (see the home path in File Manager).
5. If you picked Node **24**, change `alt-nodejs22` to `alt-nodejs24`.
6. Restart the Node app.

`public_html` should **not** list the Next.js project. It should only proxy to Node.

---

## 5. SSL and HTTPS

**cPanel → SSL/TLS Status** (or AutoSSL) → issue a certificate for the domain.

`.htaccess` in the project forces HTTPS once SSL is on. If Passenger already wrote its own `.htaccess`, merge the HTTPS rewrite; do not delete Passenger lines.

---

## 6. Abandoned-order emails (every 5 minutes)

**cPanel → Cron Jobs → Add**

```
*/5 * * * * curl -s -H "Authorization: Bearer YOUR_CRON_SECRET" https://yourdomain.com/api/cron/abandoned >/dev/null 2>&1
```

Replace `YOUR_CRON_SECRET` with the same value as `CRON_SECRET`.

---

## 7. Paystack webhook

In the Paystack dashboard, set the webhook URL to:

`https://yourdomain.com/api/paystack/webhook`

Callback URL:

`https://yourdomain.com/pay/callback`

Use **live** keys once the domain is public.

---

## 8. Mail (Namecheap)

You can send abandoned-order mail through Namecheap email:

- Create `hello@yourdomain.com` in **cPanel → Email Accounts**.
- SMTP host is usually `mail.yourdomain.com`, port `465` (SSL) or `587` (TLS).
- Put those values in the Node.js app environment variables, then **Restart**.

---

## 9. After each update

On your computer:

```bash
npm run build
npm run pack:namecheap
```

Upload/extract the updated project, then run `npm install --omit=dev` in the Node.js application environment. Because the database is MySQL/MariaDB, user data remains in Namecheap SQL and is not tied to the uploaded files. Restart the Node.js app after changes.

---

## Common issues

| Problem | Fix |
| --- | --- |
| `AttributeError: ... 'lower'` on NPM Install | Ignore that button. Use **cPanel Terminal** + `source ~/nodevenv/.../activate` then `npm install --omit=dev`. |
| App not starting from `public_html` | Move files to a folder like `cediforge` and set that as Application root. |
| 503 / Passenger error | Startup file must be exactly `server.js`. Restart after npm install. |
| Database connection error | Confirm the five `DB_*` variables in cPanel and that the database user is assigned **All Privileges** to `kwetswws_cediforge`. |
| Paystack test on live site | Switch to `sk_live_` / `pk_live_` and HTTPS URLs. |
| Emails not sending | Set SMTP vars; Namecheap often wants port **465** + `SMTP_USER` = full email address. |

---

## First admin login (after first start)

If the database is new on the server:

- `admin@cediforge.gh` / `Demo1234!`

Change that password (or create a new admin and disable the seed account) as soon as the site is live.