# Deploying to Namecheap shared hosting (cPanel) — step by step

This guide is written for a **complete beginner** on Namecheap shared hosting with cPanel.
Read it top to bottom. Take your time; each step is small.

A ready-to-upload file has been created for you on your Desktop:
**`residential-ip-verifier-deploy.zip`** (the app with everything except `node_modules`,
which the server doesn't need).

> Your fresh production app key is already inside `.env.production.example`:
> `base64:cJfP5N2VUNKASJ9meEJrxjvlLpwW+tQYmxhlLnvWadU=`

---

## 0) What you need first

- A Namecheap shared hosting account with **cPanel**.
- Your domain pointed at that hosting (if you bought both at Namecheap this is usually done).
- 15–30 minutes.

---

## 1) Set the PHP version to 8.3 (required)

1. Log in to **cPanel**.
2. Search for **"Select PHP Version"** (sometimes "MultiPHP Manager").
3. Set the PHP version for your domain to **8.3** (8.2 will NOT work — Laravel 13 needs 8.3+).
4. On the **Extensions** tab, make sure these are ticked:
   `bcmath, ctype, curl, dom, fileinfo, gd, intl, mbstring, openssl, pdo_mysql,
   tokenizer, xml, zip` (and `sodium` if listed).
5. Click **Save** / **Apply**.

If 8.3 is not offered, open a Namecheap support chat and ask them to enable PHP 8.3 for your
account — it's free and takes them a minute.

---

## 2) Create the database (MySQL)

1. In cPanel open **"MySQL® Databases"**.
2. Under **Create New Database**, type a name like `ripv` → **Create Database**.
   The real name becomes `youruser_ripv` (cPanel adds your username — write it down).
3. Under **MySQL Users → Add New User**, create a user (e.g. `ripv`) and a strong password.
   The real username becomes `youruser_ripv` (write down the password too).
4. Under **Add User To Database**, select the user and the database → **Add** →
   tick **ALL PRIVILEGES** → **Make Changes**.

You now have three values for later: **database name**, **username**, **password**.

---

## 3) Upload the app

1. In cPanel open **"File Manager"**.
2. Go to your home folder (the one that *contains* `public_html`, not inside it).
3. Click **+ Folder**, create a folder named **`app`** (this will hold the Laravel code,
   safely outside the public web folder).
4. Open the **`app`** folder, click **Upload**, and upload
   `residential-ip-verifier-deploy.zip` from your Desktop. Wait for 100%.
5. Back in File Manager, right-click the uploaded zip → **Extract** → extract it into
   `app`. You should now see `app/artisan`, `app/public`, `app/vendor`, etc.
6. Delete the zip file to save space.

---

## 4) Put the public files where the domain looks

Your domain serves the **`public_html`** folder, but Laravel's web files live in `app/public`.
We move the public files up and point them back to the app.

1. In File Manager, open **`app/public`**.
2. Select **all** files in there (including the hidden `.htaccess` — turn on
   *Settings → Show Hidden Files* if you don't see it) and **Move** them into
   **`public_html`**.
   - If `public_html` already has a default `index.html` or `default.php`, delete those first.
3. Now open **`public_html/index.php`** → **Edit**, and change the two `require`/path lines
   so they point one level up into `app`. Replace the file's two `__DIR__.'/../...'` lines:

   **Find:**
   ```php
   require __DIR__.'/../vendor/autoload.php';
   ```
   **Change to:**
   ```php
   require __DIR__.'/../app/vendor/autoload.php';
   ```

   **Find:**
   ```php
   $app = require_once __DIR__.'/../bootstrap/app.php';
   ```
   **Change to:**
   ```php
   $app = require_once __DIR__.'/../app/bootstrap/app.php';
   ```
   (Newer Laravel uses `(require_once __DIR__.'/../bootstrap/app.php')` — just add `/app`
   before `/bootstrap` the same way.) **Save**.

> Result: `public_html` holds only the public entry files; all your code stays private in `app`.

---

## 5) Create your `.env` configuration

1. In File Manager open the **`app`** folder.
2. Find **`.env.production.example`**, right-click → **Copy** → name the copy **`.env`**
   (place it in `app`). Then right-click **`.env`** → **Edit**.
3. Fill in your real values:
   - `APP_URL=https://YOURDOMAIN.com` (use your actual domain)
   - `DB_DATABASE=` your database name from step 2 (e.g. `youruser_ripv`)
   - `DB_USERNAME=` your DB user from step 2
   - `DB_PASSWORD=` your DB password
   - For email, either fill the `MAIL_*` lines with an email account you create in cPanel
     (**Email Accounts**), or leave them — you can set SMTP later in the admin panel.
   - `SETUP_TOKEN=` type a long random string, e.g. `mySecret-9f8a72bc55` (used once in step 6).
4. **Save**.

---

## 6) Run the installer (creates tables + demo content)

You have two options. Try **Option A** first.

### Option A — cPanel Terminal / SSH (preferred)
1. In cPanel open **"Terminal"** (or connect via SSH).
2. Run these commands (replace the path if your home folder differs):
   ```bash
   cd ~/app
   php artisan migrate --force --seed
   php artisan storage:link
   php artisan config:cache
   ```
   If `php` is an old version there, use `/usr/local/bin/ea-php83 artisan ...` instead.

### Option B — No Terminal? Use the one-time web installer
1. Make sure you set `SETUP_TOKEN` in `.env` (step 5).
2. In your browser visit:
   `https://YOURDOMAIN.com/__setup/YOUR_SETUP_TOKEN`
   (use the exact token you put in `.env`).
3. You'll see a page of output ending in **DONE**. That created all tables and demo content.
4. **IMPORTANT — security:** edit `.env` again and **delete the `SETUP_TOKEN` line**
   (set it blank). The installer will then refuse to run again.

---

## 7) Lock it down & finish

1. **HTTPS:** in cPanel, your Namecheap **AutoSSL** usually issues a free certificate
   automatically. If the site isn't on `https`, open **"SSL/TLS Status"** → **Run AutoSSL**.
   Make sure `APP_URL` in `.env` starts with `https://`.
2. **File permissions:** in File Manager, set the **`app/storage`** and
   **`app/bootstrap/cache`** folders to **755** (right-click → Permissions). They must be
   writable by the web server.
3. Visit your site:
   - Home: `https://YOURDOMAIN.com`
   - Admin: `https://YOURDOMAIN.com/admin`
   - Log in as **`admin@residentialipverifier.test`** / **`password`**
   - **Change this admin password immediately** (Admin → top-right → Profile, or the Users
     resource) and update the site name, logo, colours, etc. under **Settings**.

---

## 8) After it works

- Remove `SETUP_TOKEN` from `.env` (if you used Option B) — double-check it's gone.
- Optional: delete `app/Http/Controllers/SetupController.php` and the `/__setup` route line
  in `app/routes/web.php`.
- Real geo accuracy: download the free **GeoLite2-City** and **GeoLite2-ASN** `.mmdb` files
  from your MaxMind account and upload them into `app/storage/app/geoip/` (overwrite the
  test files). Or switch to the MaxMind web service in **Admin → Settings → IP Intelligence**.

---

## Common problems

| Symptom | Fix |
|---|---|
| **500 error / blank page** | PHP not 8.3 (step 1), or `.env` DB values wrong, or `app/storage` not writable (step 7.2). Temporarily set `APP_DEBUG=true` in `.env` to see the real error, then set it back to `false`. |
| **"No application encryption key"** | The `APP_KEY` line in `.env` is missing — it's already provided in the example; make sure it copied over. |
| **CSS/styling missing** | The `public/build` folder didn't move into `public_html`. Re-check step 4 — `public_html` must contain a `build` folder and `index.php`. |
| **Images/logos you upload don't show** | The storage symlink isn't there. Run `php artisan storage:link` in Terminal, or it was created by the installer. On some hosts symlinks are disabled — contact support. |
| **Database connection error** | Re-check DB name/user/password include your cPanel username prefix (`youruser_...`), and `DB_HOST=127.0.0.1`. |
| **Page loads but `/admin` is 404** | Make sure the `.htaccess` file moved into `public_html` (it's hidden — enable "Show Hidden Files"). |

---

### Updating the site later
Edit content from the **admin panel** — no re-deploy needed. Only re-upload files if you
change actual code, in which case re-zip (excluding `node_modules`) and repeat steps 3–4,
then run `php artisan config:cache` again (or the installer).
