MotivdMotivd
AboutCase studiesDocs
PricingSecurity
← Back to Documentation

Deployment guide

Environment setup, release flow, and production checks

On this page

  • Deployment guide
    • Deployment model
    • Environments and configuration
    • Release workflow
    • Post-deploy verification
    • Scheduled operational jobs
    • Alert remediation runbook
    • Rollback strategy
    • Capacitor native shell
    • Deployment documentation checklist

Deployment guide

How to release Motivd safely from local development to production.

Deployment model

Motivd is a Next.js app designed for Git-driven deployment:

  1. Make and validate changes locally.
  2. Commit and push to GitHub.
  3. Let Vercel build and deploy from the connected repository.

This keeps releases traceable and easy to roll back.

For React / Next.js performance expectations on Vercel (this app and user-generated projects), see docs/VERCEL_REACT_PERFORMANCE.md in the repo — it maps Vercel’s official React best-practices guide to Motivd’s stack.

Environments and configuration

Required baseline

  • Node/npm versions compatible with the repository
  • Supabase project and keys configured
  • GitHub repository connected to Vercel
  • Production domain configured in Vercel

Common environment variables

Set values in Vercel project settings (and locally in .env when needed):

  • NEXT_PUBLIC_SITE_URL
  • NEXT_PUBLIC_BOOK_DEMO_URL (optional; scheduler URL used by Plans “Book a demo” CTA)
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY (or publishable key)
  • SUPABASE_SERVICE_ROLE_KEY (server-only)
  • CRON_SECRET (recommended; shared auth token for internal cron routes)
  • NEXT_PUBLIC_SENTRY_DSN and SENTRY_DSN (for client/server/edge error tracking)
  • Optional Sentry tuning: NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE, SENTRY_TRACES_SAMPLE_RATE, NEXT_PUBLIC_SENTRY_ENVIRONMENT, SENTRY_ENVIRONMENT, NEXT_PUBLIC_SENTRY_RELEASE, SENTRY_RELEASE
  • For local source map uploads during next build, run npm run sentry:login (or curl -fsSL https://cli.sentry.dev/install | bash then sentry auth login) instead of committing tokens. Vercel still needs SENTRY_AUTH_TOKEN + SENTRY_ORG + SENTRY_PROJECT from Sentry’s auth tokens UI—CI cannot open a browser.
  • Provider-specific vars (for example GitHub, Stripe, Resend, Groq) based on enabled features
  • Repo handoff alerting vars (optional but recommended): REPO_HANDOFF_ALERT_SLACK_WEBHOOK_URL, REPO_HANDOFF_ALERT_EMAIL_TO, threshold overrides (REPO_HANDOFF_ALERT_HOURLY_*, REPO_HANDOFF_ALERT_WEEKLY_*), cadence controls (, , , weekly equivalents), and optional admin runbook URLs (, , )

Keep secrets server-only and rotate credentials when access changes.

Release workflow

1) Validate before pushing

  • Run npm run build to catch compile/type issues.
  • Run relevant tests (for example npm run test:e2e for route smoke checks).
  • Verify changed routes and user flows manually in the browser when UI behavior changed.

2) Commit and push

Use clear commit messages describing the behavior change.

From project root you can use:

npm run ship

Or provide a custom message:

npm run ship -- "feat: your release summary"

3) Monitor deployment

  • Confirm Vercel build succeeds.
  • Validate production routes (especially multilingual routes for EN/FR).
  • Check key integrations (auth, builder flow, webhooks, preview URLs).
  • Confirm Sentry receives test events (client and server paths) in the expected environment/release.

Post-deploy verification

Run a focused release checklist:

  • Home, docs, and solution routes load in both locales.
  • Critical APIs respond as expected.
  • Build polling and workspace views still function.
  • Webhook deliveries are being recorded if integrations are active.
  • No major regressions in SEO surfaces (metadata/sitemap/robots).
  • Error tracking is reporting cleanly (no new untriaged production exceptions spike).

Scheduled operational jobs

