# Put CleanMate (PHP + MySQL) on cPanel

This guide uses your real details. Where it says **qlixbzqplz**, that is your
cPanel user name; **laundry.tapiyo.com** is the address CleanMate gets until
you have its own domain (when you buy e.g. cleanmate.ae, use that instead
everywhere below). You need only the
cPanel pages **MultiPHP Manager**, **MySQL Databases**, **File Manager**,
**Domains** and **Cron Jobs**.

You will make three things:

| What | Where |
|---|---|
| The program | `/home/qlixbzqplz/cleanmatepro` |
| Pictures, PDFs, backups | `/home/qlixbzqplz/cleanmatepro-files` |
| The database | MySQL database `qlixbzqplz_cmpro` |

> **First make the address:** cPanel → **Domains** → **Create A New Domain** →
> `laundry.tapiyo.com` → untick *Share document root* → **Submit**. Your
> DinePad Pro at resto.tapiyo.com is not touched by anything in this guide.

---

## 1. Build the package (on your Mac)

In the CleanMate folder (`~/cleanmate-new`) run:

```bash
sh laravel_server/tools/build_cpanel.sh
```

You get **`deploy/cleanmate-laravel-cpanel.zip`** (about 45 MB).

## 2. Choose PHP 8.3

1. cPanel → **MultiPHP Manager**.
2. Tick **laundry.tapiyo.com**.
3. Top right, **PHP Version** → **PHP 8.3** → **Apply**.

If your cPanel has **Select PHP Version** instead: choose **8.3**, then open
**Extensions** and make sure these are ticked: `pdo_mysql`, `mbstring`,
`openssl`, `curl`, `zip`, `gd`, `pdo_sqlite`, `fileinfo`.

## 3. Make the database

cPanel → **MySQL Databases**:

| Box | Type |
|---|---|
| **Create New Database** → New Database | `cmpro` → **Create Database** (cPanel names it `qlixbzqplz_cmpro`) |
| **Add New User** → Username | `cmpro` (it becomes `qlixbzqplz_cmpro`) |
| Password | click **Password Generator**, tick "I have copied this password", **Use Password**. **Keep this password** — you need it in step 5. |
| → **Create User** | |
| **Add User To Database** → User | `qlixbzqplz_cmpro` |
| Database | `qlixbzqplz_cmpro` → **Add** |
| On the next page | tick **ALL PRIVILEGES** → **Make Changes** |

### 3b. Load the tables (phpMyAdmin)

The file **`cleanmate-database.sql`** (in the `deploy` folder, next to the zip)
holds every CleanMate table, empty.

1. cPanel → **phpMyAdmin**.
2. On the left, click **`qlixbzqplz_cmpro`**.
3. Top menu **Import** → **Choose File** → `cleanmate-database.sql`.
4. Leave everything else as it is → scroll down → **Import**.
   You should see "Import has been successfully finished" and 115 tables on the left.

(You can skip this step: the program also makes the tables by itself on its
first visit. Importing them first is quicker and shows any database problem
straight away. Importing the file again later is safe; it never deletes
anything.)

## 4. Upload the program

1. cPanel → **File Manager**. You are in `/home/qlixbzqplz`.
2. Top right **Settings** → tick **Show Hidden Files (dotfiles)** → **Save**.
3. **Upload** → choose `cleanmate-laravel-cpanel.zip` → wait until it shows 100% → **Go Back**.
4. Right-click the zip → **Extract** → leave `/home/qlixbzqplz` → **Extract Files**.
   You now have the folder **`cleanmatepro`**.
5. Click **+ Folder** → name it `cleanmatepro-files` → **Create New Folder**.
6. Delete the zip (right-click → **Delete**).

## 5. Type the database password

1. Open the folder `cleanmatepro`.
2. Right-click **`.env`** → **Edit** → **Edit**.
3. Change only these lines:

| Line | Make it |
|---|---|
| `DB_PASSWORD=type-the-password-here` | `DB_PASSWORD=` and the password from step 3 |
| `APP_URL=https://laundry.tapiyo.com` | your address (e.g. `https://laundry.tapiyo.com`) |
| `PUBLIC_URL=https://laundry.tapiyo.com` | the same address |
| `ADMIN_LOGIN_PATH=type-your-secret-word` | a secret word only you know, e.g. `ADMIN_LOGIN_PATH=retail-boss-4827` (small letters, numbers and dashes). Your super admin sign-in page becomes `https://laundry.tapiyo.com/retail-boss-4827`. **Write it down.** |

