# Installing BotGuard on Namecheap Shared Hosting (cPanel)

Namecheap shared hosting uses **cPanel + LiteSpeed**, which reads the app's `.htaccess` natively. Best of
all: **BotGuard has no runtime Composer dependencies** (only PHP extensions), so you do **not** need SSH or
Composer on the server — the app ships a fallback autoloader.

> You will deploy the platform to a **subdomain** whose document root points at the app's `public/` folder.
> This keeps `.env`, code and storage out of the web root — the secure, recommended layout.

---

## Stellar Business quick-path (you have SSH)

Stellar Business includes **SSH access** and **unlimited databases**, so you can skip File-Manager zips and
run migrations from the command line. Connect (find your server hostname in cPanel → *Server Information*):

```bash
ssh yourcpuser@serverXXX.web-hosting.com -p 21098      # Namecheap SSH port is 21098
```

Then:

```bash
# 1. Put the code under your home dir (upload a zip and unzip, or git clone your repo)
cd ~ && mkdir -p botguard && cd botguard          # then upload+unzip platform/ here

# 2. (Optional) Composer isn't required — the app has a fallback autoloader.
#    If you want the optimized autoloader and have composer available:
cd ~/botguard/platform && composer install --no-dev

# 3. Create the schema from the CLI (or use the web installer in step 8 below)
cp .env.example .env      # edit DB_*, APP_URL, APP_KEY  (nano .env)
php bin/migrate.php       # creates tables + seeds admin/modules/thresholds
```

You still do the cPanel bits (PHP 8.3, database, subdomain → `public/`, SSL) below. With SSH, the
**License Server** (step 10) is trivial — just `php bin/migrate.php` in its folder, no cron trick needed.

---

## 0. Requirements

- A Namecheap shared plan with **cPanel** (Stellar / Stellar Plus / Business).
- Ability to select **PHP 8.3**.
- PHP extensions (enable in step 1): `pdo_mysql`, `mbstring`, `json`, `curl`, `openssl`, `zip`, `fileinfo`.

---

## 1. Set PHP to 8.3 and enable extensions

1. cPanel → **Select PHP Version** (a.k.a. *MultiPHP Manager* / *PHP Selector*).
2. Set the version to **8.3**.
3. On the **Extensions** tab, tick: `pdo_mysql`, `mbstring`, `json`, `curl`, `openssl`, `zip`, `fileinfo`.
4. Save.

---

## 2. Prepare the upload (on your PC)

From your project, create a ZIP of the **`platform/`** folder **excluding** these (not needed in production):

- `vendor/`  (no runtime Composer deps)
- `.env`  (the installer creates it)
- `storage/logs/*`, `storage/cache/*`, `storage/backups/*`
- `tests/`, `.git/`, `node_modules/`

Name it e.g. `botguard.zip`.

---

## 3. Upload and extract

1. cPanel → **File Manager**.
2. Go to your home directory (e.g. `/home/yourcpuser/`) — **not** `public_html`.
3. Create a folder `botguard` and open it.
4. **Upload** `botguard.zip` into `botguard/`, then right-click → **Extract**.
   You should end up with `/home/yourcpuser/botguard/platform/` containing `app/`, `public/`, `config/`, …

---

## 4. Create the database

1. cPanel → **MySQL® Databases**.
2. **Create New Database**: e.g. `botguard` → full name becomes `yourcpuser_botguard`.
3. **Add New User**: e.g. `bguser` with a strong password → full name `yourcpuser_bguser`.
4. **Add User To Database** → grant **ALL PRIVILEGES**.
5. Write down: DB name, DB user, password, host = `localhost`.

---

## 5. Point a subdomain at `public/`

1. cPanel → **Domains** (or **Subdomains**).
2. Create a subdomain, e.g. **`verify`** → `verify.yourdomain.com`.
3. Set its **Document Root** to:
   ```
   /home/yourcpuser/botguard/platform/public
   ```
   (Delete the auto-filled `public_html/verify` and type the path above.)
4. Create.

> If your plan won't let you set the document root outside `public_html`, put the folder at
> `public_html/botguard` and set the subdomain docroot to `public_html/botguard/platform/public`.

---

## 6. Set folder permissions

In **File Manager**, select `botguard/platform/storage` → **Permissions** → set to **755**
(apply to subfolders `logs`, `cache`, `backups`). The web user must be able to write here and to the
project root (so the installer can create `.env`).

