Skip to main content

🚀 Deployment Guide

Complete guide for deploying MongoDB Minute to production.

Pre-Deployment Checklist​

Before deploying, ensure:

  • All tests passing
  • Environment variables documented
  • MongoDB indexes created
  • .gitignore includes .env.local
  • Production build succeeds (npm run build)
  • Database connection tested
  • Authentication working
  • Workflow system tested

Environment Variables​

Required environment variables for production:

MongoDB Configuration​

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority
MONGODB_DB=mongodb_minute

Authentication​

JWT_SECRET=your-secure-random-secret-key
JWT_EXPIRES_IN=7d
MAGIC_LINK_EXPIRES_IN=15m

Email Service (Gmail SMTP)​

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_FROM=noreply@mongodb.com

Application​

NODE_ENV=production
NEXT_PUBLIC_BASE_URL=https://your-domain.com

Vercel Deployment​

Initial Setup​

  1. Connect Repository

    • Go to Vercel Dashboard
    • Click "Add New Project"
    • Import your GitHub repository
    • Select the repository

  2. Configure Build Settings

    • Framework Preset: Next.js
    • Root Directory: ./ (or your app directory)
    • Build Command: npm run build
    • Output Directory: .next

  3. Add Environment Variables

    • Go to Project Settings → Environment Variables
    • Add all required variables (see above)
    • Set for Production, Preview, and Development

  4. Deploy

    • Click "Deploy"
    • Wait for build to complete
    • Verify deployment URL

Custom Domain​

  1. Go to Project Settings → Domains
  2. Add your custom domain
  3. Follow DNS configuration instructions
  4. Wait for SSL certificate provisioning

Environment-Specific Variables​

Set different values for:

  • Production: Live environment
  • Preview: Pull request previews
  • Development: Local development

MongoDB Atlas Setup​

Database Configuration​

  1. Create Cluster

    • Log in to MongoDB Atlas
    • Create new cluster (or use existing)
    • Choose region closest to your deployment

  2. Create Database User

    • Go to Database Access
    • Create user with read/write permissions
    • Save credentials securely

  3. Network Access

    • Go to Network Access
    • Add IP address or allow all (0.0.0.0/0) for Vercel
    • Vercel IPs change, so consider allowing all

  4. Get Connection String

    • Go to Clusters → Connect
    • Choose "Connect your application"
    • Copy connection string
    • Replace <password> with your database user password

Create Indexes​

Run these indexes for optimal performance:

// Unique slug for URL routing
db.episodes.createIndex({ slug: 1 }, { unique: true })

// Query optimization for admin list
db.episodes.createIndex({ status: 1, episodeNumber: 1 })

// Public filtering by category
db.episodes.createIndex({ category: 1 })

// Latest episodes query
db.episodes.createIndex({ status: 1, createdAt: -1 })

// Workflow stage queries
db.episodes.createIndex({ "workflow.currentStage": 1 })

// Review queue queries
db.episodes.createIndex({ 
  "workflow.currentStage": 1, 
  "workflow.submittedForReview.timestamp": 1 
})

// User email lookup
db.users.createIndex({ email: 1 }, { unique: true })

Email Service Configuration​

Gmail SMTP Setup​

  1. Enable 2-Factor Authentication

    • Required for app passwords

  2. Generate App Password

    • Go to Google Account → Security
    • Enable 2-Step Verification
    • Generate App Password
    • Use this password in EMAIL_PASS

  3. Test Email Sending

    • Verify magic link emails are sent
    • Check spam folder if needed

Alternative Email Services​

Consider using:

  • SendGrid: More reliable for production
  • AWS SES: Cost-effective at scale
  • Mailgun: Developer-friendly API

Update lib/email.js accordingly.

Security Considerations​

Production Security​

  1. Environment Variables

    • Never commit .env.local
    • Use Vercel environment variables
    • Rotate secrets regularly

  2. JWT Secret

    • Use strong, random secret
    • Minimum 32 characters
    • Different for each environment

  3. HTTPS

    • Vercel provides SSL automatically
    • Verify certificate is active
    • Force HTTPS redirects

  4. CORS

    • Configure allowed origins
    • Restrict API access if needed

  5. Rate Limiting

    • Consider adding rate limiting
    • Protect against abuse
    • Use Vercel Edge Middleware

Performance Optimization​

Build Optimization​

  1. Enable Turbopack (Next.js 16+)

    • Already enabled in config
    • Faster builds and HMR

  2. Image Optimization

    • Use Next.js Image component
    • Configure image domains
    • Enable lazy loading

  3. Database Connection

    • Connection pooling enabled
    • Reuse connections
    • Monitor connection count

Caching Strategy​

  1. Static Generation

    • Consider ISR for public pages
    • Revalidate published episodes
    • Cache at CDN level

  2. API Caching

    • Cache public episode lists
    • Don't cache admin endpoints
    • Use appropriate cache headers

Monitoring & Analytics​

Vercel Analytics​

  1. Enable Vercel Analytics
  2. Track page views
  3. Monitor performance metrics

Error Tracking​

Consider integrating:

  • Sentry: Error tracking
  • LogRocket: Session replay
  • Vercel Logs: Built-in logging

Database Monitoring​

  • Use MongoDB Atlas monitoring
  • Set up alerts for:
    • High connection count
    • Slow queries
    • Storage limits

Post-Deployment​

Verification Steps​

  1. Test Authentication

    • Request magic link
    • Verify email delivery
    • Complete login flow

  2. Test Workflow

    • Create test episode
    • Submit for review
    • Approve episode
    • Verify workflow history

  3. Test Public Site

    • Browse episodes
    • Test search/filter
    • Verify episode detail pages
    • Check social links

  4. Test Admin Features

    • Access dashboard
    • Create/edit episodes
    • Generate QR codes
    • Update settings

DNS Configuration​

If using custom domain:

  1. Add DNS Records

    • CNAME: www → cname.vercel-dns.com
    • A Record: @ → Vercel IP (if needed)

  2. Verify SSL

    • Wait for certificate provisioning
    • Test HTTPS connection
    • Verify certificate validity

Troubleshooting​

Build Failures​

Issue: Build fails on Vercel

Solutions:

  • Check build logs for errors
  • Verify Node.js version (18+)
  • Ensure all dependencies are in package.json
  • Check environment variables are set

Database Connection Issues​

Issue: Cannot connect to MongoDB

Solutions:

  • Verify MONGODB_URI is correct
  • Check network access in Atlas
  • Verify database user permissions
  • Test connection string locally

Email Not Sending​

Issue: Magic links not received

Solutions:

  • Verify Gmail app password
  • Check spam folder
  • Verify EMAIL_FROM address
  • Test email service configuration
  • Consider using alternative service

Authentication Issues​

Issue: Login not working

Solutions:

  • Verify JWT secret is set
  • Check cookie settings
  • Verify email domain restriction
  • Check middleware configuration

Rollback Procedure​

If deployment has issues:

  1. Vercel Rollback

    • Go to Deployments
    • Find previous successful deployment
    • Click "Promote to Production"

  2. Database Rollback

    • Restore from backup if needed
    • Use MongoDB Atlas point-in-time restore

  3. Environment Variables

    • Revert to previous values
    • Verify configuration

Maintenance​

Regular Tasks​

  1. Update Dependencies

    • Check for security updates
    • Test updates in staging
    • Deploy updates regularly

  2. Database Maintenance

    • Monitor storage usage
    • Archive old episodes if needed
    • Optimize indexes

  3. Backup Strategy

    • Enable MongoDB Atlas backups
    • Regular database exports
    • Document restore procedures

Next Steps​