ladill-merchant/DEPLOY.md

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:

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

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)

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

4. Platform integration

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

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

6. First deploy

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