Production Deployment | Client Guides

This guide will walk you through deploying your SaaS application to production, including environment setup, database migrations, and webhook configuration.

ℹ️

Prerequisites

Completed customization
Production database setup
OAuth providers configured

💡

Documentation System

If you want to keep, modify, or remove the documentation system before production, see the Managing Guides guide.

Pre-Deployment Checklist

Before deploying to production, ensure you have completed these customizations:

Customized theme colors and branding (logo, site name)
Configured OAuth providers (GitHub, Google)
Set up Stripe and/or LemonSqueezy billing
Configured admin emails
Updated pricing plans and features
Tested all functionality locally

Deployment Steps

Set Up Production Database

Choose a PostgreSQL hosting provider and create a production database. Recommended providers:

Supabase - Free tier available, excellent PostgreSQL hosting
Neon - Serverless PostgreSQL with generous free tier
Railway - Simple deployment with database included
Vercel Postgres - Integrated with Vercel deployments

Once created, copy your database connection string (it should look like this):

Example Connection String

1postgresql://username:password@host.example.com:5432/database_name

You'll use this in the next step.

Configure Environment Variables

Set up your production environment variables in your hosting platform. These are the required variables:

.env.production (Reference Only)

1# Database
2DATABASE_URL="postgresql://user:pass@host:5432/dbname"
3 
4# Auth.js
5AUTH_URL="https://yourdomain.com"
6AUTH_SECRET="your-production-secret-here"
7 
8# App URL (used for OAuth callbacks and email links)
9NEXT_PUBLIC_APP_URL="https://yourdomain.com"
10 
11# OAuth Providers
12AUTH_GITHUB_ID="your-github-client-id"
13AUTH_GITHUB_SECRET="your-github-client-secret"
14AUTH_GOOGLE_ID="your-google-client-id"
15AUTH_GOOGLE_SECRET="your-google-client-secret"
16 
17# Stripe (if using)
18STRIPE_SECRET_KEY="sk_live_..."
19STRIPE_WEBHOOK_SECRET="whsec_..."
20NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_..."
21 
22# LemonSqueezy (if using)
23LEMONSQUEEZY_API_KEY="your-lemonsqueezy-api-key"
24LEMONSQUEEZY_WEBHOOK_SECRET="your-webhook-secret"
25LEMONSQUEEZY_STORE_ID="your-store-id"
26 
27# Admin Email (bootstrap admin - always has access)
28ADMIN_EMAIL="admin@yourdomain.com"
29 
30# Feature Flags (optional)
31ENABLE_STRIPE="true"
32ENABLE_LEMONSQUEEZY="true"

⚠️

Security Notes

Never commit .env.production to git
Use production OAuth credentials (not development)
Use Stripe live keys (not test keys)
Generate a strong AUTH_SECRET: openssl rand -base64 32

Run Database Migrations

Push your database schema to production using Prisma:

Terminal

1# Set production database URL temporarily
2export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
3 
4# Push schema to production database
5npx prisma db push
6 
7# Optional: Seed with initial data if needed
8npx prisma db seed

ℹ️

Migration Strategy

For the first deployment, prisma db push is sufficient. For future updates with existing data, consider using prisma migrate to safely evolve your schema without data loss.

Build and Test Locally

Before deploying, verify your production build works locally:

Terminal

1# Create production build
2npm run build
3 
4# Test the production build locally
5npm start

Visit http://localhost:3000 and verify:

Authentication works
Pricing page displays correctly
Dashboard loads without errors
All customizations are visible

🚨

Build Errors?

If you see TypeScript errors or build failures, check your environment variables and ensure all required dependencies are installed. Run npm install and npx prisma generate if needed.

Deploy to Hosting Platform

Deploy to your chosen hosting platform. This starter kit works with:

Vercel (Recommended)

Best for Next.js applications with zero-config deployment:

Terminal

1# Install Vercel CLI
2npm i -g vercel
3 
4# Deploy
5vercel --prod

Or connect your GitHub repository at vercel.com for automatic deployments.

Netlify

Alternative platform with similar features:

netlify.toml

1[build]
2  command = "npm run build"
3  publish = ".next"
4 
5[[plugins]]
6  package = "@netlify/plugin-nextjs"

