Deployment

Before you deploy

• Run the full gate locally: pnpm verify plus pnpm e2e.
• Confirm the env matrix for your target mode — key names per mode live in the env matrix module; values come from your secret manager, never from the repo.
• Decide the mode: demo for a public sample, production-kit for your own product.

Vercel checklist

1. Import the repository into Vercel and select the Next.js app.
2. Set the environment variables for your mode (see the env matrix; demo requires the Supabase keys, Google OAuth client, and admin allowlist).
3. Point DATABASE_URL at your Supabase Postgres and run migrations: pnpm db:setup.
4. Seed demo data when deploying the public sample: pnpm db:seed.
5. Update the Google OAuth client and Supabase redirect list with the deployed callback, e.g. https://demo.buildgrain.com/auth/callback.
6. Schedule the nightly reset job (cron): restore protected seed accounts and remove visitor workspaces inactive for 24 hours.
7. Smoke-check after deploy: sign in with Google, create a project, open the admin console, and confirm the boundary chips render on the public entry.

Docker checklist

1. Build the app image with the provided Dockerfile and run it next to Postgres via docker compose.
2. Supply env vars through an env file or your orchestrator's secret store — the compose file references key names only.
3. Run migrations on boot (pnpm db:setup) before the app container reports healthy.
4. Expose port 3000 and set the app callback URL to your host, e.g. http://localhost:3000/auth/callback for local Docker.
5. For offline development, run Postgres locally and leave the OAuth keys unset — the login screen shows the setup blocker instead of failing silently.

Demo mode boundary

The public sample must keep its no-charge boundary: entitlement state is simulated, the billing provider slot stays disabled, and mail delivers to the local preview queue only. Never expose a test auth bypass or fake Google login on a public deployment.

Billing provider (buyers)

The kit ships a Stripe-ready billing module behind the STRIPE_SECRET_KEY env flag. It stays off in demo mode. In production-kit mode, configure your own Stripe keys and enable the module after reviewing the provider documentation — enabling live mode is your decision and responsibility as the buyer.

Post-deploy verification

• /app/* and /admin/* guards respond correctly for signed-out users.
• Tenant isolation: a second Google account cannot see the first account's workspace.
• The nightly reset job ran within the last 24 hours (check the admin Events surface).
• pnpm check:ui-copy passes against the deployed branch — no forbidden public copy.