Step-by-step deployment process, rollback procedures, and environment management for the AI Execution Lab platform.
The platform runs on Next.js 15 deployed to Vercel. Deployments are automatic via GitHub push to main. This document covers the full workflow — from local verification to production rollback.
Every deployment follows the same four-step sequence:
Run TypeScript check and production build locally before pushing.
Git push triggers Vercel build pipeline automatically.
Watch Vercel dashboard for build errors before the deployment goes live.
Verify homepage, one article page, sitemap, and /ops on the live domain.
Always run these before pushing:
# TypeScript check — must pass with 0 errors
npx tsc --noEmit
# Production build
next build
If next build fails:
git add -A
git commit -m "feat: description of change"
git push origin main
Vercel picks up the push within seconds and starts a new build.
Common Vercel build failures and fixes:
| Error | Cause | Fix |
|---|---|---|
Edge runtime crypto error | runtime = 'edge' in an image file | Change to Node.js runtime (see failure archive) |
| Module not found | Missing import or wrong path alias | Check @/ path and file existence |
| React hydration error | Server/client mismatch | Check for Date.now() or Math.random() in components |
After the deployment goes live (usually 60–90 seconds for a content-only change):
✓ Homepage loads
✓ One article page loads with correct OG metadata
✓ /sitemap.xml returns current pages
✓ /ops shows correct section counts
Adding or editing MDX files in content/ only requires:
.mdx filetitle, description, date, tags, status)The site is fully static — new content gets included automatically in the next build.
Vercel keeps the full deployment history. To roll back:
Rollback is instant because Vercel aliases the domain to a different already-built deployment. No build queue needed.
Environment variables are set in Vercel project settings, not in the repository.
Never commit .env.local to Git. The .gitignore excludes all .env* files.
| Variable | Set in | Notes |
|---|---|---|
NEXT_PUBLIC_SITE_URL | Vercel → Settings → Env Vars | Required for canonical URLs |
NEXT_PUBLIC_PLAUSIBLE_DOMAIN | Vercel → Settings → Env Vars | Optional analytics |
NEXT_PUBLIC_GA_ID | Vercel → Settings → Env Vars | Optional analytics |
To add or change an env var:
Current env var status is visible at /ops → Analytics Status.
Every branch push (not main) gets a unique preview URL:
https://ai-execution-lab-git-<branch-name>-<username>.vercel.app
Use preview deployments to:
Preview deployments are identical to production except they use the preview domain.
For significant changes (new sections, route changes, layout changes):
tsc --noEmit passesnext build completes/api/og) returns an image for new section labelsFor content-only deployments, this checklist can be skipped.