Guide: Production Deployment

This guide covers deploying a SeloraX embedded app to production, using the SeloraX Messaging architecture (separate frontend + backend) as an example.

Architecture

A typical SeloraX app has three components:

┌──────────────────┐     iframe      ┌──────────────────┐
│ SeloraX Dashboard │───────────────>│  App Frontend     │
│ admin.selorax.io  │   postMessage  │  (Vercel, etc.)   │
└──────────────────┘                 └──────────────────┘
        │                                    │
        │ REST API                           │ REST API
        v                                    v
┌──────────────────┐                 ┌──────────────────┐
│ SeloraX Platform  │── webhooks ──>│  App Backend      │
│ api.selorax.io    │   (Inngest)   │  (DO App Platform)│
└──────────────────┘                 └──────────────────┘

Backend Environment Variables

Provider-specific variables (for SMS apps):

Frontend Environment Variables

Step 1: Deploy Backend

Deploy your Express server to any Node.js hosting provider:

• DigitalOcean App Platform — Use the Dockerfile, set env vars in the console
• Railway / Render — Connect GitHub repo, set env vars
• Self-hosted — Use PM2 or Docker behind a reverse proxy with SSL

Verify the backend is running:

curl https://your-backend.example.com/api/messaging/health

Step 2: Deploy Frontend

Deploy your React/Next.js frontend to Vercel, Netlify, or similar:

1. Set NEXT_PUBLIC_MESSAGING_API_URL to your production backend URL
2. Deploy and note the production URL (e.g., https://messaging.selorax.com)

Step 3: Update App URLs

Via the Developer Portal or API, update your app's URLs:

PATCH /api/v1/apps/:appId
Content-Type: application/json
Authorization: Bearer <token>
 
{
  "app_url": "https://messaging.selorax.com",
  "webhook_url": "https://api.messaging.selorax.com/api/messaging/oauth",
  "webhook_receive_url": "https://api.messaging.selorax.com/api/messaging/webhooks"
}

Step 4: Verify Scopes

Ensure your app's requested_scopes includes all scopes your app needs:

SELECT requested_scopes FROM apps WHERE slug = 'your-app-slug';

If your app uses billing (wallet, charges, subscriptions), you must include "billing":

["read:orders", "read:customers", "read:store", "billing"]

For existing installations, also update granted_scopes in app_installations:

UPDATE app_installations
SET granted_scopes = '["read:orders","read:customers","read:store","billing"]'
WHERE app_id = ? AND store_id = ?;

Step 5: Test the Full Flow

1. Marketplace visibility — Navigate to the marketplace in a merchant dashboard. Your app should appear if is_listed = 1 and is_active = 1.
2. Install — Click Install. The platform calls your webhook_url/token with tokens.
3. Iframe loads — Open the app page. The iframe should load your app_url with HMAC params.
4. Session token works — Your app should receive a session token via postMessage and display data.
5. Wallet works — If using billing, the wallet balance should display and Top Up should work.
6. Webhooks work — Trigger an event (e.g., change an order status) and verify your webhook endpoint receives it.

Common Issues

Wallet / Top Up Button Not Showing

Cause: Missing billing scope.

The wallet API endpoint (GET /api/apps/v1/billing/wallet) requires requireScope('billing'). If billing is not in requested_scopes AND granted_scopes, all wallet calls return 403, and your frontend shows no wallet data.

Fix: Add billing to both apps.requested_scopes and app_installations.granted_scopes.

Iframe Shows "Connecting..."

Cause: app_url is wrong, or DASHBOARD_URL on the platform doesn't match the actual dashboard origin.

The iframe loads your app_url with HMAC params. If the URL is wrong, the iframe can't load. If DASHBOARD_URL doesn't match the actual dashboard origin, the postMessage handshake fails.

Fix: Verify app_url points to your production frontend. Check that the platform's DASHBOARD_URL env var matches the actual dashboard domain.

Webhook Delivery Fails (500)

Cause: Your webhook_receive_url is incorrect, or your backend is down.

Fix:

1. Use the Developer Portal webhook test endpoint to verify connectivity
2. Check your backend logs for errors
3. Verify the webhook_receive_url in the Developer Portal matches your deployed backend

OAuth Token Callback Fails

Cause: webhook_url is wrong or backend isn't handling POST to /token path.

During direct-install, the platform POSTs tokens to {webhook_url}/token. If this fails, the installation succeeds but your app doesn't receive tokens.

Fix: Verify webhook_url is correct and your backend handles POST {webhook_url}/token.

"Invalid session token" on API Calls

Cause: SESSION_SIGNING_KEY mismatch between your backend and the platform.

Fix: Check the signing key in the Developer Portal matches your backend's SESSION_SIGNING_KEY env var. If you regenerated the key, update your backend deployment.