---

## 7. Enable HTTPS (SSL)

1. cPanel → **SSL/TLS Status** (AutoSSL) → **Run AutoSSL**, or install Namecheap's SSL for the subdomain.
2. Confirm `https://verify.yourdomain.com` shows a padlock. BotGuard auto-enables HSTS over HTTPS.

---

## 8. Run the installer

1. Visit **`https://verify.yourdomain.com/`** — it redirects to **`/install`**.
2. Follow the wizard:
   - **License**: enter your key, or leave blank to run in **trial/offline mode**.
   - **Requirements**: all required rows must be green (fix PHP version/extensions if not).
   - **Database**: host `localhost`, your `yourcpuser_botguard` DB, `yourcpuser_bguser`, password → **Test & continue**.
   - **Administrator**: your admin name / email / password.
   - **Website**: Site name, Base URL = `https://verify.yourdomain.com`, timezone, default challenge = **Puzzle**.
   - **Install** → **Finish**.
3. Sign in at **`/login`** with your admin account.

> Prefer manual setup? Instead of the wizard, copy `.env.example` to `.env` (File Manager → rename),
> edit the `DB_*`, `APP_URL`, and `APP_KEY` values, then visit the site. Generate a key locally with
> `php -r "echo bin2hex(random_bytes(32));"`.

---

## 9. First-run configuration

- **Dashboard → Redirects**: set your **Primary URL** (where verified humans go) and **Alternate URL**.
- **Admin → Modules / Thresholds**: tune weights and score bands if desired.
- **Admin → SMTP**: (optional) add your mailbox's SMTP so welcome/test emails send. Send a test.
- Put your protected page behind `/verify`, or send visitors to `https://verify.yourdomain.com/verify`.

---

## 10. (Optional) License Server on a second subdomain

Only needed if you want to **issue/manage licenses yourself** (customers). The platform works fine
without it (offline/trial).

1. ZIP and upload the **`license-server/`** folder to `/home/yourcpuser/licenses/`.
2. Create a second database, e.g. `yourcpuser_licenses`, with a user.
3. Create subdomain **`licenses.yourdomain.com`** → docroot `…/licenses/license-server/public`.
4. `chmod 755` its `storage/`.
5. Copy `.env.example` → `.env`, set `DB_*`, `APP_URL=https://licenses.yourdomain.com`, and `APP_KEY`.
6. Because there is no web installer here, create the schema. If your plan has **SSH**:
   ```bash
   cd ~/licenses/license-server && php bin/migrate.php
   ```
   No SSH? cPanel → **Cron Jobs** → add a one-off command
   `php /home/yourcpuser/licenses/license-server/bin/migrate.php` (set it a few minutes ahead, then delete it).
7. Sign in at `https://licenses.yourdomain.com/login` (admin from that `.env`), add a customer, issue a license.
8. Back in the platform, point its client at the server by adding to the platform `.env`:
   `LICENSE_SERVER_URL=https://licenses.yourdomain.com`.

---

## 11. Post-install hardening

- In the platform `.env`, confirm `APP_ENV=production` and `APP_DEBUG=false` (the installer sets these).
- Keep `.env`, `app/`, `config/`, `storage/` **outside** the web root (they are, with the subdomain layout).
- Behind Cloudflare? cPanel → set `TRUSTED_PROXIES` in `.env` to Cloudflare's IPs so real client IPs +
  country are detected.
- Take a backup anytime from **Admin → Backups**.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| 500 error on load | Set `APP_DEBUG=true` in `.env` temporarily to see the message; usually DB creds or PHP version. |
| Redirect loop to `/install` | The app isn't installed yet — finish the wizard. After install, `storage/installed.lock` exists. |
| "Database connection failed" | Re-check DB name/user are the **prefixed** `yourcpuser_…` names; host is `localhost`. |
| Blank page / "class not found" | Confirm PHP is **8.3** for this subdomain in MultiPHP Manager. |
| Excel export fails | Enable the `zip` PHP extension. |
| Emails don't send | Enable `openssl`; verify SMTP host/port/credentials under Admin → SMTP; send a test. |
| `.htaccess` ignored | Ensure you extracted the app so `public/.htaccess` exists; LiteSpeed reads it automatically. |