# EdumacFlo Multi-Tenant SaaS — cPanel & Shared Hosting Deployment Guide

This guide walks you through deploying **EdumacFlo Multi-Tenant SaaS** on any standard **cPanel**, **WHM**, or **VPS** hosting environment in under 2 minutes using the automated Web Installer Wizard.

---

## Prerequisites

Before starting, ensure your cPanel hosting account has:
1. **PHP 7.4 or higher** (PHP 8.0 – 8.2 strongly recommended).
2. **PHP Extensions Enabled**: `mysqli`, `pdo`, `pdo_mysql`, `mbstring`, `curl`, `openssl`, `json`, `gd`, `zip` (enabled by default on almost all cPanel hosts under **Select PHP Version** or **MultiPHP INI Manager**).
3. **One MySQL Database & User** created via cPanel.

---

## Step 1: Upload & Extract the Distribution Package

1. Log into your **cPanel Dashboard**.
2. Open **File Manager** and navigate to your web root (`public_html/` or your addon domain root directory).
3. Click **Upload** in the top navigation bar and select:
   ```
   edumacflo-v2-saas-installer.zip
   ```
4. Once the upload hits 100%, return to File Manager, right-click `edumacflo-v2-saas-installer.zip`, and click **Extract**.
5. Extract the files directly into `public_html/`.

---

## Step 2: Create a MySQL Database & User in cPanel

1. In cPanel, go to **MySQL Databases** (or **MySQL Database Wizard**).
2. **Create a New Database**:
   - Example: `cpaneluser_edumacflo_master`
3. **Create a New Database User**:
   - Username: `cpaneluser_dbadmin`
   - Password: Choose a strong password and save it securely.
4. **Add User to Database**:
   - Check **ALL PRIVILEGES** and click **Make Changes**.

---

## Step 3: Launch the Web Installer Wizard

1. Open your web browser and navigate to:
   ```
   https://yourdomain.com/install/
   ```
   *(If your database is not yet configured, simply visiting `https://yourdomain.com/` will also automatically redirect you to the installer!)*

2. **Step 1 — System Check**:
   - The installer will automatically verify PHP version, required extensions, and directory write permissions. Click **Continue**.

3. **Step 2 — Deployment Mode & Database**:
   - Choose **Multi-Tenant SaaS Platform** (Recommended) or **Single-Tenant Standalone**.
   - Enter your database details:
     - **Host**: `localhost` (or `127.0.0.1`)
     - **Port**: `3306`
     - **Database Username**: Your cPanel MySQL username (e.g., `cpaneluser_dbadmin`).
     - **Database Password**: Your MySQL user password.
     - **Database Name**: Your created database (e.g., `cpaneluser_edumacflo_master`).
   - Click **🔌 Test Database Connection** to verify connection, then click **Configure Administrator**.

4. **Step 3 — Accounts & School Setup**:
   - Set up your master SaaS Super-Admin credentials (Name, Username, Email, Password).
   - *(Optional)* Enter an initial starter school name and slug (e.g. `crownintl`).

5. **Step 4 — Automated Installation**:
   - Click **Execute Installation**.
   - Watch the live deployment console import tables, seed plans, hash credentials, and generate `saas_master_config.php` and `db_config.php`.

6. **Step 5 — Ready to Launch!**:
   - The installer will automatically lock itself (`install/installed.lock`) for production security.
   - Click **🚀 Launch EdumacFlo Dashboard** to log in at:
     ```
     https://yourdomain.com/saas/admin/login.php
     ```

---

## Step 4: Configure Wildcard Subdomains (for Multi-Tenant School URLs)

To allow each school to have their own portal subdomain (e.g. `school1.yourdomain.com`, `greenwood.yourdomain.com`):

1. In cPanel, go to **Domains** &rarr; **Subdomains**.
2. In the Subdomain field, type:
   ```
   *
   ```
3. Set the **Document Root** to point to the exact same folder as your main application (`public_html/`).
4. Click **Create**.
5. In your DNS Management (cPanel Zone Editor or Cloudflare), ensure a Wildcard `A` record exists:
   ```
   *  IN  A  YOUR_SERVER_IP
   ```

---

## Step 5: Set Up the 15-Minute cPanel Cron Job

To automate daily subscription expiration checks, tenant snapshot backups, and housekeeping:

1. In cPanel, search for and open **Cron Jobs**.
2. Under **Add New Cron Job**, select **Common Settings**: `Once Every 15 Minutes (*/15 * * * *)`.
3. In the **Command** field, enter:
   ```bash
   /usr/local/bin/php /home/CPANEL_USERNAME/public_html/cron/saas_cron_runner.php >/dev/null 2>&1
   ```
   *(Replace `CPANEL_USERNAME` with your actual cPanel username)*.
4. Click **Add New Cron Job**.

---

## Security & Maintenance Tips

- **Reinstalling / Resetting**: To rerun the installer, delete `install/installed.lock`.
- **Payment Gateway Live Mode**: Once live, open `saas_master_config.php` and set `'payment_simulation' => false` and paste your live Paystack/Flutterwave API keys.
- **Upload Backups**: Tenant student pictures and documents are securely stored in isolated folders under `uploads/tenants/{school_slug}/` with PHP execution blocked via `.htaccess`.
