# Deploying to cPanel

Written for lighthouseit.nz, putting the new app **alongside** the existing
WordPress site so nothing breaks while you try it.

WordPress stays exactly where it is at `lotto.lighthouseit.nz`. The new app gets
its own subdomain. Once you are happy with it, switching over is one setting.

**Everything here is done in cPanel screens and a web browser.** No SSH, no
command line, no terminal. Where a shortcut exists for hosting that does have a
command line, it is in a note at the end.

Work through the steps in order. Steps 1–3 can be done in any order, but 4
onwards depend on the ones before.

---

## What you need before you start

- Your cPanel login
- The file `lotto-syndicate-app-deploy.zip`
- Somewhere to note down four things as you go: database name, database user,
  database password, mailbox password. A password manager is ideal.

Set aside about half an hour.

---

## 1. Set the PHP version

**cPanel → MultiPHP Manager** (under *Software*).

1. Tick the box next to `lighthouseit.nz`.
2. In *PHP Version*, choose **PHP 8.2** (or 8.3).
3. Click **Apply**.

The app needs 8.1 or newer. If your only options are older than that, stop here
and ask your host to enable a newer PHP — nothing later will work without it.

---

## 2. Create the database

**cPanel → MySQL Databases** (under *Databases*).

**a. Create the database**

In *Create New Database*, type `lotto` and click **Create Database**.

cPanel adds your account prefix, so the real name becomes something like
`lighthou_lotto`. **Write down the full name including the prefix.**

Click **Go Back**.

**b. Create the user**

Scroll to *MySQL Users → Add New User*.

- Username: `lottoapp` (becomes `lighthou_lottoapp`)
- Click **Password Generator**, then **Use Password**, and **copy the password
  somewhere safe before closing the box** — you cannot see it again
- Click **Create User**, then **Go Back**

**c. Join them together**

Scroll to *Add User To Database*.

- User: the one you just made
- Database: the one you just made
- Click **Add**
- On the privileges screen, tick **ALL PRIVILEGES**, then **Make Changes**

You should now have three things written down: database name, user name,
password.

---

## 3. Create the mailbox the app sends from

**cPanel → Email Accounts** (under *Email*) **→ Create**.

- Username: `lotto`, domain `lighthouseit.nz`
- Set a password with the generator and **write it down**
- Click **Create**

This mailbox is what the app logs into to send member emails. Replies from
members arrive here, so it is worth checking occasionally.

---

## 4. Upload the app

**cPanel → File Manager** (under *Files*).

The app goes **outside** `public_html`. This matters: it is what stops anyone
fetching `config.php`, which will hold your database and mailbox passwords.

1. In the left-hand tree, click your **home directory** — the top entry, usually
   `/home/lighthou`. Make sure you are **not** inside `public_html`.
2. Click **+ Folder** in the toolbar, name it `lotto-app`, and click
   *Create New Folder*.
3. Double-click into `lotto-app`.
4. Click **Upload** in the toolbar, choose `lotto-syndicate-app-deploy.zip`,
   and wait for it to reach 100%.
5. Click **Go Back to /home/lighthou/lotto-app**.
6. Right-click the zip → **Extract** → **Extract Files**.
7. Once it finishes, right-click the zip → **Delete**.

You should now see these inside `lotto-app`: `app`, `bin`, `migrations`,
`public`, `schema.sql`, `README.md`, `DEPLOY.md`.

> If Extract produced a single folder with everything inside it, open that
> folder, select all its contents, and **Move** them up one level into
> `lotto-app` so the layout matches the list above.

---

## 5. Point a subdomain at it

**cPanel → Domains → Create A New Domain.**
(Older cPanel: **Subdomains** instead.)

- **Domain:** `lotto2.lighthouseit.nz`
  (temporary — the real address stays with WordPress for now)
- **Untick** *Share document root*
- **Document Root:** `/home/lighthou/lotto-app/public`

Click **Submit**.

The document root must end in **`/public`**. Pointing it at `lotto-app` itself
would expose your config file to the internet.

DNS may take a few minutes. If the address does not respond straight away, give
it ten minutes before worrying.

---

## 6. Import the database structure

**cPanel → phpMyAdmin** (under *Databases*).

1. In the left-hand list, click your database (`lighthou_lotto`).
2. Click the **Import** tab at the top.
3. **Choose File** → select `schema.sql`.
   It is on your own computer inside the zip — unzip it locally to get at it,
   or download it from `lotto-app` using File Manager's *Download* button.
4. Scroll down and click **Import** (older versions: **Go**).

You should see a green success message, and **10 tables** appear in the
left-hand list.

---

## 7. Write the settings file

**cPanel → File Manager**, go to `/home/lighthou/lotto-app/app/`.

**a. Make the file**

Right-click `config.example.php` → **Copy** → set the path to
`/home/lighthou/lotto-app/app/config.php` → **Copy File**.

**b. Get a random key**

Open https://www.random.org/strings/ and generate one 32-character string, or
just mash a keyboard for 40+ characters. Anything long and random will do. You
need it twice: once in the file, once in step 8.

**c. Edit it**

Right-click `config.php` → **Edit** → **Edit** again if it warns about encoding.

Change these lines, leaving everything else alone:

```php
'base_url' => 'https://lotto2.lighthouseit.nz',

'app_key' => 'PASTE-YOUR-LONG-RANDOM-STRING-HERE',

'db' => [
    'host'     => 'localhost',
    'port'     => 3306,
    'name'     => 'lighthou_lotto',       // from step 2a
    'user'     => 'lighthou_lottoapp',    // from step 2b
    'password' => 'your-db-password',     // from step 2b
    'charset'  => 'utf8mb4',
],

'mail' => [
    'host'       => 'mail.lighthouseit.nz',
    'port'       => 587,
    'encryption' => 'tls',
    'username'   => 'lotto@lighthouseit.nz',
    'password'   => 'your-mailbox-password',   // from step 3
    'from_email' => 'lotto@lighthouseit.nz',
    'from_name'  => 'Lotto Syndicate',
    'reply_to'   => 'lotto@lighthouseit.nz',
    'enabled'    => true,
    'timeout'    => 20,
    'verify_peer' => true,
],
```

Click **Save Changes**.

Watch for three things: keep every quote and comma exactly as they are, do not
let the editor turn straight quotes into curly ones, and make sure `base_url`
matches your subdomain with no trailing slash.

---

## 8. Run the setup page

In your browser: **https://lotto2.lighthouseit.nz/install.php**

This checks the server and tells you plainly what, if anything, is wrong.

**If every row says OK**, fill in the form:

- **app_key** — paste the same random string you put in `config.php`
- **Username** — what you will log in with, e.g. `ron`
- **Password** — at least 12 characters

Click **Create login**.

**If a row says PROBLEM**, fix it and reload:

| It says | Do this |
|---|---|
| PHP version too old | Go back to step 1 |
| Database connection failed | Check the four `db` values in `config.php` against step 2 |
| Schema imported — missing tables | Redo step 6 |
| uploads/tickets not writable | File Manager → right-click the folder → **Change Permissions** → `755` |
| app_key still the default | You did not save `config.php`, or edited the wrong copy |

**If you get a blank white page**, the config file has a typo. Set
`'debug' => true` in `config.php`, reload to see the error, fix it, then set it
back to `false`.

**Finally: delete `public/install.php`** in File Manager. It disables itself
once your login exists, but do not leave it there.

---

## 9. Prove email works

Sign in at **https://lotto2.lighthouseit.nz**, go to **Email log**, put your own
address in the test box and click **Send test**.

Do not go further until a message arrives. Everything members see depends on it.

| Error mentions | Fix in `config.php` |
|---|---|
| connection refused, timed out | `'port' => 465` and `'encryption' => 'ssl'` |
| authentication failed | Mailbox password does not match step 3 |
| certificate, STARTTLS | Try `'host' => 'localhost'`; failing that `'verify_peer' => false` |

Check the spam folder before concluding it did not send.

---

## 10. Set up the daily task

**cPanel → Cron Jobs** (under *Advanced*). This is a web form — no terminal
needed.

Under *Add New Cron Job*:

- **Common Settings:** *Once Per Day (0 0 * * *)*, then change **Hour** to `7`
- **Command:**

```
/usr/local/bin/php /home/lighthou/lotto-app/bin/cron.php --quiet >> /home/lighthou/lotto-app/cron.log 2>&1
```

Click **Add New Cron Job**.

The setup page in step 8 showed the exact PHP path it detected — use that if it
differs from `/usr/local/bin/php`. If cron emails you an error about the
command not being found, try `/opt/cpanel/ea-php82/root/usr/bin/php` instead.

This creates each day's draws and emails the members. The app also catches up on
its own whenever you open it, so a missed run is not a disaster — cron just
means the emails go out in the morning rather than when you next log in.

---

## 11. Set it up for real

1. **Syndicates → New syndicate.** Name, draw days, **cost per draw**, where
   winnings go. Save, then upload the **subscription ticket** image.
2. **Members → Add member** for each person, entering their current balances
   from the old site as opening balances.
3. Repeat for the second syndicate.
4. Check the dashboard shows no warnings.

Then let it run alongside WordPress for a draw or two. Confirm the emails
arrive, and that the results maths matches what you would have worked out by
hand.

---

## 12. Switching over, when you are ready

**cPanel → Domains.** Change the document root of `lotto.lighthouseit.nz` to
`/home/lighthou/lotto-app/public`.

Then edit `config.php` and set `'base_url' => 'https://lotto.lighthouseit.nz'`.

Finally, remove the `lotto2` subdomain.

Keep the WordPress files and a database dump until you are certain. Disk is
cheap and second thoughts are common.

---

## Updating the app later

Download the new zip, then in File Manager:

1. Upload it into `/home/lighthou/lotto-app/`.
2. Right-click → **Extract**, and let it overwrite.
3. Delete the zip.

`app/config.php` and everything in `public/uploads/` are **not** in the zip, so
your settings and every ticket photo are left alone.

If an update includes a database change there will be a new file in
`migrations/`. Take a backup first (**phpMyAdmin → Export**), then apply it the
same way as step 6, choosing the migration file instead of `schema.sql`.

---

## Afterwards

**Back up.** cPanel → *Backup Wizard*, or ask your host to enable nightly
backups. The database is what matters — the code can always be re-uploaded.

**Keep `config.php` private.** It holds your database and mailbox passwords. It
is already unreachable because the document root points at `public/`, and
`app/.htaccess` denies it even if that ever changes.

**Watch the first few draws.** The Email log page shows every message and any
failure, and the dashboard warns you if the scheduled task stops running.

---

## If you later get SSH access

Everything above still works. SSH would let you skip the zip and clone the repo
instead, so updates become a single `git pull`:

- Repo: `git@github.com:RubyRonS/lotto-syndicate-app.git` (private)
- Add a **read-only** deploy key on the server, under the repo's
  *Settings → Deploy keys*
- `php bin/setup.php check`, `adduser` and `testmail` replace `install.php` and
  the test-email button

Note that cPanel **Terminal** and **SSH access** are separate features — some
hosts disable Terminal but still allow SSH from your own computer. Worth asking
your host if you would rather work that way.