# Installation Guide

Works on local (XAMPP/Laragon), a VPS, or **cPanel/LiteSpeed shared hosting**.

## 1. Requirements

- PHP **8.1+** with `pdo_mysql`, `mbstring`, `fileinfo`, `openssl`
- MySQL 5.7+ / MariaDB 10.3+
- Apache/LiteSpeed with `mod_rewrite` (or Nginx with equivalent rewrites)

## 2. Database

Create a database, then import **schema first, seed second**:

```sql
CREATE DATABASE reeva_cargo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
```bash
mysql -u <user> -p reeva_cargo < database/schema.sql
mysql -u <user> -p reeva_cargo < database/seed.sql
```
(In cPanel, use **phpMyAdmin → Import** for each file in that order.)

## 3. Configuration

Copy `.env.example` to `.env` and set your values:

```
APP_ENV=production
APP_URL=            # leave BLANK to auto-detect (recommended on cPanel)
DB_HOST=localhost
DB_NAME=reeva_cargo
DB_USER=your_db_user
DB_PASS=your_db_pass

# Optional gateways (Notifications module is API-ready)
MAIL_HOST=
SMS_URL=
SMS_KEY=
WHATSAPP_URL=
WHATSAPP_TOKEN=
```

> **APP_URL auto-detect:** leave `APP_URL` empty and the app derives the base URL from the request. This avoids broken assets/redirects when the same code runs on staging + production. If you set it, set it to the exact scheme+host with no trailing slash.

## 4. Web root

Point your domain/subdomain **document root to the `public/` folder**.

- **cPanel:** create a subdomain (e.g. `cargo.deevapayon.com`) and set its Document Root to `.../reeva-cargo-erp/public`.
- If you cannot move the docroot and must serve from a subfolder, keep `public/` as the entry and ensure the included `.htaccess` files are uploaded (they are shipped in the repo).

## 5. Writable folders

```bash
chmod -R 775 storage
```
The app writes to `storage/logs`, `storage/uploads`, `storage/documents`.

> **`is_writable()` false negatives on cPanel/LiteSpeed:** some hosts report writable dirs as non-writable. This app checks writability with a real write-probe (attempts to create a temp file) rather than trusting `is_writable()` alone, so uploads keep working even when the function lies.

## 6. Common cPanel / LiteSpeed gotchas (already handled)

- **`php_flag` in `.htaccess` → HTTP 500:** never put `php_flag`/`php_value` in `.htaccess` on LiteSpeed. Use a **`.user.ini`** in `public/` instead. A sample is included:
  ```
  upload_max_filesize = 20M
  post_max_size = 25M
  max_execution_time = 120
  memory_limit = 256M
  ```
- **PHP execution disabled in uploads:** `storage/` ships with an `.htaccess` that denies direct access and disables PHP execution in upload dirs (security baseline).
- **`$_ENV` vs `getenv()`:** the config loader reads `$_ENV` first and falls back to `getenv()`, because some hosts populate only one of them.
- **Hardcoded base URL breaks redirects:** solved by the `APP_URL` auto-detect above.

## 7. First run

Visit your domain → log in with the default credentials in **README.md** → change the admin password → start creating masters (Companies/Branches already seeded).