Current Vercel cron jobs (vercel.json) include:

  • Daily case-study sitemap cache sync: GET /api/case-study-sitemap-sync
  • Hourly repo-handoff alert policy: GET /api/telemetry/repo-handoff-alerts (supports cooldown suppression + escalation on repeated breaches)
  • Weekly repo-handoff alert policy: GET /api/telemetry/repo-handoff-alerts/weekly
  • Investor updates: GET /api/cron/investor-updates (hourly; sends only when Monday 9:00 in INVESTOR_UPDATE_SCHEDULE_TZ, default America/Toronto, and automation is on in Admin → Investors; weekly list every run, monthly list on the first Monday of that month in the same timezone; requires RESEND_API_KEY and a saved draft)
  • Monthly strategic partner updates: GET /api/cron/partner-updates (1st day of each month, 9:00 UTC; sends monthly partner draft from Admin → Partners; requires RESEND_API_KEY and saved draft)
  • Forecasting refresh: GET /api/cron/forecasting-refresh (daily at 00:20 UTC; rebuilds forecasting_metric_daily for the trailing 365 UTC days so forecasting actuals stay current without requiring ad hoc SQL)

All cron routes should be protected with CRON_SECRET in production. Validate by running a manual request with the bearer token and checking for a structured JSON response.

Alert remediation runbook

When Slack/email alerts appear degraded on /[locale]/admin, use this workflow to recover quickly:

  1. Open /[locale]/admin and go to Repo handoff telemetry → Alert remediation.
    • Review per-channel health first (last successful test, last check, and latest failure reason) plus cooldown/escalation metadata so you can quickly tell stale failures from fresh regressions.
  2. Open the linked runbook(s): generic, Slack-specific, or email-specific.
  3. Run a quick channel check from the same card:
    • Send Slack test → calls POST /api/telemetry/repo-handoff-alerts/test-channel with {"channel":"slack"}
    • Send email test → calls POST /api/telemetry/repo-handoff-alerts/test-channel with {"channel":"email"}
  4. Confirm delivery in the destination channel and in the admin UI status feedback. The test result is persisted to telemetry and updates the channel-health snapshot.

Slack channel checks

  • Verify REPO_HANDOFF_ALERT_SLACK_WEBHOOK_URL is set and still valid.
  • If the test action fails with a 4xx/5xx response, rotate the webhook in Slack and update Vercel env.
  • Re-run Send Slack test and confirm receipt.

Email channel checks

  • Verify REPO_HANDOFF_ALERT_EMAIL_TO (or ADMIN_EMAIL fallback) is set to active inboxes.
  • Verify RESEND_API_KEY and sender (REPO_HANDOFF_ALERT_EMAIL_FROM or FROM_EMAIL) are valid.
  • Re-run Send email test and confirm delivery.

Rollback strategy

If production behavior regresses:

  1. Identify the bad commit range quickly from deployment history.
  2. Revert the offending commit(s) in Git.
  3. Push revert commit(s) to trigger a clean redeploy.
  4. Re-verify the affected paths and integrations.

Prefer small, focused commits to make rollback safer and faster.

Capacitor native shell

Founder projects can use Capacitor to wrap the same web app for App Store and Google Play. In the builder, Launch → Native shell (Capacitor) saves how the WebView loads your site (static webDir vs HTTPS server.url) and can sync capacitor.config.ts into Motivd Cloud (and optionally push patched paths to GitHub).

  • Technical mapping and APIs: docs/LAUNCH_TAB.md (Native shell section) and repo root docs/CAPACITOR_USER_PROJECT.md for CI and local npx cap sync workflows.
  • Motivd’s own consumer app (fixed bundle id, loads motivd.com) lives under apps/motivd-mobile/ in this repository — separate from per-project Launch metadata.

Deployment documentation checklist

When deployment behavior changes:

  1. Update this guide with new release steps or quality gates.
  2. Update content/docs/overview.md if project-level deployment architecture changed.
  3. Ensure docs routes remain listed in sitemap for EN/FR.
  4. Record any new operational runbooks (incidents, rollbacks, migrations).
REPO_HANDOFF_ALERT_HOURLY_COOLDOWN_MINUTES
REPO_HANDOFF_ALERT_HOURLY_ESCALATE_AFTER_BREACHES
REPO_HANDOFF_ALERT_HOURLY_ESCALATE_EVERY_BREACHES
REPO_HANDOFF_ALERT_RUNBOOK_URL
REPO_HANDOFF_ALERT_SLACK_RUNBOOK_URL
REPO_HANDOFF_ALERT_EMAIL_RUNBOOK_URL