Railway / Render

Connect your GitHub repo and configure the build command as npm run buildwith start command npm start.

Configure Webhook Endpoints

Set up webhooks in Stripe and/or LemonSqueezy to handle subscription events:

Webhook URLs:

Stripe: https://yourdomain.com/api/billing/stripe/webhook
LemonSqueezy: https://yourdomain.com/api/billing/lemonsqueezy/webhook

For Stripe:

Go to Stripe Dashboard → Webhooks
Click "Add endpoint"
Enter your webhook URL: https://yourdomain.com/api/billing/stripe/webhook
Select events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted
Copy the webhook signing secret and add it to your environment variables as STRIPE_WEBHOOK_SECRET

For LemonSqueezy:

Go to LemonSqueezy → Settings → Webhooks
Create a new webhook
Enter your webhook URL: https://yourdomain.com/api/billing/lemonsqueezy/webhook
Copy the webhook secret and add it to your environment variables as LEMONSQUEEZY_WEBHOOK_SECRET

Verify Production Deployment

After deployment, test all critical functionality:

OAuth login works with GitHub and Google

Pricing page displays correctly

Stripe/LemonSqueezy checkout flow works

Subscription updates are reflected in dashboard

Admin dashboard accessible to configured admin emails

Dark mode toggle works

Mobile responsive design looks good

Post-Deployment Tasks

Set Up Domain (Optional)

If using a custom domain:

Add your domain in your hosting platform settings
Update DNS records with your domain registrar
Update AUTH_URL environment variable to use your custom domain
Update OAuth callback URLs in GitHub/Google settings
Update webhook URLs in Stripe/LemonSqueezy

Enable SSL/HTTPS

Most hosting platforms (Vercel, Netlify, Railway) automatically provide SSL certificates. Verify your site loads with https:// and redirects from http://.

Set Up Monitoring (Recommended)

Consider adding error tracking and analytics:

Sentry - Error tracking and monitoring
Vercel Analytics - Built-in if using Vercel
Google Analytics - User behavior tracking
PostHog - Product analytics and session replay

Test Payment Flows

Use Stripe test cards to verify the complete payment flow:

Test card: 4242 4242 4242 4242 (success)
Verify webhooks are received and processed
Check that subscription status updates in database
Test subscription cancellation flow

Troubleshooting

Authentication fails in production

Check these common issues:

Verify AUTH_URL matches your production domain
Update OAuth callback URLs in GitHub/Google to include production URL
Ensure AUTH_SECRET is set and different from development
Check that environment variables are properly set in hosting platform

Webhooks not being received

Debug webhook issues:

Verify webhook URLs are correct in Stripe/LemonSqueezy dashboards
Check webhook signing secrets match environment variables
Review webhook logs in Stripe/LemonSqueezy for delivery errors
Test webhook endpoints manually using their testing tools

Database connection errors

Common database issues:

Verify DATABASE_URL format is correct
Ensure database allows connections from your hosting platform's IP range
Check that database is running and accessible
Run npx prisma db push to ensure schema is up-to-date

Environment variables not working

If changes to environment variables aren't taking effect:

Redeploy your application after updating variables
Check variable names match exactly (case-sensitive)
For client-side variables, ensure they start with NEXT_PUBLIC_
Clear build cache and rebuild if using Vercel/Netlify

Continuous Deployment

Once initial deployment is complete, set up automatic deployments:

GitHub Integration (Recommended)

Connect your GitHub repository to your hosting platform
Choose your production branch (usually main or master)
Enable automatic deployments on push
Every commit to your production branch will trigger a new deployment

Preview Deployments

Platforms like Vercel and Netlify automatically create preview deployments for pull requests. This lets you test changes before merging to production.

Related Guides

Customize Theme Colors

Learn how to customize the color palette to match your brand identity using CSS variables

Customize Logo & Branding

Add your company logo and update branding elements throughout the app

Customize UI Components

Fine-tune button styles, cards, inputs, and other UI components to match your design

Vercel Features

Learn how to leverage Vercel's built-in features: Web Analytics, Speed Insights, and Preview Deployments

🎉 Congratulations!

