ladill-mini/DEPLOY.md

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:

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

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)

php artisan passport:client \
  --name="Ladill Mini" \
  --redirect_uri="https://mini.ladill.com/sso/callback"

4. Platform integration

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

sudo deployment/setup-service-subdomain-nginx.sh mini --app /var/www/ladill-mini/current

6. First deploy

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:

ANDROID_APP_PACKAGE=com.ladill.mini
ANDROID_APP_SHA256_FINGERPRINTS=AA:BB:CC:...

After deploy, confirm:

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)