# Install KOS on cPanel shared hosting

About 20 minutes. You need: cPanel login, a domain or sub-domain for KOS (e.g. `kos.kingdigital.in`), and `KOS-server.zip`.

## 1. Check PHP
cPanel → **Select PHP Version** (or **MultiPHP Manager**):
* Choose **PHP 8.1 or newer** (8.2 / 8.3 is best) for the KOS domain.
* Tick these extensions: **pdo_mysql, curl, mbstring, fileinfo, openssl** (and **apcu** if listed).

## 2. Create the database
cPanel → **MySQL® Databases**:
1. **Create New Database:** `kos` → cPanel names it `cpuser_kos`. Note the full name.
2. **Add New User:** `kosuser` with a long password (use the Password Generator). Note the full name `cpuser_kosuser` and the password.
3. **Add User To Database:** pick both → tick **ALL PRIVILEGES** → Make Changes.

KOS needs **MySQL 8.0+ or MariaDB 10.6+**. The version is shown on the cPanel home page under *General Information → Server Information*; if it is older, ask your host to upgrade.

## 3. Upload KOS (outside public_html)
cPanel → **File Manager**:
1. Open your **home folder** (`/home/cpuser`) — *not* `public_html`.
2. **Upload** `KOS-server.zip`, then right-click → **Extract**. You get `/home/cpuser/KOS-server/`.
3. Delete the zip.

Only `KOS-server/public` will be visible on the web; settings, data and code stay private.

## 4. Point the domain at KOS
cPanel → **Domains** → **Create A New Domain** (or Subdomains):
* Domain: `kos.kingdigital.in`
* Untick "Share document root"; **Document Root:** `KOS-server/public`
* Submit. If the sub-domain already exists, use **Manage** to change its document root.

## 5. Turn on HTTPS
cPanel → **SSL/TLS Status** → tick the domain → **Run AutoSSL** (or Let's Encrypt). Wait until it shows a green lock. KOS sends everyone to https.

## 6. Folder permissions
In File Manager, right-click → **Change Permissions**:
* `KOS-server/storage` and `KOS-server/config` → **755**
* files are normally 644 already; leave them.

## 7. Run the setup page
1. Open **https://kos.kingdigital.in/setup.php**. It checks the server and creates a one-time **setup key**.
2. In File Manager open `KOS-server/storage/setup-key.txt` (right-click → View) and copy the key.
3. Fill in the form: setup key · database name, user and password from step 2 (host `localhost`) · web address `https://kos.kingdigital.in` · company name · **your admin name, work email and password**.
4. Click **Install KOS**. When it says *KOS is installed*, the setup page switches itself off and deletes itself. (If it asks you to, delete `KOS-server/public/setup.php` in File Manager.)

*Have Terminal in cPanel instead?* You can run `php KOS-server/install/install.php` there — same result.
If `php -v` shows an old version, use the full path, e.g. `/usr/local/bin/ea-php83` or `/opt/alt/php83/usr/bin/php`.

## 8. Sign in
Open **https://kos.kingdigital.in/staff/login.php** → your email and password. Customers use **https://kos.kingdigital.in/portal/login.php**.

## 9. Email and SMS (File Manager → `KOS-server/config/app.php` → Edit)
**Email** — needed so staff can set their passwords. Create a mailbox in cPanel → **Email Accounts** (e.g. `kos@kingdigital.in`), then:
```php
'mail' => [
    'driver' => 'smtp',
    'from' => 'kos@kingdigital.in', 'from_name' => 'KOS · King Digital',
    'smtp' => ['host' => 'mail.kingdigital.in', 'port' => 465, 'secure' => 'ssl', 'user' => 'kos@kingdigital.in', 'pass' => 'MAILBOX-PASSWORD'],
],
```
(The exact host and port are in cPanel → Email Accounts → **Connect Devices**.)

**SMS OTP for customers** — set `'driver' => 'msg91'` (or `fast2sms`) and fill in your keys and DLT-approved template ID. While testing keep `'driver' => 'log'`: codes are written to `KOS-server/storage/logs/sms.log` instead of being sent. **Never leave `log` on a live site.**

**Recommended:** in `'staff' => [...]` set `'email_2fa' => true` (staff also enter a code from their email).

## 10. PHP safety settings
cPanel → **MultiPHP INI Editor** → choose the KOS domain → set:
`display_errors` **Off** · `expose_php` **Off** · `allow_url_fopen` **Off** · `upload_max_filesize` **10M** · `post_max_size` **12M** · `session.cookie_secure` **On** · `session.cookie_httponly` **On**

## 11. Cron job (nightly clean-up)
cPanel → **Cron Jobs** → Add New Cron Job → *Once Per Day*, command:
```
/usr/local/bin/php /home/cpuser/KOS-server/cron/cleanup.php >/dev/null 2>&1
```
(replace `cpuser` with your cPanel username; use the PHP path from step 7 if different).

## 12. Backups
cPanel → **Backup** (or **JetBackup**) → download a **MySQL database backup** of `cpuser_kos` and a **Home directory** backup of `KOS-server` regularly, and keep them off the server. (`cron/backup.sh` is for VPS servers.)

## Add your team and customers
* **Staff:** KOS → Employees → add each person with a work email and role. They open the sign-in page → *Forgot or first-time password?* → email link → choose a password.
* **Customers:** HR or an admin opens a customer → *Create customer login* with their 10-digit mobile.

## If something goes wrong
| You see | Do this |
|---|---|
| **500 Internal Server Error** | cPanel → **Errors** (or `public/error_log`). Usually: PHP below 8.1, or a missing extension (step 1). If it says `Options not allowed`, delete the line starting with `Options` in `KOS-server/public/.htaccess`. |
| **403 Forbidden** in your browser | A VPN or browser add-on is hiding your browser details; use normal Chrome / Edge / Safari. |
| "Could not connect to the database" | Wrong DB name/user/password, or the user is not added to the database with ALL PRIVILEGES (step 2). |
| "Your database is MySQL 5.7 …" | Ask your host for MySQL 8 / MariaDB 10.6+, or move to a plan that has it. |
| "storage folder is not writable" | Set `KOS-server/storage` to 755 (step 6). |
| Page keeps redirecting | SSL is not active yet (step 5). If the site is behind Cloudflare, set SSL mode to **Full (strict)**. |
| Staff email never arrives | Check the `mail` settings (step 9). Test with `'driver' => 'log'` and read `storage/logs/mail.log`. |
| Customer OTP never arrives | DLT template / sender ID not approved yet, or wrong SMS keys. |