isaaccladandCursor
ea51b49342
Deploy Ladill Mini / deploy (push) Successful in 40s
Expose /.well-known/assetlinks.json from env-configured Play app signing fingerprints so mini.ladill.com passes Play Console deep link domain checks. Co-authored-by: Cursor <cursoragent@cursor.com>
122 lines
4.0 KiB
Markdown
122 lines
4.0 KiB
Markdown
# Ladill Mini — deploy & cutover runbook
|
||
|
||
Standalone app for **trader payment QRs** at `mini.ladill.com` — static scan-to-pay
|
||
codes with amount entry, no catalog. Takings 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 payment codes to this app (see
|
||
`MiniQrForwarder` on the monolith); grant the platform DB user read access:
|
||
|
||
```bash
|
||
sudo mysql -e "GRANT SELECT ON ladill_mini.qr_codes TO 'ladilldb'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
||
```
|
||
|
||
Set `MINI_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_MINI` | platform `.env` + this app |
|
||
| `PAY_API_KEY_MINI` | platform `.env` (`PAY_API_KEY_MINI`) + this app — Ladill Pay checkout |
|
||
| `IDENTITY_API_KEY_MINI` | platform `.env` + this app |
|
||
| `PLATFORM_DB_*` | read `ladilldb.platform_settings` (Paystack keys from admin → Billing) |
|
||
|
||
Paystack credentials are **not** duplicated in this app’s `.env`. They are
|
||
configured in the platform admin panel (`/admin/settings` → Billing) and read
|
||
at runtime from `platform_settings` via the `platform` DB connection.
|
||
Grant the app DB user `SELECT` on `ladilldb.platform_settings` only.
|
||
|
||
## 1. Gitea repo + CI
|
||
|
||
1. Repo: **ladill-mini** (create on Gitea)
|
||
2. Push to `main` triggers `.gitea/workflows/deploy.yml`.
|
||
3. App root: `/var/www/ladill-mini`
|
||
|
||
## 2. Server app-slot + database
|
||
|
||
```bash
|
||
sudo install -d -o deploy -g www-data /var/www/ladill-mini
|
||
sudo install -d -o deploy -g www-data /var/www/ladill-mini/{releases,shared}
|
||
sudo mysql -e "CREATE DATABASE ladill_mini CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||
sudo mysql -e "CREATE USER 'ladill_mini'@'127.0.0.1' IDENTIFIED BY '<pw>';"
|
||
sudo mysql -e "GRANT ALL ON ladill_mini.* TO 'ladill_mini'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
||
sudo mysql -e "GRANT SELECT ON ladilldb.platform_settings TO 'ladill_mini'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
||
```
|
||
|
||
The Gitea deploy runner acts as `deploy`. The app root and `current` symlink must be
|
||
owned by `deploy` (not root), or the release switch step will fail with
|
||
`sudo: a password is required`.
|
||
|
||
## 3. Register OIDC client (platform)
|
||
|
||
```bash
|
||
php artisan passport:client \
|
||
--name="Ladill Mini" \
|
||
--redirect_uri="https://mini.ladill.com/sso/callback"
|
||
```
|
||
|
||
## 4. Platform integration
|
||
|
||
```env
|
||
BILLING_API_KEY_MINI=<same>
|
||
IDENTITY_API_KEY_MINI=<same>
|
||
RP_MINI_FRONTCHANNEL_LOGOUT=https://mini.ladill.com/sso/logout-frontchannel
|
||
LADILL_MINI_APP_URL=https://mini.ladill.com
|
||
```
|
||
|
||
Add `mini` to `config/pdns.php` service subdomains (done in monolith).
|
||
|
||
## 5. nginx + TLS
|
||
|
||
```bash
|
||
sudo deployment/setup-service-subdomain-nginx.sh mini --app /var/www/ladill-mini/current
|
||
```
|
||
|
||
## 6. First deploy
|
||
|
||
```bash
|
||
cd /var/www/ladill-mini/current
|
||
php artisan migrate --force
|
||
php artisan config:cache route:cache view:cache
|
||
```
|
||
|
||
## 7. Android App Links
|
||
|
||
Add the **App signing certificate** SHA-256 fingerprint from Play Console
|
||
(Setup → App signing) to production `.env`:
|
||
|
||
```env
|
||
ANDROID_APP_PACKAGE=com.ladill.mini
|
||
ANDROID_APP_SHA256_FINGERPRINTS=AA:BB:CC:...
|
||
```
|
||
|
||
After deploy, confirm:
|
||
|
||
```bash
|
||
curl -sS https://mini.ladill.com/.well-known/assetlinks.json | jq .
|
||
```
|
||
|
||
Then re-check deep links in Play Console (App content → Deep links). Users may
|
||
need an app update after verification passes.
|
||
|
||
## 8. Verify
|
||
|
||
- SSO login at `mini.ladill.com`
|
||
- Create a payment QR, download PNG
|
||
- Scan `/q/<code>`, pay test amount, confirm wallet credit (net of 3.5%)
|
||
- Withdraw from `account.ladill.com/wallet`
|
||
|
||
## Product IA (blueprint)
|
||
|
||
- **Overview** — today's takings, payment count, wallet balance
|
||
- **My Payment QR** — print/display static QRs (one per till/branch)
|
||
- **Payments** — incoming payment feed
|
||
- **Payouts** — wallet-first settlement, withdraw to bank/MoMo
|
||
- **Settings** — business branding (no Developers by default)
|