# NexStock — Live Production Deployment Guide (cPanel / Shared Linux)

> **Target Domain**: `nexstock.nexgentech.co.tz`  
> **Server Control Panel**: cPanel / Shared Linux Server  
> **PHP Version**: PHP 8.2 or 8.3  
> **Database**: MySQL 8.x  
> **Production Credentials**:
> - **Database User**: `nexgente_nexstock`
> - **Database Name**: `nexgente_nexstock`
> - **Database Password**: `U#_{C&NfSycnQ~2u`
> - **Host**: `127.0.0.1` (or `localhost`)
> - **System Email**: `nexstock@nexgentech.co.tz`

---

## 📋 Pre-Upload Preparation Checklist

- [x] **Local Frontend Assets Built**: Ran `npm run build` locally. Compiled assets are ready inside `public/build/`.
- [x] **Production Environment File Ready**: `.env.production` created with production credentials.
- [x] **HTTPS Enforcement**: `AppServiceProvider.php` configured to force HTTPS when `APP_ENV=production`.
- [ ] **cPanel Subdomain**: `nexstock.nexgentech.co.tz` created.
- [ ] **Document Root Assigned**: Must point to `public` folder (`/home/USERNAME/nexstock.nexgentech.co.tz/public` or `public_html/nexstock/public`).

---

## 🗂️ What to Upload vs What to EXCLUDE (Manual Upload)

When creating your project `.zip` file on your computer to upload to cPanel File Manager, follow these rules:

### ✅ MUST INCLUDE in ZIP:
- `app/`
- `bootstrap/` *(keep `bootstrap/app.php` and `bootstrap/cache/`)*
- `config/`
- `database/`
- `public/` *(contains `.htaccess`, `index.php`, `build/` assets, images, fonts)*
- `resources/` *(contains Vue views, blade templates, CSS)*
- `routes/`
- `storage/`
- `vendor/` *(see note below)*
- `artisan`
- `composer.json`
- `composer.lock`
- `.env.production` *(Rename this to `.env` after uploading to cPanel)*

### ❌ DO NOT UPLOAD (Save Bandwidth & Avoid Errors):
| Folder / File | Why Exclude |
|---|---|
| `node_modules/` | **NEVER upload!** (>300MB). Frontend is already built into `public/build/`. |
| `.git/` & `.github/` | Unnecessary repository history. |
| `.env` (Local) | Contains local XAMPP/Windows database settings. Use `.env.production` instead. |
| `tests/` | Unit and feature test files are not executed in live production. |
| `phpunit.xml` | Testing configuration. |
| `scratch_*.php` | Temporary debug scripts. |
| `storage/logs/laravel.log` | Start with a clean/empty log file on the server. |

> [!NOTE]
> **About the `vendor/` directory**:
> - If you have **SSH / Terminal access** in cPanel, do **NOT** upload `vendor/`. Simply upload without `vendor/` and run `composer install --no-dev --optimize-autoloader` via SSH.
> - If you **DO NOT have SSH access**, run `composer install --no-dev --optimize-autoloader` locally first, then include the `vendor/` folder in your ZIP.

---

## 🚀 Step-by-Step cPanel Deployment Guide

### Step 1: Upload & Extract via cPanel File Manager
1. In cPanel, open **File Manager**.
2. Navigate to your subdomain directory (e.g., `/home/nexgente/nexstock.nexgentech.co.tz/`).
3. Click **Upload** and select your `NexStock.zip`.
4. Right-click the uploaded `.zip` and click **Extract**.
5. Rename `.env.production` to `.env`.

---

### Step 2: Configure Document Root (Crucial)
In cPanel $\rightarrow$ **Domains** (or **Subdomains**):
- Subdomain: `nexstock.nexgentech.co.tz`
- **Document Root**: Must end with `/public`:
  ```text
  /home/nexgente/nexstock.nexgentech.co.tz/public
  ```
  *(If your cPanel forces root in `public_html`, point it to `public_html/nexstock/public`)*.

---

