Render's free Postgres plan backing settlekit-api/checkout expires soon and was buried in a one-line table note. Document the real impact (service downtime, not data loss — only testnet demo rows exist today), the two owner-only fixes (upgrade plan or move to Neon), and add scripts/migrate-db.sh so moving the data over is a single command once a target DB exists.
11 KiB
Deploying SettleKit
SettleKit is a pnpm monorepo: a Hono API + a background worker (both
Dockerized, Postgres-backed) and several Next.js apps (web marketing,
dashboard, marketplace, docs, checkout, portal, admin).
Two supported paths: Render (full stack incl. API/worker/DB) and Vercel (the Next.js sites). Circle/Arc API keys are added after launch — every integration is cred-gated, so the stack runs without them (each feature is a clear "not configured" no-op until its key is set).
TL;DR — the working split
- Render = the API backend. The repo root has a
startscript (node apps/api/dist/server.js), so a plain Render Web Service pointing at the repo root just works: its defaultpnpm install && pnpm build && pnpm startbuilds the workspace and boots the API on Render's injected$PORT(the API binds0.0.0.0). For the API + worker + Postgres together, use therender.yamlBlueprint instead. - Vercel = the Next.js frontends. One Vercel project per app, Root Directory
set to the app folder (each has a
vercel.json). Point each at the Render API withNEXT_PUBLIC_API_URL.
Live deployment (Render, from main, 2026-09-30)
Created service by service with the Render API, using the render.yaml layout. All services are on the free plan in Ohio and auto-deploy from main.
| Service | URL |
|---|---|
| settlekit-web | https://settlekit-web.onrender.com (/proof, /docs/integrate) |
| settlekit-api | https://settlekit-api.onrender.com (/health, /v1/public/proof) |
| settlekit-checkout | https://settlekit-checkout.onrender.com (payment links /l/<slug>) |
| settlekit-dashboard | https://settlekit-dashboard.onrender.com |
| settlekit-operator | https://settlekit-operator.onrender.com (/proof; Tameion operator console, free plan, added 2026-10-07; talks to settlekit-api) |
| settlekit-db | Render Postgres, free plan (expires 2026-10-30 unless it is upgraded or moved to Neon — see "DB EXPIRY" below) |
- Mode: testnet.
SETTLEKIT_CHAIN_ENV=testnet,ENABLED_EVM_CHAINS=base,arbitrum,ethereum,SOLANA_CLUSTER=devnet, and Arc testnet. Every other chain and integration is unset, so it fails closed. settlekit-workerhas not been created (it needs the starter plan, about $7/mo). One-time checkout works without it. Renewals, retries and seller webhooks do not run.- Signing secrets were generated by Render (
generateValue). The checkout'sSETTLEKIT_SERVICE_TOKENis a copy of the API's. NEXT_PUBLIC_DOCS_URLon the web service points to/docs/integrate, because the separate docs app is not deployed.- The operator is enabled on settlekit-api by
~/products/settlekit-demo/enable-live-operator.sh(Arc testnet vault, throwaway testnet keys, demo org) after the Circle faucet step; until then/v1/public/operator/proofanswers "not configured". PROOF_EXCLUDED_ORGSlists the two demo orgs (both marked as test accounts).- To go to mainnet: set the chain variables from the launch checklist (
docs/colosseum/LAUNCH-CHECKLIST.md) on the api and the checkout. Then redeploy the Next services, becauseNEXT_PUBLIC_*values are fixed at build time.
DB EXPIRY — action needed before 2026-10-30
settlekit-db is Render's free Postgres plan. Render deletes free
Postgres databases automatically a fixed number of days after creation —
this one expires 2026-10-30. Confirmed still live and serving real
traffic as of 2026-10-24 (settlekit-api /health and /v1/public/proof
both answer 200 against it), so this has not happened yet, but there is no
grace period: when it expires, settlekit-api, settlekit-checkout (and
settlekit-worker if created) lose DATABASE_URL and the live deployment
goes down — checkout, payment confirmation and /proof all break.
The data at risk is low-value: as of this check the only rows are testnet demo payments/sessions (the $1 demo checkout link, one Solana devnet payment) — there is no real customer data on this instance. The risk is service downtime, not data loss.
This requires an owner action that this agent will not do unattended (new credentials or a payment):
- Cheapest fix — upgrade the Render Postgres plan (Render dashboard →
settlekit-db→ change plan to Starter, ~$7/mo). No app changes needed;DATABASE_URLstays the same. - Free fix — move to Neon. Create a Neon project (needs an owner login/
new account — this repo's
mcp__Neon__authenticatetool starts an OAuth flow that needs a human in the browser), then either:- let it start empty (the migrator in
scripts/start.mjscreates the schema automatically on first boot — no manual migration needed), or - run
./scripts/migrate-db.sh "$OLD_DATABASE_URL" "$NEW_DATABASE_URL"to carry over the existing (low-value, testnet) rows first. Then setDATABASE_URLto the Neon connection string onsettlekit-apiandsettlekit-checkoutand redeploy both.
- let it start empty (the migrator in
Either way, verify afterward with:
curl -s https://settlekit-api.onrender.com/health
curl -s https://settlekit-api.onrender.com/v1/public/proof
Render (full stack) — render.yaml blueprint
render.yaml at the repo root is a Render Blueprint. Deploy via Blueprint —
NOT as a plain Web Service (see Troubleshooting below for why). From the Render
dashboard:
- New → Blueprint, connect the GitHub repo, pick
render.yaml. - Render provisions:
settlekit-db(Postgres),settlekit-api+settlekit-worker(Docker), andsettlekit-web/dashboard/marketplace/checkout/docs(Next.js). Each Next service starts withnext start -p $PORTso Render detects the open port. - Signing secrets (
*_SECRET,API_BOOTSTRAP_KEY) are auto-generated.DATABASE_URLis wired from the database automatically. - Migrations run automatically: the API service's
preDeployCommandruns the bundled migrator (node /app/packages/database/dist/cli.js) againstDATABASE_URLbefore each deploy goes live. It's idempotent — a deploy with no new migrations is a no-op. (To run manually:DATABASE_URL=… pnpm --filter @settlekit/database migrate:run.) - After the first deploy, set the cross-service URLs in each service's Environment:
settlekit-dashboard/marketplace/checkout→NEXT_PUBLIC_API_URL= the API's URL.settlekit-web→NEXT_PUBLIC_DASHBOARD_URL,NEXT_PUBLIC_MARKETPLACE_URL,NEXT_PUBLIC_DOCS_URL.
- Later (when live): add the Circle/Arc keys (
CIRCLE_*,GAS_STATION_API_KEY,COMPLIANCE_API_KEY,ARC_CHAIN_ID=5042002) tosettlekit-api(+ wallet keys to the worker). Each flips its feature live; see.env.example. The platform take-rate is configurable viaPLATFORM_FEE_BPS/PLATFORM_FEE_FIXED(default 1%, no fixed fee;DEFAULT_FEE_SCHEDULEin packages/platform-billing).
Commit the lockfile. Every service installs with
--frozen-lockfile, sopnpm-lock.yamlmust be committed and current (runpnpm installand commit it after any dependency change), or the build fails before it starts.
Troubleshooting
ERR_PNPM_NO_SCRIPT_OR_SERVER: Missing script start or file server.js /
No open ports detected — the service was created as a plain Web Service
pointing at the repo root, so Render runs its default pnpm start. The monorepo
root has no start script and binds no port, so it fails. Fix: delete that
service and redeploy via New → Blueprint (above), which gives each app its own
build/start command. If you must configure a service by hand instead, set:
| Service | Build command | Start command |
|---|---|---|
| API | (use Docker: apps/api/Dockerfile) |
(Docker CMD) |
| Worker | (use Docker: apps/worker/Dockerfile) |
(Docker CMD) |
| Marketing | corepack enable && pnpm install --frozen-lockfile && pnpm --filter @settlekit/web... build |
pnpm --filter @settlekit/web exec next start -p $PORT |
| Dashboard | corepack enable && pnpm install --frozen-lockfile && pnpm --filter @settlekit/dashboard... build |
pnpm --filter @settlekit/dashboard exec next start -p $PORT |
| Marketplace | corepack enable && pnpm install --frozen-lockfile && pnpm --filter @settlekit/marketplace-app... build |
pnpm --filter @settlekit/marketplace-app exec next start -p $PORT |
| Checkout | corepack enable && pnpm install --frozen-lockfile && pnpm --filter @settlekit/checkout-app... build |
pnpm --filter @settlekit/checkout-app exec next start -p $PORT |
| Docs | corepack enable && pnpm install --frozen-lockfile && pnpm --filter @settlekit/docs-app... build |
pnpm --filter @settlekit/docs-app exec next start -p $PORT |
The Next.js package names are @settlekit/web, @settlekit/dashboard,
@settlekit/marketplace-app, @settlekit/checkout-app, @settlekit/docs-app
(the -app suffix matters for the last three).
Vercel (the Next.js sites)
Vercel deploys the Next apps fastest. For each site, create a Vercel project from the same repo and set Root Directory to the app:
| Site | Root Directory |
|---|---|
| Marketing | apps/web |
| Dashboard | apps/dashboard |
| Marketplace | apps/marketplace |
| Checkout | apps/checkout |
| Docs | apps/docs |
Every app folder above ships a vercel.json pinning the pnpm-workspace install +
filtered build (pnpm --filter @settlekit/<pkg>... build), so Vercel builds only
that app + its deps from the monorepo. With Root Directory set to the app,
Vercel runs the workspace install and the build emits that app's .next in place.
Set NEXT_PUBLIC_API_URL (and, for the marketing site, the NEXT_PUBLIC_*_URL
cross-links) in each Vercel project's env. Keep the API + worker on Render
(Vercel is serverless and not suited to the long-lived worker / Postgres backend).
The package names differ from the folder names for three apps:
apps/marketplace→@settlekit/marketplace-app,apps/checkout→@settlekit/checkout-app,apps/docs→@settlekit/docs-app. Thevercel.jsonfiles already use the correct names.
Recommended split
- Render:
settlekit-api,settlekit-worker,settlekit-db(the backend). - Vercel:
apps/web(marketing) + optionallydashboard/marketplace/docs. - Wire the Next apps'
NEXT_PUBLIC_API_URLto the Render API URL.
Branding assets
Web assets are generated from the source logos in design/brand-source/:
- per-app
app/icon.png+app/apple-icon.png(browser tab + iOS), apps/web/public/favicon.ico,logo-mark.png(navbar),logo-wordmark.png,apps/web/app/opengraph-image.png(social share).
Regenerate with ImageMagick from design/brand-source/ if the logo changes.