# Installing TrustFund on cPanel hosting (no command line needed)

Everything below is done in your cPanel in a web browser. Estimated time: 20 to 30 minutes.

**Your host needs:** PHP 8.1 or newer, MySQL or MariaDB, and free SSL (AutoSSL). Almost every cPanel host has these.
`shared hosting` is fine for a first launch. Pick a reputable host, because this site holds people's donation records.

> The simulated payment gateway is still switched on. Do not take real donations until your real gateway is connected
> (`DEPLOY.md`, section 8) and you have taken legal advice.

## Step 1. Choose PHP 8.1 or newer

1. cPanel > **MultiPHP Manager** > tick your domain > choose **PHP 8.1** (or newer) > **Apply**.
2. cPanel > **Select PHP Version** > **Extensions** (if your host has it): make sure **pdo_mysql**, **mbstring** and **fileinfo** are ticked.
3. cPanel > **MultiPHP INI Editor** > your domain: set `upload_max_filesize` to **6M** and `post_max_size` to **8M** (evidence uploads allow 5 MB).

## Step 2. Create the database

1. cPanel > **MySQL Database Wizard**.
2. Step 1: name the database `trustfund`. cPanel adds your account name in front, for example `myacct_trustfund`. Write it down.
3. Step 2: create a user (for example `tfuser`) and a long random password. Write both down (you get `myacct_tfuser`).
4. Step 3: tick **ALL PRIVILEGES** and finish.

## Step 3. Upload the app

Choose **one** of the two layouts. Layout A is cleaner and safer.

### Layout A (recommended): a subdomain such as `donate.your-domain.com`

1. cPanel > **File Manager** > go to your home folder (`/home/myacct`, **not** `public_html`) > **+ Folder** > name it `trustfund`.
2. Open `trustfund` > **Upload** `trustfund.zip` > select it > **Extract**. You should now see `public`, `src`, `views` and `config.php` directly inside `trustfund`.
3. cPanel > **Domains** > **Create A New Domain** (or **Subdomains** on older cPanel). Enter `donate.your-domain.com`, un-tick "Share document root", and set the document root to **`trustfund/public`** (that is `/home/myacct/trustfund/public`).

### Layout B: the main domain (`public_html`)

1. Do steps 1 and 2 of Layout A (extract into `/home/myacct/trustfund`).
2. In File Manager open `trustfund/public`, **Select All**, **Copy** into `public_html` (the folder must contain `index.php`, `install.php`, `assets` and the hidden file `.htaccess`).
3. In `public_html` copy `app-root.example.php` to **`app-root.php`** and edit it so it reads your real app path, for example
   `return '/home/myacct/trustfund';`

> **Hidden files:** File Manager > **Settings** > tick **Show Hidden Files (dotfiles)**. The `.htaccess` files in `public`, `storage`,
> `src`, `views` and `bin` must exist; they make the site work and keep private folders closed. Zip extraction keeps them.
> If you upload by FTP instead, make sure your FTP program uploads hidden files.

## Step 4. Settings file

1. In File Manager open the `trustfund` folder. **Copy** `config.local.cpanel.example.php` to **`config.local.php`**.
2. **Edit** `config.local.php` and fill in:
   * `db` > `name`, `user`, `pass`: the three values from Step 2
   * `install_key`: type a long random text (16+ characters). You will need it once, in Step 5
   * `mail_from`: a real email address on your domain (create one in cPanel > **Email Accounts** if needed)
3. Right-click `config.local.php` > **Permissions** > set **640** (or 600).

## Step 5. Run the web installer

1. Open `https://donate.your-domain.com/install.php` (use your own address; Layout B is `https://your-domain.com/install.php`).
2. The **Server check** table must show all **OK**. Anything marked **Fix** tells you what to change; fix it and refresh.
   (A **Warning** about HTTPS means SSL is not on yet. Do Step 6 first and reopen the page over `https://`.)
3. Fill in the install key, your name, your email and a strong password (12+ characters) > **Install**.
4. If the installer says it could not create the ledger "append-only" triggers, that is normal on some shared hosts.
   The ledger is still protected by its tamper-detecting hash chain; ask your host if you want the extra database lock turned on.
5. **Immediately:** delete `install.php` from the public folder, and delete the `install_key` line from `config.local.php`.

## Step 6. Turn on HTTPS

cPanel > **SSL/TLS Status** > tick the domain > **Run AutoSSL**. When the padlock works, open `public/.htaccess` (or `public_html/.htaccess`)
in File Manager and remove the `#` in front of the two `RewriteCond` / `RewriteRule` lines under "force HTTPS", so every visit uses `https://`.

## Step 7. Try it

Log in with the admin account you just created and follow the checklist in `DEPLOY.md` section 7 (create an auditor, register a test
recipient and a test donor, run one donation through approval, release and audit). The ledger page should say "Integrity check passed".

## Backups and upkeep

* cPanel > **Backup** (or **JetBackup**): download or schedule a full backup. At minimum back up the database (**phpMyAdmin > Export**) **and**
  the folder `trustfund/storage/uploads` (the evidence files). Keep copies somewhere other than this hosting account.
* Keep PHP updated through MultiPHP Manager; the app works on newer PHP versions.
* Never edit or delete rows in the `ledger` table. If a correction is needed, add one through the app.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| "500 Internal Server Error" | Open the `error_log` file in the public folder (File Manager), or cPanel > **Errors**. Often it is the PHP version (Step 1) or a typo in `config.local.php` |
| Home page works but every other page is "not found" | The `.htaccess` file in the public folder is missing (show hidden files and re-copy it) |
| White page or "Something went wrong" | Set `'debug' => true` in `config.local.php`, reload, read the message, then set it back to `false` |
| Server check says the database connection failed | Re-check the three database values; remember the account-name prefix (`myacct_`) and that Step 2 gave the user ALL PRIVILEGES |
| Uploading evidence fails | Raise `upload_max_filesize` and `post_max_size` (Step 1) |
| Emails never arrive | Use a real `mail_from` address on your domain; check spam folders; ask your host whether PHP `mail()` is allowed |
| Login keeps returning to the login page | Use the `https://` address consistently (the session cookie is marked secure on HTTPS) |
