# cPanel & WHM Wildcard Multi-Tenant Setup Guide

This guide explains how to deploy the EdumacFlo Multi-Tenant SaaS platform on standard cPanel hosting with automatic wildcard subdomain routing.

---

## Step 1: Create the Wildcard Subdomain in cPanel

1. Log into your **cPanel Account**.
2. Navigate to **Domains** -> **Domains** (or **Subdomains** in older cPanel versions).
3. Click **Create A New Domain**.
4. In the domain name field, enter:
   ```text
   *.yourdomain.com
   ```
   *(e.g., `*.edumacflo.com`)*
5. **CRITICAL**: Uncheck *"Share document root"*. Set the **Document Root** to point to the exact same folder as your main website:
   ```text
   public_html
   ```
6. Click **Submit**.

> **How this works**: Any request to `schoolname.yourdomain.com` will now load your main application codebase in `public_html/`. The dynamic router in `public/connection.php` will read `$_SERVER['HTTP_HOST']`, look up `schoolname` in `edumacflo_master`, and connect to that school's isolated database automatically.

---

## Step 2: Configure Wildcard SSL (AutoSSL / Let's Encrypt)

1. In cPanel, navigate to **Security** -> **SSL/TLS Status**.
2. Locate your domain:
   - `yourdomain.com`
   - `*.yourdomain.com`
3. Click **Run AutoSSL**.
4. If your cPanel host uses Let's Encrypt with DNS verification enabled, AutoSSL will automatically issue a wildcard SSL certificate covering all subdomains.
5. If using Cloudflare:
   - Go to Cloudflare DNS dashboard.
   - Add a DNS Record:
     - **Type**: `A`
     - **Name**: `*`
     - **IPv4 Address**: `Your Server IP`
     - **Proxy status**: Proxied (Orange Cloud) for automatic SSL.

---

## Step 3: Configure Database Privileges in cPanel

In single-tenant mode, you only needed one database. In multi-tenant mode, the automated provisioner creates a new database (`cpaneluser_tenant_slug`) for each new school.

1. Ensure your cPanel MySQL user has permissions to **CREATE DATABASE** and grant privileges.
2. In `saas_master_config.php`, configure your MySQL credentials:
   ```php
   return [
       'enabled'  => true,
       'host'     => 'localhost',
       'username' => 'cpaneluser_dbuser',
       'password' => 'YourStrongPassword',
       'dbname'   => 'cpaneluser_master',
   ];
   ```

---

## Step 4: Configure the Multi-Tenant Cron Job in cPanel

1. In cPanel, search for **Cron Jobs**.
2. Under **Add New Cron Job**:
   - Common Settings: **Once Per Hour** (or `0 * * * *` / `*/15 * * * *`).
   - Command:
     ```bash
     /usr/local/bin/php /home/cpaneluser/public_html/cron/tenant_cron_runner.php >/dev/null 2>&1
     ```
     *(Adjust path to match your cPanel username and PHP path)*
3. Click **Add New Cron Job**.

---

## Step 5: Verify Wildcard Routing

1. Open your browser and navigate to:
   ```text
   https://kings.yourdomain.com
   ```
2. You should see the Kings College portal login screen.
3. Access the SaaS Super-Admin panel:
   ```text
   https://yourdomain.com/saas/admin/login.php
   ```