Your SaaS application is now live in production! You've successfully:

Configured production environment and database
Deployed your customized application
Set up billing webhooks
Verified all critical functionality

Your users can now sign up, subscribe to plans, and start using your SaaS product!

This guide will walk you through deploying your SaaS application to production, including environment setup, database migrations, and webhook configuration.

ℹ️

Prerequisites

Completed customization
Production database setup
OAuth providers configured

💡

Documentation System

If you want to keep, modify, or remove the documentation system before production, see the Managing Guides guide.

Pre-Deployment Checklist

Before deploying to production, ensure you have completed these customizations:

Customized theme colors and branding (logo, site name)
Configured OAuth providers (GitHub, Google)
Set up Stripe and/or LemonSqueezy billing
Configured admin emails
Updated pricing plans and features
Tested all functionality locally

Deployment Steps

Set Up Production Database

Choose a PostgreSQL hosting provider and create a production database. Recommended providers:

Supabase - Free tier available, excellent PostgreSQL hosting
Neon - Serverless PostgreSQL with generous free tier
Railway - Simple deployment with database included
Vercel Postgres - Integrated with Vercel deployments

Once created, copy your database connection string (it should look like this):

Example Connection String

1postgresql://username:password@host.example.com:5432/database_name

You'll use this in the next step.

Configure Environment Variables

Set up your production environment variables in your hosting platform. These are the required variables:

.env.production (Reference Only)

1# Database
2DATABASE_URL="postgresql://user:pass@host:5432/dbname"
3 
4# Auth.js
5AUTH_URL="https://yourdomain.com"
6AUTH_SECRET="your-production-secret-here"
7 
8# App URL (used for OAuth callbacks and email links)
9NEXT_PUBLIC_APP_URL="https://yourdomain.com"
10 
11# OAuth Providers
12AUTH_GITHUB_ID="your-github-client-id"
13AUTH_GITHUB_SECRET="your-github-client-secret"
14AUTH_GOOGLE_ID="your-google-client-id"
15AUTH_GOOGLE_SECRET="your-google-client-secret"
16 
17# Stripe (if using)
18STRIPE_SECRET_KEY="sk_live_..."
19STRIPE_WEBHOOK_SECRET="whsec_..."
20NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_live_..."
21 
22# LemonSqueezy (if using)
23LEMONSQUEEZY_API_KEY="your-lemonsqueezy-api-key"
24LEMONSQUEEZY_WEBHOOK_SECRET="your-webhook-secret"
25LEMONSQUEEZY_STORE_ID="your-store-id"
26 
27# Admin Email (bootstrap admin - always has access)
28ADMIN_EMAIL="admin@yourdomain.com"
29 
30# Feature Flags (optional)
31ENABLE_STRIPE="true"
32ENABLE_LEMONSQUEEZY="true"

⚠️

Security Notes

Never commit .env.production to git
Use production OAuth credentials (not development)
Use Stripe live keys (not test keys)
Generate a strong AUTH_SECRET: openssl rand -base64 32

Run Database Migrations

Push your database schema to production using Prisma:

Terminal

1# Set production database URL temporarily
2export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
3 
4# Push schema to production database
5npx prisma db push
6 
7# Optional: Seed with initial data if needed
8npx prisma db seed

ℹ️

Migration Strategy

For the first deployment, prisma db push is sufficient. For future updates with existing data, consider using prisma migrate to safely evolve your schema without data loss.

Build and Test Locally

Before deploying, verify your production build works locally:

Terminal

1# Create production build
2npm run build
3 
4# Test the production build locally
5npm start

Visit http://localhost:3000 and verify:

Authentication works
Pricing page displays correctly
Dashboard loads without errors
All customizations are visible

🚨

Build Errors?

If you see TypeScript errors or build failures, check your environment variables and ensure all required dependencies are installed. Run npm install and npx prisma generate if needed.

Deploy to Hosting Platform

Deploy to your chosen hosting platform. This starter kit works with:

Vercel (Recommended)

Best for Next.js applications with zero-config deployment:

Terminal

1# Install Vercel CLI
2npm i -g vercel
3 
4# Deploy
5vercel --prod

Or connect your GitHub repository at vercel.com for automatic deployments.

