# Ladill Give — deploy & cutover runbook

Standalone app for **online giving pages** at `give.ladill.com` — branded donation
pages with collection categories (Offering, Tithe, Building Fund…). Donations
settle into the one platform UserWallet (3.5% fee), then withdraw via
`account.ladill.com`.

Public scans stay at `ladill.com/q/<code>` (blueprint decision — printed codes
never migrate). The platform host forwards church/giving codes to this app (see
`GiveQrForwarder` on the monolith); grant the platform DB user read access:

```bash
sudo mysql -e "GRANT SELECT ON ladill_give.qr_codes TO 'ladilldb'@'127.0.0.1'; FLUSH PRIVILEGES;"
```

Set `GIVE_DB_*` on the platform `.env` if the lookup user differs from the
main app DB user.

---

## 0. Prerequisites

| Secret | Where |
|---|---|
| `LADILL_SSO_CLIENT_ID` / `LADILL_SSO_CLIENT_SECRET` | `passport:client` on platform |
| `BILLING_API_KEY_GIVE` | platform `.env` + this app |
| `PAY_API_KEY_GIVE` | platform `.env` + this app — Ladill Pay checkout (3.5% donations tier) |
| `IDENTITY_API_KEY_GIVE` | platform `.env` + this app |
| `PLATFORM_DB_*` | read `ladilldb.platform_settings` (Paystack keys from admin → Billing) |

## 1. Gitea repo + CI

1. Repo: **ladill-give** (create on Gitea)
2. Push to `main` triggers `.gitea/workflows/deploy.yml`.
3. App root: `/var/www/ladill-give`

## 2. Server app-slot + database

```bash
sudo install -d -o deploy -g www-data /var/www/ladill-give
sudo install -d -o deploy -g www-data /var/www/ladill-give/{releases,shared}
sudo mysql -e "CREATE DATABASE ladill_give CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'ladill_give'@'127.0.0.1' IDENTIFIED BY '<pw>';"
sudo mysql -e "GRANT ALL ON ladill_give.* TO 'ladill_give'@'127.0.0.1'; FLUSH PRIVILEGES;"
sudo mysql -e "GRANT SELECT ON ladilldb.platform_settings TO 'ladill_give'@'127.0.0.1'; FLUSH PRIVILEGES;"
```

## 3. Register OIDC client (platform)

```bash
php artisan passport:client \
  --name="Ladill Give" \
  --redirect_uri="https://give.ladill.com/sso/callback"
```

## 4. Platform integration

```env
BILLING_API_KEY_GIVE=<same>
IDENTITY_API_KEY_GIVE=<same>
PAY_API_KEY_GIVE=<same>
RP_GIVE_FRONTCHANNEL_LOGOUT=https://give.ladill.com/sso/logout-frontchannel
LADILL_GIVE_APP_URL=https://give.ladill.com
GIVE_DB_DATABASE=ladill_give
```

Add `give` to `config/pdns.php` service subdomains.

## 5. nginx + TLS

```bash
sudo deployment/setup-service-subdomain-nginx.sh give --app /var/www/ladill-give/current
```

## 6. First deploy

```bash
cd /var/www/ladill-give/current
php artisan migrate --force
php artisan config:cache route:cache view:cache
```

## 7. Verify

- SSO login at `give.ladill.com`
- Create a giving page, download QR PNG
- Scan `/q/<code>`, give test amount, confirm wallet credit (net of 3.5%)
- Withdraw from `account.ladill.com/wallet`

## Product IA (blueprint)

- **Overview** — total raised, donors, active causes, recent donations
- **Giving Pages** — create/manage branded giving pages + QR
- **Donations** — incoming donation feed
- **Payouts** — wallet-first settlement, withdraw to bank/MoMo
- **Settings** — organisation profile