4. **Save Changes** → **Close**.

(The database and user names `qlixbzqplz_cmpro` and the data folder
`/home/qlixbzqplz/cleanmatepro-files` are already filled in.)

### Visitor addresses (only behind a proxy or Cloudflare)
On cPanel the program sees each visitor's real address directly and ignores the
`X-Forwarded-For` header that anyone can send, so nothing needs setting. Only
if the site is put behind a proxy or Cloudflare add one of these to `.env`:

| Line | When |
|---|---|
| `TRUSTED_PROXIES=203.0.113.10` | a proxy or load balancer in front of the site (its public addresses or ranges, comma separated; local and private addresses are trusted already) |
| `CLOUDFLARE_PROXIES=173.245.48.0/20,103.21.244.0/22,…` | the site is behind Cloudflare (orange cloud): Cloudflare's IPv4 ranges from cloudflare.com/ips |

Without them, behind a proxy every visitor would show the proxy's address
(Allowed networks would then refuse staff), so set them before switching a
proxy on.

## 6. Point the domain at the program

1. cPanel → **Domains**.
2. Find **laundry.tapiyo.com**  → **Manage**.
3. **Document Root**: change it to `/home/qlixbzqplz/cleanmatepro/public` → **Update**.
4. Back on **Domains**, check **Force HTTPS Redirect** is on for that domain.

Open `https://laundry.tapiyo.com/api/health` in your browser. You should see
a line starting with `{"ok":true`. The tables in the database are made
automatically on this first visit.

Then open `https://laundry.tapiyo.com` → the dashboard asks you to create the
**super admin** (on a new server). Use your own email and a strong password
(at least 8 characters).

From now on the super admin signs in **only** at your secret link
(`https://laundry.tapiyo.com/retail-boss-4827`, the word from step 5). The
normal sign-in page is for stores; resellers use
`https://laundry.tapiyo.com/reseller`.

### Offline licence keys (only if you sell the offline Windows app)

The keys are signed with your private key, the file **`license_private.key`**
in the `secrets` folder of CleanMate on your Mac (`~/cleanmate-new/secrets`). It
is CleanMate's own key: DinePad's key does not work here.

1. File Manager → open `/home/qlixbzqplz/cleanmatepro-files`.
2. **Upload** → choose `license_private.key` → **Go Back**.

Super admin → **Offline licences** now says it is ready. Never send this file
to anyone.

### Keep the files and the licence key in a private folder

The server looks in `/home/qlixbzqplz/private` by itself (the folder next to `cleanmatepro`),
so no `.env` change is needed. (Check first that your host does not serve that folder to the
web: on some hosts `private_html` is the HTTPS website folder, so do not use that name.)

1. Upload and extract the update zip as usual (step 9, Updating later).
2. File Manager → `/home/qlixbzqplz` → **+ Folder** → `private`.
3. Move the whole `cleanmatepro-files` folder into `private`
   (→ `/home/qlixbzqplz/private/cleanmatepro-files`).
4. Move `license_private.key` out of it into `private`
   (→ `/home/qlixbzqplz/private/license_private.key`).
5. Check: item pictures show, Super admin → Apps and downloads lists the apps, Super admin →
   Offline licences says the key is ready.

The old `DINEPAD_DATA=/home/qlixbzqplz/cleanmatepro-files` line in `.env` can stay: when that
folder is gone the server uses `private/cleanmatepro-files` (a folder named
`private/cleanmate-data` works too). `DINEPAD_DATA` and
`LICENSE_PRIVATE_KEY_FILE=/home/qlixbzqplz/private/license_private.key` still win when they
point at folders and files that exist.

Keep a copy of `license_private.key` off the server (password manager or encrypted drive):
offline apps already sold only accept keys signed with it, and it cannot be made again.

## 7. Add the cron job (campaigns, e-invoices, devices, backups, renewal invoices, CRM reminders)

cPanel → **Cron Jobs** → **Add New Cron Job**:

