# cPanel Deployment Guide — Harcourts Marketing Portal

This step-by-step guide explains how to deploy the **Harcourts Marketing Request & Proofing Portal** to standard cPanel web hosting (Shared Hosting, Namecheap, cPanel/WHM, cPanel Apache environments).

---

## Step 1: Check PHP Version in cPanel

1. Log into your **cPanel**.
2. Search for **Select PHP Version** or **MultiPHP Manager**.
3. Set the PHP version for your domain to **PHP 8.2** or **PHP 8.3**.
4. Ensure the following extensions are enabled:
   - `pdo_mysql`
   - `fileinfo`
   - `gd`
   - `mbstring`
   - `openssl`
   - `zip`

---

## Step 2: Create MySQL Database & User

1. In cPanel, open **MySQL Database Wizard** (or **MySQL Databases**).
2. Create a database, e.g., `username_harcourts_db`.
3. Create a database user, e.g., `username_harcourts_usr`, and set a strong password.
4. Assign the user to the database and grant **ALL PRIVILEGES**.

---

## Step 3: Upload Project Files to cPanel

### Option A: Direct Document Root (Recommended)
If your cPanel domain document root can be set directly to the `public/` directory (e.g. `/home/username/public_html/public`):
1. Zip your project files locally (excluding `node_modules`, `.git`, and local `vendor/` if installing via SSH).
2. Upload the zip file into your domain folder in cPanel File Manager and extract it.

### Option B: Root Folder + Public Folder (Standard cPanel Structure)
If your domain points strictly to `public_html/`:
1. Upload all project files **ONE LEVEL ABOVE** `public_html`, into `/home/username/harcourts-portal/`.
2. Move the contents of `/home/username/harcourts-portal/public/` into `/home/username/public_html/`.
3. Edit `/home/username/public_html/index.php` and update the paths to point to the parent directory:
   ```php
   require __DIR__.'/../harcourts-portal/vendor/autoload.php';
   $app = require_once __DIR__.'/../harcourts-portal/bootstrap/app.php';
   ```

---

## Step 4: Configure the `.env` File

In your project root (e.g. `/home/username/harcourts-portal/.env`), set the production configuration:

```ini
APP_NAME="Harcourts Marketing Request Portal"
APP_ENV=production
APP_KEY=base64:9cyY2633qbIbLkC2WAmday31sO7/E1c+3SEdgd57jnQ=
APP_DEBUG=false
APP_TIMEZONE=Pacific/Auckland
APP_URL=https://yourdomain.co.nz

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=username_harcourts_db
DB_USERNAME=username_harcourts_usr
DB_PASSWORD=your_strong_mysql_password

FILESYSTEM_DISK=public
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.co.nz
MAIL_PORT=587
MAIL_USERNAME=noreply@yourdomain.co.nz
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@yourdomain.co.nz"
MAIL_FROM_NAME="Harcourts Marketing Portal"
```

---

## Step 5: Execute Terminal / Artisan Commands

If you have cPanel **Terminal** or SSH access, run the following commands:

```bash
# 1. Run database migrations and seed default users
php artisan migrate:fresh --seed --force

# 2. Create the storage symlink for uploaded proofs
php artisan storage:link

# 3. Optimize application performance caches
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

*(If SSH/Terminal is not available on your hosting plan, you can create a temporary route in `routes/web.php` or execute artisan commands via a PHP script).*

---

## Step 6: File & Folder Permissions

Ensure proper folder write permissions in cPanel File Manager:
- `storage/` → `755`
- `storage/app/public/` → `755`
- `bootstrap/cache/` → `755`

---

## Step 7: Configure cPanel Cron Job

To run automated background checks (e.g., checking overdue jobs, sending scheduled notifications):
1. In cPanel, open **Cron Jobs**.
2. Set schedule to **Every Minute** (`* * * * *`).
3. Add command:
   ```bash
   * * * * * cd /home/USERNAME/public_html && php artisan schedule:run >> /dev/null 2>&1
   ```

---

## Step 8: Enable SSL (HTTPS)

1. Open **Lets Encrypt SSL** or **AutoSSL** in cPanel.
2. Run SSL installation for your domain.
3. Ensure `APP_URL` in `.env` starts with `https://`.

---

## Step 9: Post-Deployment Verification Checklist

1. Log in with default Super Admin: `admin@harcourts.co.nz` / `Password123!`.
2. Navigate to **User Management** and update the Super Admin password.
3. Log in as Harcourts Admin (`harcourts.admin@harcourts.co.nz`) and create a test request with a Property Listing URL.
4. Log in as Designer (`designer@harcourts.co.nz`) and verify the request appears instantly on the workload dashboard.
5. Test uploading a proof file (Version 1) and verify browser preview renders cleanly.
6. Test approval and revision workflows.

---

## 🆘 Troubleshooting

- **500 Internal Server Error**: Check `.env` syntax, verify PHP version is 8.2+, and inspect `storage/logs/laravel.log`.
- **404 Image / Proof Not Found**: Run `php artisan storage:link` or verify symlink points to `storage/app/public`.
- **Styles Not Loading**: Verify CSS CDN links or relative paths in `.htaccess`.