Deployment

Create and select the Convex deployment

Create a project in your Convex account, then select its production deployment with the Convex CLI from the repository root (convex.json points at apps/database/convex/). Never point the local bootstrap at it: pnpm bootstrap:local refuses non-local deployment names on purpose.

Set the backend variables

Backend secrets are deployment environment variables, not Next.js env files. Set them against the selected deployment:

pnpm exec convex env set SITE_URL https://app.example.com
pnpm exec convex env set ADMIN_SITE_URL https://admin.example.com
pnpm exec convex env set MCP_APP_URL https://app.example.com
pnpm exec convex env set AUTH_RESEND_KEY re_xxx
pnpm exec convex env set AUTH_EMAIL_FROM "Nextbase <auth@example.com>"
pnpm exec convex env set JWT_PRIVATE_KEY "<PKCS8 private key on one line>"
pnpm exec convex env set JWKS '<JSON web key set>'

JWT_PRIVATE_KEY and JWKS are required by Convex Auth. The local bootstrap generates an RS256 pair for the local backend (see scripts/bootstrap-convex-local.ts, which uses jose); for production generate your own pair the same way and keep the private key out of the repository. Add AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET only if you use those providers. Do not set APP_ENV=local in production; it would log auth emails instead of sending them.

SITE_URL must be the canonical web origin: it validates auth redirects and builds password reset links. ADMIN_SITE_URL is the admin origin: the redirect allowlist permits exactly those two origins, and Admin MCP consent is routed there. MCP_APP_URL is where /oauth/authorize sends users for User MCP consent and the browser origin the MCP servers accept. CONVEX_SITE_URL is provided by Convex.

Publish the backend

Deploy the schema, functions, HTTP routes, the cron and both gateway component instances (mcpUser and mcpAdmin) with pnpm exec convex deploy from the repository root with a deploy key, or through your CI integration. pnpm convex:once is convex dev --once and targets the development deployment you have selected, so use it only for a dev deployment.

Keep the existing Convex Auth providers, signing keys and auth tables when updating an existing app. If you change the schema in a way existing documents do not satisfy, the push fails; follow the stepwise approach on the project structure page.

Once the backend is live and you have signed up, promote the first administrator against production:

pnpm exec convex run --prod platform:grantAdmin '{"email":"you@example.com"}'

Configure the web host

Set these on the web app's host (Vercel project settings or Netlify):

The web build also reads the legacy NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY. scripts/verify-local.sh exports placeholders for them during the compile-mode build; set the same placeholders on the host if your build fails without them, or remove the legacy code paths. The full table is on the environment variables page.

Configure the admin host

Create a second Vercel project for the admin app against the same repository, and set:

apps/admin/.env.local.example also lists NEXT_PUBLIC_CONVEX_SITE_URL. The admin code reads ADMIN_EMAIL, RESEND_API_KEY, the STRIPE_* keys and the same legacy Supabase placeholders as the web app; add them if a feature or the build needs them. The admin app has its own origin-scoped session, so administrators sign in again at the admin /login.

Build and deploy both apps

Use apps/web and apps/admin as the root directories of two Vercel projects; each runs its own next build. The root vercel.admin.json holds the admin project's configuration (pnpm --filter admin build, output apps/admin/.next). apps/web/netlify.toml runs pnpm run build for Netlify; there is no Netlify configuration for the admin app. From the repository root the equivalents are:

pnpm build:web
pnpm build:admin

pnpm build runs Turborepo's build task for every package. Follow the Vercel guide for importing the repository and preview environments. Preview deployments need their own SITE_URL, ADMIN_SITE_URL and MCP_APP_URL on a matching Convex deployment; a backend configured for production will redirect auth and consent flows to the production apps.

Configure external callbacks

• Resend: verify your sending domain and use a sender on it for AUTH_EMAIL_FROM and ADMIN_EMAIL. See emails with Resend.
• GitHub and Google: register the OAuth callback with your .convex.site origin as Convex Auth requires, and add buttons that call signIn("github") or signIn("google"); the login pages ship without them.
• Stripe: point the webhook at https://app.example.com/api/stripe/webhooks and set STRIPE_WEBHOOK_SECRET. The gateway in apps/web/src/payments/stripe-payment-gateway.ts still persists billing through the Supabase client, and the Convex billing tables have no functions yet, so finish that migration before enabling billing.

Smoke test

1. GET /api/health on the web origin returns { "ok": true }.
2. Open /sign-up, create an account, and confirm the verification email arrives from Resend. Sign in again at /login.
3. Complete onboarding, create a workspace, and add a project.
4. Request a password reset from /forgot-password and finish it at /update-password.
5. Open /user/settings/connections and check that the displayed server URL is https://<name>.convex.site/mcp/user for the deployment you intended. Connect an agent and call account_context (connect an agent).
6. Run pnpm exec convex run --prod platform:grantAdmin '{"email":"..."}' for your account, sign in at the admin origin's /login, open /app-admin and /app-admin/connections, and confirm a non-admin account gets the unauthorized page.
7. From /app-admin/users, impersonate a test user and confirm you land on the web origin with the support banner, then end the support session.
8. Check the Convex dashboard logs for the hourly prune MCP credentials cron.