# Deploying TrustFund on a DigitalOcean Droplet

Target: Ubuntu 24.04 droplet, Nginx + PHP 8.3 (FPM) + MariaDB, free HTTPS from Let's Encrypt.
Estimated time: 30 to 45 minutes. Replace `your-domain.com` everywhere with your real domain.

> **Before real money moves:** the app ships with a *simulated* payment gateway (every payment "succeeds").
> Do not take real donations until a real gateway is connected (section 8) and you have taken legal advice
> on holding donations in escrow and any fundraising licence required in Malaysia.

## 1. Create the droplet and point your domain

1. In DigitalOcean create an Ubuntu 24.04 droplet (the 1 GB / 1 vCPU size is enough to start). Use an SSH key, not a password.
2. At your domain registrar, create an **A record** for `your-domain.com` pointing to the droplet's IP address.
3. Log in: `ssh root@YOUR_DROPLET_IP`

## 2. Basic server hardening

```bash
adduser deploy && usermod -aG sudo deploy          # then log in as "deploy" from now on
rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy
ufw allow OpenSSH && ufw allow 'Nginx Full' && ufw enable
apt update && apt upgrade -y
```

## 3. Install the software

```bash
sudo apt install -y nginx mariadb-server php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml unzip certbot python3-certbot-nginx
sudo mysql_secure_installation          # answer Y to the questions, set a root password
```

## 4. Create the database

```bash
sudo mysql
```
```sql
CREATE DATABASE trustfund CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'trustfund'@'localhost' IDENTIFIED BY 'PUT_A_LONG_RANDOM_PASSWORD_HERE';
GRANT ALL PRIVILEGES ON trustfund.* TO 'trustfund'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

## 5. Upload and configure the app

Upload `trustfund.zip` to the droplet (for example `scp trustfund.zip deploy@YOUR_DROPLET_IP:~`), then:

```bash
sudo mkdir -p /var/www/trustfund
sudo unzip ~/trustfund.zip -d /var/www/trustfund
cd /var/www/trustfund
sudo cp config.local.example.php config.local.php
sudo nano config.local.php            # set the database password, mail_from and app_name
sudo mkdir -p storage/uploads
sudo chown -R www-data:www-data storage
sudo chmod 640 config.local.php && sudo chown root:www-data config.local.php
```

Create the tables and your first admin account (use your own email and a strong password of 12+ characters;
**do not** run the `--demo` option on a real server):

```bash
sudo -u www-data php bin/install.php --admin-name='Your Name' --admin-email='you@your-domain.com' --admin-password='A-Long-Passphrase-Here'
```

If you see `WARNING: Could not create ledger_no_update trigger`, MariaDB has binary logging on. Fix it with
`sudo mysql -e "SET GLOBAL log_bin_trust_function_creators = 1;"`, add `log_bin_trust_function_creators=1` under `[mysqld]`
in `/etc/mysql/mariadb.conf.d/50-server.cnf`, then run the install command again (it is safe to repeat).

## 6. Configure PHP uploads and Nginx

Allow evidence uploads of up to 5 MB:

```bash
sudo nano /etc/php/8.3/fpm/conf.d/90-trustfund.ini
```
```ini
upload_max_filesize = 6M
post_max_size = 8M
expose_php = Off
session.cookie_httponly = 1
session.cookie_samesite = Lax
```
```bash
sudo systemctl restart php8.3-fpm
```

Create the site: `sudo nano /etc/nginx/sites-available/trustfund`

```nginx
server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    root /var/www/trustfund/public;
    index index.php;
    client_max_body_size 8M;

    location / {
        try_files $uri /index.php?$query_string;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ /\. { deny all; }
}
```

```bash
sudo ln -s /etc/nginx/sites-available/trustfund /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
```

Only `public/` is served. The code, config, database password and uploaded evidence live outside the web root.

## 7. Turn on HTTPS and test

```bash
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
```

Visit `https://your-domain.com`, log in with the admin account, then:

1. **Users page:** create an auditor account.
2. Register a test recipient in a private window; approve it from the admin dashboard.
3. As that recipient create a small campaign; approve it as admin and assign the auditor.
4. Register a test donor, donate, and confirm stage 1 is released.
5. As the recipient submit a spending report; as the auditor approve it; confirm stage 2 is released after more donations.
6. Open the ledger page and confirm it says "Integrity check passed".

## 8. Connecting your payment gateway

All payment code is in `src/gateway.php`. The rest of the app does not change.

1. Add a class (e.g. `BillplzGateway`) that implements `PaymentGateway`:
   * `createPayment()`: create the bill/order at the gateway and return `status => 'pending'` and the `redirect_url` of the gateway's payment page.
   * `parseWebhook()`: **verify the gateway's signature** (reject anything unsigned), then return the donation id, the gateway reference and whether it was paid.
2. Register the class in `gateway()` and set `'payment_gateway' => 'billplz'` plus your API keys in `config.local.php`.
3. In the gateway dashboard set the callback URL to `https://your-domain.com/webhook/payment`.
4. Money is only credited when the webhook confirms payment (`confirm_donation()` ignores repeats safely).
5. Test in the gateway's sandbox first, including a failed payment and a repeated webhook.

Refunds in this app update the ledger and escrow balance only; send the money back to the donor in your gateway dashboard.

## 9. Backups and maintenance

* Turn on DigitalOcean **Backups** for the droplet (about 20% of the droplet price).
* Add a nightly database dump and keep copies off the server (also copy `/var/www/trustfund/storage/uploads`):
  `mysqldump trustfund | gzip > /root/backup/trustfund-$(date +%F).sql.gz`
* Keep the server updated: `sudo apt update && sudo apt upgrade`; consider `unattended-upgrades`.
* Emails: by default the app writes emails to `storage/mail.log`. To send real email, set `'mail_enabled' => true` and
  configure an SMTP relay (for example install `msmtp` for PHP's `mail()`), or ask a developer to add a mailer library.
* Never edit or delete rows in the `ledger` table. If a fix is needed, add a corrective entry through the app.

## Troubleshooting

| Problem | What to check |
| --- | --- |
| White page or "Something went wrong" | `sudo tail -50 /var/log/nginx/error.log` and `/var/log/php8.3-fpm.log` |
| Cannot connect to database | Password and database name in `config.local.php`; `sudo systemctl status mariadb` |
| Upload fails | `upload_max_filesize` / `post_max_size` and Nginx `client_max_body_size` (section 6) |
| Uploads or emails fail with permission errors | `sudo chown -R www-data:www-data /var/www/trustfund/storage` |
| Login loops back to the login page | Open the site over HTTPS (cookies are marked secure when HTTPS is on) |
