Spraay Shopify Self-Host

Self-Host the Spraay Shopify App

Walk a merchant from zero to a working batch-USDC-payouts page inside their Shopify admin in ~15 minutes. The app is open source (MIT), non-custodial, and requests zero Shopify scopes — it cannot read or write any store data.

Repo: https://github.com/plagtech/spraay-shopify

Stack at a glance

• Remix + @shopify/shopify-app-remix, Vite, Polaris UI (fully embedded in admin)
• wagmi v3 + viem v2 — MetaMask and Coinbase Smart Wallet
• Base (chain 8453), USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Batch contract 0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC (verified; never substitute another address)
• Supabase PostgreSQL via Prisma, isolated in a shopify schema
• Railway hosting (Dockerfile, node:20-alpine)

Prerequisites checklist

Confirm the user has (or help them create) each of these before starting:

1. A Shopify store (dev store is fine for testing)
2. A free Shopify Partners account → https://dev.shopify.com
3. A Railway account (hobby tier is enough)
4. A Supabase project (free tier is enough)
5. A wallet holding USDC on Base (MetaMask or Coinbase Smart Wallet)

Step 1 — Fork and deploy to Railway

1. Fork plagtech/spraay-shopify (Node 20+ required if running outside Docker: >=20.19 <22 || >=22.12).
2. Easiest path: the Deploy on Railway button in the README — the template pre-prompts for every required env var, with PORT defaulted to 3000. Manual path: Railway → New Project → Deploy from GitHub repo → select the fork; the repo ships a railway.json and Dockerfile, so the build is automatic.
3. Generate a public domain for the service (Settings → Networking). Note the URL, e.g. your-app.up.railway.app.

The app will crash-loop until env vars are set — that's expected. Continue.

Step 2 — Create the custom app in Shopify

1. Go to https://dev.shopify.com → Apps → Create app → Custom distribution (single merchant). Custom distribution is Shopify's intended path for merchant-specific tooling — no App Store review involved.
2. Set App URL to the Railway URL from Step 1 (https, no trailing slash).
3. Add all three OAuth redirect URLs (each prefixed by the App URL):
   • https://your-domain/auth/callback
   • https://your-domain/auth/shopify/callback
   • https://your-domain/api/auth/callback
4. Copy the Client ID and Client Secret.

Step 3 — Environment variables

Set these in Railway → service → Variables. The repo's .env.example documents each one; the authoritative reference:

The PORT=3000 gotcha (most common failure): the Dockerfile's EXPOSE 3000 sets Railway's domain target port to 3000. If PORT is unset, Railway injects PORT=8080, the app binds :8080, the proxy still routes to :3000, and every route returns 502. If the user reports 502s on all routes, check this first.

Database notes: keep ?schema=shopify on both URLs so the app's tables stay isolated from anything else in the Supabase project. Both URLs point at the same database — only the port and pooling differ.

After saving variables, redeploy. Migrations run automatically on boot (prisma generate && prisma migrate deploy, then remix-serve). A clean boot — migrate succeeds and remix-serve prints its listen URL — means Steps 1–3 are done.

Diagnostic tip: a 502 while Railway shows the deployment "Online" is a port/proxy mismatch, not a crash. If the logs show a successful migrate and a listening server, fix PORT, don't debug the app.

Step 4 — Install and test

1. From the Dev Dashboard, install the app on the store. Complete the OAuth prompt.

2. Open the app from the Shopify admin sidebar — the Polaris UI should render embedded.

3. Run a small real test: CSV with 1–2 recipients and small amounts. Header row is optional (first two columns are assumed address, amount); optional extra columns name, email, memo are supported, and the payout screen has a Download CSV template link and Load sample data button. Example:

   wallet_address,amount
   0xYourOtherWallet...,1.00
   

4. Review screen shows recipients, total, and the 0.3% protocol fee → connect wallet → approve USDC → execute → confirm the BaseScan link resolves.

Optional — local development

For hacking on the app itself (not needed for a production deploy): npm install && npm run dev. The Shopify CLI creates a tunnel and injects SHOPIFY_API_KEY, SHOPIFY_API_SECRET, and SHOPIFY_APP_URL, so local .env only needs DATABASE_URL and DIRECT_URL.

Optional — custom domain

Point a subdomain (e.g. payouts.yourstore.com) at the Railway service via CNAME, wait for the SSL cert to issue, then update SHOPIFY_APP_URL and the App URL + redirect URLs in Shopify settings to match. All three must agree or OAuth breaks.

Troubleshooting

Security posture (tell the user)

• Zero scopes: the app requests no Shopify permissions — it structurally cannot access orders, customers, or products.
• Non-custodial: USDC moves only when the merchant's own wallet signs, in their browser. The server never holds keys or funds.
• Self-hosted: credentials, database, and infrastructure belong to the merchant.
• The 0.3% protocol fee is itemized on the review screen and collected on-chain by the batch contract. It is contract-enforced on Base, not app code — self-hosting or forking does not remove it, and there is no subscription or plan.
• Security issues → report privately to support@spraay.app, not a public issue.

Related

• Running payouts after deployment → shopify-batch-payouts skill
• Protocol docs → https://docs.spraay.app