# Installing North West SEO on cPanel

This guide assumes only cPanel access — no server administration needed.
Allow 30–45 minutes. Follow the steps in order.

**What you need before starting**
- cPanel with **Setup Node.js App** (you confirmed you have it)
- The file `northwest-seo-cpanel-v0.1.0.zip`
- The domain `northwestcar.group` managed in this cPanel account

---

## Step 1 — Create the subdomain

1. cPanel → **Domains** → **Create a New Domain** (or **Subdomains** on older cPanel).
2. Domain: `seo.northwestcar.group`.
3. Document root: accept the suggestion (e.g. `seo.northwestcar.group`). The
   Node.js app will take over this location later — the folder just needs to exist.

## Step 2 — Create the MySQL database

1. cPanel → **MySQL Database Wizard**.
2. Database name: `seo` (cPanel will prefix it, e.g. `youruser_seo`).
3. Create a user, e.g. `seouser` (becomes `youruser_seouser`) with a **strong
   password** — write all three values down.
4. On the privileges screen tick **ALL PRIVILEGES** → Next Step.

## Step 3 — Import the database structure

1. cPanel → **phpMyAdmin**.
2. Click your new database (`youruser_seo`) in the left sidebar.
3. Click the **Import** tab → **Choose File** → select `database-init.sql`
   (it's inside the zip, in the `cpanel` folder — extract it first, or upload
   the zip in Step 4 and come back).
4. Click **Import** at the bottom. You should see "Import has been
   successfully finished" and a long list of tables in the sidebar.

## Step 4 — Upload the application

1. cPanel → **File Manager** → go to your **home directory** (the folder that
   contains `public_html` — do NOT go inside public_html).
2. Click **+ Folder** → name it `northwest-seo`.
3. Open that folder → **Upload** → select `northwest-seo-cpanel-v0.1.0.zip`.
4. Back in File Manager, right-click the zip → **Extract** → extract into
   `/home/YOURUSER/northwest-seo`.
5. Check: the folder should now contain `server.js`, `package.json`, a
   `.next` folder, `src`, `prisma`, etc. (If everything landed inside an
   extra nested folder, move the contents up one level.)
6. You can delete the zip after extracting.

## Step 5 — Configure the environment

1. In File Manager inside `northwest-seo`, find `.env.cpanel.example`.
2. Right-click → **Copy** → name the copy `.env`.
   *(If you can't see dot-files: File Manager → Settings → tick "Show Hidden
   Files".)*
3. Right-click `.env` → **Edit** and fill in:
   - `DATABASE_URL` — your database name, user and password from Step 2:
     `mysql://youruser_seouser:PASSWORD@localhost:3306/youruser_seo`
   - `CREDENTIAL_ENCRYPTION_KEY` — 64 random hex characters (Step 7 shows how
     to generate one; you can leave the placeholder until then, the app will
     tell you if it's invalid only when integrations are used).
4. Save.

## Step 6 — Create the Node.js application

1. cPanel → **Setup Node.js App** → **Create Application**.
2. Settings:
   - **Node.js version**: 22 if offered, otherwise 20 (must be 20.9+).
   - **Application mode**: Production.
   - **Application root**: `northwest-seo`
   - **Application URL**: `seo.northwestcar.group`
   - **Application startup file**: `server.js`
3. Click **Create**.
4. On the app's page click **Run NPM Install** and wait for it to finish
   (several minutes — it also prepares the database client for MySQL).
5. Click **Restart**.

## Step 7 — Generate the encryption key (recommended now)

1. At the top of the Node.js App page, cPanel shows a command like
   `source /home/YOURUSER/nodevenv/northwest-seo/22/bin/activate && cd /home/YOURUSER/northwest-seo`
   — copy it.
2. cPanel → **Terminal** → paste that command and press Enter.
3. Run:
   ```
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   ```
4. Copy the 64-character output into `CREDENTIAL_ENCRYPTION_KEY` in `.env`
   (File Manager → Edit), save, then **Restart** the app in Setup Node.js App.

## Step 8 — Set up the crawl cron job

Crawls are processed by a scheduled task (no Redis on shared hosting).

1. cPanel → **Cron Jobs**.
2. Common Settings: **Once Per Five Minutes** (`*/5 * * * *`).
3. Command — one line, replacing `YOURUSER` and `22` with your username and
   the Node version from Step 6:
   ```
   source /home/YOURUSER/nodevenv/northwest-seo/22/bin/activate && cd /home/YOURUSER/northwest-seo && npm run jobs:once >> /home/YOURUSER/northwest-seo/jobs.log 2>&1
   ```
4. Add the cron job.

Crawls you start in the dashboard will show "queued" and begin within
5 minutes when the cron fires.

## Step 9 — SSL (https)

1. cPanel → **SSL/TLS Status**.
2. Find `seo.northwestcar.group`, tick it, click **Run AutoSSL**.
3. Wait until it shows a green padlock. (If the domain is behind Cloudflare,
   use DNS-only mode until this succeeds, then you may enable the proxy with
   SSL mode **Full (Strict)** — never "Flexible".)

## Step 10 — Verify the installation

1. Visit `https://seo.northwestcar.group/api/health` — expect
   `{"status":"ok", ...}` with `"database":"ok"` and `"queue":"ok"`.
2. Visit `https://seo.northwestcar.group` — the homepage loads.
3. **Register** an account, add your website, click **Start crawl**, wait up
   to 5 minutes, refresh — pages and issues appear.
4. Email note: until `SMTP_URL` is set in `.env`, verification/reset emails
   are written to the application log (`stderr.log` in the app folder /
   the Node.js App page's log) instead of being sent. Everything else works
   without email.

---

## Troubleshooting

| Problem | Fix |
| --- | --- |
| Visiting the site shows a Passenger error page | Setup Node.js App → check the app is **started**; open `stderr.log` in the app folder for the real error |
| Health shows `"database":"error"` | `DATABASE_URL` in `.env` is wrong — recheck user/password/dbname (all include your cPanel prefix); Restart the app after editing |
| "Run NPM Install" fails or hangs | Run it again (shared hosts sometimes kill long installs); or use the Terminal (Step 7 command) and run `npm install` there |
| Crawls stay "queued" forever | The cron job isn't running — recheck the Step 8 command paths, and look at `jobs.log` in the app folder |
| Crawl marked failed: "Crawl runner was interrupted" | The host killed a long process; click Start crawl again — consider lowering the page limit on the website's settings via the API, or crawling at quieter times |
| Site works on http but not https | Run AutoSSL (Step 9) and retry after a few minutes |
| You changed `.env` but nothing happened | Always **Restart** the app in Setup Node.js App after editing `.env` |

## Updating to a new version

1. Download the new `northwest-seo-cpanel-vX.Y.Z.zip`.
2. In File Manager, rename the old `northwest-seo` folder to
   `northwest-seo-old` (keep it until the new version works).
3. Repeat Steps 4–6 (upload/extract, copy your existing `.env` across from
   the old folder, Run NPM Install, Restart).
4. Apply any database update SQL shipped with the release via phpMyAdmin.
5. Delete `northwest-seo-old` once everything works.