Netlify

Alternative platform with similar features:

netlify.toml

1[build]
2  command = "npm run build"
3  publish = ".next"
4 
5[[plugins]]
6  package = "@netlify/plugin-nextjs"

Railway / Render

Connect your GitHub repo and configure the build command as npm run buildwith start command npm start.

Configure Webhook Endpoints

Set up webhooks in Stripe and/or LemonSqueezy to handle subscription events:

Webhook URLs:

Stripe: https://yourdomain.com/api/billing/stripe/webhook
LemonSqueezy: https://yourdomain.com/api/billing/lemonsqueezy/webhook

For Stripe:

Go to Stripe Dashboard → Webhooks
Click "Add endpoint"
Enter your webhook URL: https://yourdomain.com/api/billing/stripe/webhook
Select events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted
Copy the webhook signing secret and add it to your environment variables as STRIPE_WEBHOOK_SECRET

For LemonSqueezy:

Go to LemonSqueezy → Settings → Webhooks
Create a new webhook
Enter your webhook URL: https://yourdomain.com/api/billing/lemonsqueezy/webhook
Copy the webhook secret and add it to your environment variables as LEMONSQUEEZY_WEBHOOK_SECRET

Verify Production Deployment

After deployment, test all critical functionality:

OAuth login works with GitHub and Google

Pricing page displays correctly

Stripe/LemonSqueezy checkout flow works

Subscription updates are reflected in dashboard

Admin dashboard accessible to configured admin emails

Dark mode toggle works

Mobile responsive design looks good

Post-Deployment Tasks

Set Up Domain (Optional)

If using a custom domain:

Add your domain in your hosting platform settings
Update DNS records with your domain registrar
Update AUTH_URL environment variable to use your custom domain
Update OAuth callback URLs in GitHub/Google settings
Update webhook URLs in Stripe/LemonSqueezy

Enable SSL/HTTPS

Most hosting platforms (Vercel, Netlify, Railway) automatically provide SSL certificates. Verify your site loads with https:// and redirects from http://.

Set Up Monitoring (Recommended)

Consider adding error tracking and analytics:

Sentry - Error tracking and monitoring
Vercel Analytics - Built-in if using Vercel
Google Analytics - User behavior tracking
PostHog - Product analytics and session replay

Test Payment Flows

Use Stripe test cards to verify the complete payment flow:

Test card: 4242 4242 4242 4242 (success)
Verify webhooks are received and processed
Check that subscription status updates in database
Test subscription cancellation flow

Troubleshooting

Authentication fails in production

Check these common issues:

Verify AUTH_URL matches your production domain
Update OAuth callback URLs in GitHub/Google to include production URL
Ensure AUTH_SECRET is set and different from development
Check that environment variables are properly set in hosting platform

Webhooks not being received

Debug webhook issues:

Verify webhook URLs are correct in Stripe/LemonSqueezy dashboards
Check webhook signing secrets match environment variables
Review webhook logs in Stripe/LemonSqueezy for delivery errors
Test webhook endpoints manually using their testing tools

Database connection errors

Common database issues:

Verify DATABASE_URL format is correct
Ensure database allows connections from your hosting platform's IP range
Check that database is running and accessible
Run npx prisma db push to ensure schema is up-to-date

Environment variables not working

If changes to environment variables aren't taking effect:

Redeploy your application after updating variables
Check variable names match exactly (case-sensitive)
For client-side variables, ensure they start with NEXT_PUBLIC_
Clear build cache and rebuild if using Vercel/Netlify

Continuous Deployment

Once initial deployment is complete, set up automatic deployments:

GitHub Integration (Recommended)

Connect your GitHub repository to your hosting platform
Choose your production branch (usually main or master)
Enable automatic deployments on push
Every commit to your production branch will trigger a new deployment

Preview Deployments

Platforms like Vercel and Netlify automatically create preview deployments for pull requests. This lets you test changes before merging to production.

🎉 Congratulations!

Your SaaS application is now live in production! You've successfully:

Configured production environment and database
Deployed your customized application
Set up billing webhooks
Verified all critical functionality

Your users can now sign up, subscribe to plans, and start using your SaaS product!