Deploy to Production

This guide walks you through deploying your self-hosted Banata Auth stack to production. It covers the Convex backend, your Next.js frontend, security hardening, and everything you need to go live with confidence.

Self-hosted only. If you are using Banata as a managed service, you do not need to deploy the Convex auth runtime yourself. Create your project and API keys in the dashboard, then integrate with @banata-auth/sdk.

Deployment Architecture

In production, your stack has two main components — a Next.js app (deployed to Vercel, Cloudflare, or your own servers) and a Convex backend that runs the auth engine and database.

┌──────────────────────────────────────┐
│           Vercel / Cloudflare        │
│                                      │
│   ┌────────────────────────────┐     │
│   │       Next.js App          │     │
│   │  /api/auth/[...all] proxy  │     │
│   │  Middleware (route guard)  │     │
│   │  React UI + SSR           │     │
│   └─────────────┬──────────────┘     │
└─────────────────┼────────────────────┘
                  │ HTTPS
┌─────────────────┼────────────────────┐
│           Convex Cloud               │
│                                      │
│   ┌─────────────▼──────────────┐     │
│   │      Better Auth Engine    │     │
│   │  HTTP routes (.site URL)   │     │
│   │  Database (26 tables)      │     │
│   │  Functions (queries,       │     │
│   │    mutations, actions)     │     │
│   └────────────────────────────┘     │
└──────────────────────────────────────┘

Step 1 — Deploy to Convex

Start by pushing your Convex functions and schema to a production deployment.

npx convex deploy

This creates an isolated production deployment with its own database, completely separate from your dev environment.

Set production environment variables

# Generate a unique auth secret (different from dev!)
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)" --prod
 
# Your production domain
npx convex env set SITE_URL "https://myapp.com" --prod
 
# OAuth credentials (use production values)
npx convex env set GITHUB_CLIENT_ID "prod-client-id" --prod
npx convex env set GITHUB_CLIENT_SECRET "prod-client-secret" --prod
npx convex env set GOOGLE_CLIENT_ID "prod-client-id" --prod
npx convex env set GOOGLE_CLIENT_SECRET "prod-client-secret" --prod
 
# Email provider
npx convex env set RESEND_API_KEY "re_prod_..." --prod

Important: Always use a different BETTER_AUTH_SECRET in production than in development. If one is compromised, the other environment stays safe.

Step 2 — Deploy Next.js

Vercel (Recommended)

1. Connect your repository to Vercel.
2. Add these environment variables in the Vercel dashboard:

CONVEX_DEPLOYMENT=prod:your-project-name
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site
NEXT_PUBLIC_SITE_URL=https://myapp.com

3. Deploy:

vercel --prod

Cloudflare Pages

1. Create a Cloudflare Pages project.
2. Set the same environment variables listed above.
3. Build command: next build
4. Output directory: .next

Self-Hosted

# Build the app
npm run build
 
# Run with a process manager like PM2
pm2 start npm --name "myapp" -- start

Step 3 — Update OAuth Callback URLs

Head to each OAuth provider's developer console and update the callback URLs to your production domain.

Tip: Most providers let you register multiple callback URLs. Keep your localhost URL alongside the production one so local development keeps working.

Security Hardening

HTTPS

Production requires HTTPS. The Secure cookie flag is set automatically, so session cookies are only sent over encrypted connections. Vercel and Cloudflare provide HTTPS out of the box. If you are self-hosting, place your app behind a TLS-terminating reverse proxy.

Auth Secret

• Generate with openssl rand -base64 32 (minimum 32 bytes).
• Never share between environments.
• Never commit to source control.
• Rotating the secret invalidates all active sessions — plan rotations during low-traffic windows.

Session Security

Rate Limiting

Built-in rate limits protect against brute-force attacks by default:

Exceeding these returns a 429 Too Many Requests response. For additional protection, add rate limiting at the infrastructure level (Cloudflare WAF, Vercel Edge Middleware, etc.).

Trusted Origins

Configure trusted origins to restrict which domains can make authenticated requests. Only list the origins your app actually runs on — for example, https://myapp.com and https://admin.myapp.com.

Monitoring

Convex Dashboard

The Convex Dashboard gives you real-time visibility into your auth backend:

• Function logs — Every auth operation, including errors.
• Database explorer — Browse users, sessions, and organizations.
• Metrics — Execution counts, latency, and error rates.

Audit Logs

Banata Auth automatically records 30 auth event types. Query them through the SDK to spot suspicious activity:

const failedLogins = await banata.auditLogs.listEvents({
  action: "session.created",
  limit: 100,
});

Webhooks

Set up webhook endpoints to pipe auth events into your monitoring stack (Datadog, PagerDuty, Slack, etc.). Monitor delivery success rates and retry counts through the admin dashboard.

Scaling

Convex handles backend scaling automatically — serverless functions scale from zero to thousands of concurrent executions, the database is sharded and replicated, and there are no cold starts. You do not need to configure anything.

For the Next.js frontend, Vercel provides automatic global edge deployment. If you are self-hosting, use a load balancer across multiple instances. Session cookies are stateless on the Next.js side (all state lives in Convex), so any instance can serve any user.

Pre-Launch Checklist

Environment

• BETTER_AUTH_SECRET is set to a unique production value
• SITE_URL matches your production domain (with https://)
• All NEXT_PUBLIC_* variables point to the production Convex deployment
• OAuth callback URLs updated in every provider dashboard
• Email provider API key is set and sending works
• Passkey rpId and origin match your production domain

Security

• HTTPS is enabled (required for secure cookies)
• BETTER_AUTH_SECRET is different from development
• No development or test credentials in production
• .env.local is in .gitignore
• Trusted origins are configured
• Rate limiting is enabled (on by default — do not disable)

Auth Flows

• Email/password sign-up works end-to-end
• Verification and password-reset emails are received
• Social OAuth flows complete successfully
• MFA setup and verification works (if enabled)
• Organization creation and invitations work (if enabled)

Monitoring

• Convex dashboard is accessible
• Audit logs are recording events
• Webhook endpoints are registered and receiving events
• Error alerting is configured

Compliance

• Audit logging is active (always-on by default)
• Data retention policy is defined
• Privacy policy reflects auth data collection
• Cookie consent banner is added (if required by jurisdiction)

Post-Launch

Once you are live:

1. Monitor the first 24 hours — Watch Convex function logs for unexpected errors.
2. Verify webhook deliveries — Confirm all endpoints are receiving events.
3. Test the production sign-up flow — Create a real account through the live app.
4. Set up alerts — Configure notifications for failed sign-ins, user bans, and system errors.

Next Steps

• Environment Variables — Full reference for every variable your deployment uses.
• Webhooks — Set up real-time event delivery to your systems.
• Audit Logs — Configure compliance and security logging.
• Rate Limiting — Customize rate-limit thresholds for your use case.