settlekit/docs/DEPLOYMENT.md
caelum0x e5d8894192 docs(deploy): flag settlekit-db free-tier expiry (2026-10-30) with a one-command migration path
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.
2026-10-24 21:39:41 +03:00

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 start script (node apps/api/dist/server.js), so a plain Render Web Service pointing at the repo root just works: its default pnpm install && pnpm build && pnpm start builds the workspace and boots the API on Render's injected $PORT (the API binds 0.0.0.0). For the API + worker + Postgres together, use the render.yaml Blueprint 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 with NEXT_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-worker has 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's SETTLEKIT_SERVICE_TOKEN is a copy of the API's.
  • NEXT_PUBLIC_DOCS_URL on 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/proof answers "not configured".
  • PROOF_EXCLUDED_ORGS lists 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, because NEXT_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):

  1. Cheapest fix — upgrade the Render Postgres plan (Render dashboard → settlekit-db → change plan to Starter, ~$7/mo). No app changes needed; DATABASE_URL stays the same.
  2. Free fix — move to Neon. Create a Neon project (needs an owner login/ new account — this repo's mcp__Neon__authenticate tool starts an OAuth flow that needs a human in the browser), then either:
    • let it start empty (the migrator in scripts/start.mjs creates 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 set DATABASE_URL to the Neon connection string on settlekit-api and settlekit-checkout and redeploy both.

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:

  1. New → Blueprint, connect the GitHub repo, pick render.yaml.
  2. Render provisions: settlekit-db (Postgres), settlekit-api + settlekit-worker (Docker), and settlekit-web / dashboard / marketplace / checkout / docs (Next.js). Each Next service starts with next start -p $PORT so Render detects the open port.
  3. Signing secrets (*_SECRET, API_BOOTSTRAP_KEY) are auto-generated. DATABASE_URL is wired from the database automatically.
  4. Migrations run automatically: the API service's preDeployCommand runs the bundled migrator (node /app/packages/database/dist/cli.js) against DATABASE_URL before 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.)
  5. 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.
  6. Later (when live): add the Circle/Arc keys (CIRCLE_*, GAS_STATION_API_KEY, COMPLIANCE_API_KEY, ARC_CHAIN_ID=5042002) to settlekit-api (+ wallet keys to the worker). Each flips its feature live; see .env.example. The platform take-rate is configurable via PLATFORM_FEE_BPS / PLATFORM_FEE_FIXED (default 1%, no fixed fee; DEFAULT_FEE_SCHEDULE in packages/platform-billing).

Commit the lockfile. Every service installs with --frozen-lockfile, so pnpm-lock.yaml must be committed and current (run pnpm install and 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. The vercel.json files already use the correct names.

  • Render: settlekit-api, settlekit-worker, settlekit-db (the backend).
  • Vercel: apps/web (marketing) + optionally dashboard / marketplace / docs.
  • Wire the Next apps' NEXT_PUBLIC_API_URL to 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.