| Box | Type |
|---|---|
| Common Settings | **Once Per Minute** (`* * * * *`) |
| Command | `/opt/cpanel/ea-php83/root/usr/bin/php /home/qlixbzqplz/cleanmatepro/artisan schedule:run >> /dev/null 2>&1` |

→ **Add New Cron Job**.

If your host uses **Select PHP Version** (CloudLinux), use this command instead:
`/usr/local/bin/php /home/qlixbzqplz/cleanmatepro/artisan schedule:run >> /dev/null 2>&1`

## 8. Moving data from the CleanMate Node.js server (only if you used it)

Skip this step if this is your first CleanMate server. If you already ran
CleanMate on cPanel with Node.js (`deploy/CPANEL_DEPLOY.md`), its data is in
`/home/qlixbzqplz/cleanmatepro-data`. Do this at a quiet time:

1. cPanel → **Setup Node.js App** → the CleanMate app → **Stop App**.
   (Tills and van phones keep working offline and send their sales later.)
2. cPanel → **Terminal** (under Advanced) and type:

   ```bash
   /opt/cpanel/ea-php83/root/usr/bin/php /home/qlixbzqplz/cleanmatepro/artisan dinepad:import-sqlite /home/qlixbzqplz/cleanmatepro-data
   ```

   At the end it says how many businesses and rows it copied.

   No **Terminal** in your cPanel? Add a cron job set to **Once Per Minute**
   with that same command, wait two minutes, then **delete** that cron job.
3. Open the dashboard, sign in with your usual email and password, and check a
   store's sales. Tills, phones and staff PINs keep working: nobody needs to
   sign in again.
4. When you are happy (after a few days), cPanel → **Setup Node.js App** →
   **Delete** the old app. Keep `/home/qlixbzqplz/cleanmatepro-data` as a backup.

## 9. Updating later

1. Build a new zip (step 1).
2. File Manager → upload it to `/home/qlixbzqplz` → **Extract** → when asked,
   allow it to **overwrite** files.
3. Your `.env` would be overwritten too: open `cleanmatepro/.env` and type the
   database password and your secret word again (step 5). *(Tip: before extracting, copy `.env` to
   `/home/qlixbzqplz/env-backup.txt`, and copy it back afterwards.)*

New tables and columns are added automatically on the next visit. Your data
in MySQL and in `cleanmatepro-files` (or `private/cleanmatepro-files`) is never touched by an update.

---

## If something goes wrong

| What you see | What to do |
|---|---|
| **500 Internal Server Error** | Open `cleanmatepro/storage/logs/laravel.log` in File Manager and send me the last lines. Most often the database password in `.env` is wrong. |
| **"Access denied for user"** in the log | Step 3: the user was not added to the database with ALL PRIVILEGES, or the password in `.env` is different. |
| A page of code, or the folder list | The Document Root (step 6) is not `/home/qlixbzqplz/cleanmatepro/public`. |
| **"composer"** or **"vendor"** missing | The zip was not fully extracted: delete `cleanmatepro` and extract again. |
| Dashboard shows but sign-in says *Server not reachable* | Check `https://laundry.tapiyo.com/api/health` works; HTTPS must be on (step 6.4). |
| Campaigns / ZATCA / backups never run | Step 7: check the cron command; cPanel → Cron Jobs shows it once per minute. |
| PHP version error | Step 2: the domain must use PHP 8.3 (not 8.1 or 8.2). |
| Super admin: "Wrong email or password" on the normal sign-in page | That is on purpose. Use your secret link `https://laundry.tapiyo.com/<your secret word>` (step 5). Forgot the word? Open `cleanmatepro/.env` and look at `ADMIN_LOGIN_PATH`. |
| Offline licences: "signing key is missing" | Upload `license_private.key` into `cleanmatepro-files`, or into `/home/qlixbzqplz/private` (step 6, Offline licence keys). |
| Uploading a big picture or file fails | The PHP limits come from `cleanmatepro/public/.user.ini` (64 MB). Some hosts ignore it: cPanel → **MultiPHP INI Editor** → that domain → `upload_max_filesize` and `post_max_size` = `64M`. |

Your host must have **MySQL 8** or **MariaDB 10.5 or newer** (cPanel →
**MySQL Databases** shows the version at the bottom of cPanel's home page,
"Server Information").
