isaaccladandCursor
f718b9cfbf
Shop, menu, and booking storefronts with OIDC SSO, Pay checkout, and merchant.ladill.com deployment workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# Ladill Merchant — deploy & cutover runbook
|
|
|
|
Standalone app for **shop, menu & booking storefronts** at `merchant.ladill.com` — QR
|
|
storefronts with catalog checkout. Sales settle into the one platform UserWallet
|
|
(15% 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 shop/menu/booking codes to this app (see
|
|
`MerchantQrForwarder` on the monolith); grant the platform DB user read access:
|
|
|
|
```bash
|
|
sudo mysql -e "GRANT SELECT ON ladill_merchant.qr_codes TO 'ladilldb'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
|
```
|
|
|
|
Set `MERCHANT_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_MERCHANT` | platform `.env` + this app |
|
|
| `PAY_API_KEY_MERCHANT` | platform `.env` + this app — Ladill Pay checkout (15% sales tier) |
|
|
| `IDENTITY_API_KEY_MERCHANT` | platform `.env` + this app |
|
|
| `PLATFORM_DB_*` | read `ladilldb.platform_settings` (Paystack keys from admin → Billing) |
|
|
|
|
## 1. Gitea repo + CI
|
|
|
|
1. Repo: **ladill-merchant** (create on Gitea)
|
|
2. Push to `main` triggers `.gitea/workflows/deploy.yml`.
|
|
3. App root: `/var/www/ladill-merchant`
|
|
|
|
## 2. Server app-slot + database
|
|
|
|
```bash
|
|
sudo install -d -o deploy -g www-data /var/www/ladill-merchant
|
|
sudo install -d -o deploy -g www-data /var/www/ladill-merchant/{releases,shared}
|
|
sudo mysql -e "CREATE DATABASE ladill_merchant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
|
sudo mysql -e "CREATE USER 'ladill_merchant'@'127.0.0.1' IDENTIFIED BY '<pw>';"
|
|
sudo mysql -e "GRANT ALL ON ladill_merchant.* TO 'ladill_merchant'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
|
sudo mysql -e "GRANT SELECT ON ladilldb.platform_settings TO 'ladill_merchant'@'127.0.0.1'; FLUSH PRIVILEGES;"
|
|
```
|
|
|
|
## 3. Register OIDC client (platform)
|
|
|
|
```bash
|
|
php artisan passport:client \
|
|
--name="Ladill Merchant" \
|
|
--redirect_uri="https://merchant.ladill.com/sso/callback"
|
|
```
|
|
|
|
## 4. Platform integration
|
|
|
|
```env
|
|
BILLING_API_KEY_MERCHANT=<same>
|
|
IDENTITY_API_KEY_MERCHANT=<same>
|
|
PAY_API_KEY_MERCHANT=<same>
|
|
RP_MERCHANT_FRONTCHANNEL_LOGOUT=https://merchant.ladill.com/sso/logout-frontchannel
|
|
LADILL_MERCHANT_APP_URL=https://merchant.ladill.com
|
|
MERCHANT_DB_DATABASE=ladill_merchant
|
|
```
|
|
|
|
Add `merchant` to `config/pdns.php` service subdomains.
|
|
|
|
## 5. nginx + TLS
|
|
|
|
```bash
|
|
sudo deployment/setup-service-subdomain-nginx.sh merchant --app /var/www/ladill-merchant/current
|
|
```
|
|
|
|
## 6. First deploy
|
|
|
|
```bash
|
|
cd /var/www/ladill-merchant/current
|
|
php artisan migrate --force
|
|
php artisan config:cache route:cache view:cache
|
|
```
|
|
|
|
## 7. Verify
|
|
|
|
- SSO login at `merchant.ladill.com`
|
|
- Create a shop, menu, or booking storefront, download QR PNG
|
|
- Scan `/q/<code>`, place test order, confirm wallet credit (net of 15%)
|
|
- Withdraw from `account.ladill.com/wallet`
|
|
|
|
## Product IA (blueprint)
|
|
|
|
- **Overview** — sales + orders (today/30d), revenue, payout balance
|
|
- **Storefronts** — shop / menu / booking QR storefronts
|
|
- **Orders** — incoming orders, fulfilment status
|
|
- **Payouts** — wallet-first settlement, withdraw to bank/MoMo
|
|
- **Settings** — organisation profile
|