### Step 3: Linux File Permissions (Avoid 500 Internal Server Error)
On shared Linux servers, incorrect file permissions cause HTTP 500 errors or blank screens. Set the permissions as follows:

#### Via SSH Terminal:
```bash
cd /home/nexgente/nexstock.nexgentech.co.tz

# Standard Linux directory & file permissions
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

# Writable directories for Laravel cache, logs, and sessions
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/

# If server requires full write access:
chmod -R 777 storage/
chmod -R 777 bootstrap/cache/
```

#### Via cPanel File Manager (If No SSH):
1. In File Manager, navigate to project root.
2. Right-click `storage` folder $\rightarrow$ **Change Permissions** $\rightarrow$ Set to `775` (or `777` if required by hosting).
3. Right-click `bootstrap/cache` folder $\rightarrow$ **Change Permissions** $\rightarrow$ Set to `775` (or `777`).

---

### Step 4: Run Database Migrations & Seeders

#### Method A: Via cPanel Terminal / SSH (Recommended)
```bash
cd /home/nexgente/nexstock.nexgentech.co.tz

# Run all migrations
php artisan migrate --force

# Seed base roles, retail units & default categories
php artisan db:seed --force

# Create storage symlink for uploaded logos & assets
php artisan storage:link
```

#### Method B: Via phpMyAdmin (If No Terminal)
1. In cPanel $\rightarrow$ **phpMyAdmin**.
2. Select database `nexgente_nexstock`.
3. Export your local MySQL database tables (from XAMPP `phpMyAdmin` or `mysqldump`) and click **Import** into `nexgente_nexstock`.

---

### Step 5: Production Performance & Cache Optimization

Run these commands in cPanel Terminal to speed up page loads and cache configurations:
```bash
cd /home/nexgente/nexstock.nexgentech.co.tz

php artisan config:cache
php artisan route:cache
php artisan view:cache
```

*(Note: Whenever you modify `.env`, always run `php artisan config:clear` and `php artisan config:cache`)*.

---

## ⚙️ Cron Jobs & Background Queue Configuration

Shared Linux hosting does not run continuous daemon background processes (like Redis Supervisor). NexStock is configured to use the **`database` queue driver** and **cPanel Cron Jobs**.

### In cPanel $\rightarrow$ **Cron Jobs**, set up these 2 jobs:

#### 1. Laravel Master Task Scheduler (Runs Every Minute)
- **Schedule**: `* * * * *` (Every Minute)
- **Command**:
  ```bash
  /usr/local/bin/php /home/nexgente/nexstock.nexgentech.co.tz/artisan schedule:run >> /dev/null 2>&1
  ```
  *(Handles trial expiration checks, low stock scanners, and automated maintenance)*.

#### 2. Background Queue Worker (Runs Every Minute to Process Email/SMS)
- **Schedule**: `* * * * *` (Every Minute)
- **Command**:
  ```bash
  /usr/local/bin/php /home/nexgente/nexstock.nexgentech.co.tz/artisan queue:work database --stop-when-empty --tries=3 >> /dev/null 2>&1
  ```
  *(Picks up queued WhatsApp alerts, welcome emails, and background jobs, processes them, and exits cleanly)*.

---

## 🔒 Verification & Live Testing Checklist

After completing the steps:
1. Visit `https://nexstock.nexgentech.co.tz`
   - [ ] SSL padlock is active (HTTPS).
   - [ ] Landing page loads with branding logo and images.
2. Test User Lifecycle:
   - [ ] Click **"Start Free 14-Day Trial"** and register a new store.
   - [ ] Check if welcome email is received from `nexstock@nexgentech.co.tz`.
   - [ ] Check if admin WhatsApp alert is received.
3. Test POS & Finance:
   - [ ] Open POS Counter (`/pos`), add products, and perform a test checkout.
   - [ ] Check [Operating Expenses (`/expenses`)](https://nexstock.nexgentech.co.tz/expenses) and [Income Ledger (`/income`)](https://nexstock.nexgentech.co.tz/income).
   - [ ] Check [Reports (`/reports`)](https://nexstock.nexgentech.co.tz/reports) for P&L and Cashflow breakdown.