Deploy Supabase to Production

Configure your Supabase project for production with Postgres database, Row Level Security (RLS) policies, authentication, and webhooks. This guide covers the complete setup for your MakerKit Next.js Supabase Turbo application.

Overview

Create a Supabase Project

If you're not self-hosting Supabase, create a project at supabase.com.

1. Sign in to the Supabase Dashboard
2. Click New Project
3. Choose your organization
4. Enter a project name and generate a database password
5. Select a region close to your users

Retrieve API Credentials

Navigate to Project Settings > API to find your credentials:

Configure Authentication URLs

Set up redirect URLs so authentication flows work correctly.

Navigate to Authentication > URL Configuration and configure:

Site URL

Your production domain:

https://yourdomain.com

Redirect URLs

Add this pattern to allow all auth callbacks:

https://yourdomain.com/auth/callback**

The ** wildcard matches any path after /auth/callback, which MakerKit uses for different auth flows.

Configure SMTP

Supabase's built-in email service has strict rate limits (4 emails per hour) and low deliverability. Configure a real SMTP provider for production.

Navigate to Project Settings > Authentication > SMTP Settings:

1. Toggle Enable Custom SMTP
2. Enter your provider's credentials:

Recommended SMTP providers:

• Resend: MakerKit has native integration, simple setup
• SendGrid: High volume, good deliverability
• Mailgun: Developer-friendly, detailed analytics
• Postmark: Excellent deliverability, transactional focus

Update Email Templates

MakerKit provides custom email templates that solve a common Supabase authentication issue.

The Problem

Supabase uses PKCE (Proof Key for Code Exchange) for authentication. When a user clicks a confirmation link in their email and opens it in a different browser than where they signed up, authentication fails because the PKCE verifier is stored in the original browser.

The Solution

MakerKit's templates use token hash URLs instead of PKCE, which work regardless of which browser opens the link.

How to Update

1. Find the templates in your project at apps/web/supabase/templates/
2. In Supabase Dashboard, go to Authentication > Email Templates
3. For each email type (Confirm signup, Magic Link, etc.), replace the default template with MakerKit's version
4. Customize the templates with your branding

For detailed instructions, see the Authentication Emails guide.

Link Your Local Project

Connect your local development environment to your Supabase project using the CLI.

Login to Supabase

pnpm --filter web supabase login

Follow the browser prompts to authenticate.

Link the Project

pnpm --filter web supabase link

Select your project from the list and enter your database password when prompted.

Verification: Run supabase projects list to confirm the connection.

Push Database Migrations

Deploy MakerKit's database schema to your production Supabase instance:

pnpm --filter web supabase db push

The CLI displays a list of migrations to apply. Review them and confirm.

Expected tables: After pushing, you should see these tables in your Supabase Dashboard Table Editor:

• accounts: Team and personal accounts
• accounts_memberships: User-account relationships
• subscriptions: Billing subscriptions
• subscription_items: Line items for subscriptions
• invitations: Team invitations
• roles: Custom role definitions
• role_permissions: Permission assignments

Configure Database Webhooks

MakerKit uses database webhooks to respond to data changes. The primary webhook handles subscription cleanup when accounts are deleted.

Generate a Webhook Secret

Create a strong secret for authenticating webhook requests:

openssl rand -base64 32

Save this as SUPABASE_DB_WEBHOOK_SECRET in your hosting provider's environment variables.

Why Webhooks Matter

When a user deletes their account, MakerKit needs to:

1. Cancel their subscription with the billing provider
2. Clean up related data

The webhook triggers this cleanup automatically by calling your application's /api/db/webhook endpoint.

Create the Webhook

In Supabase Dashboard, navigate to Database > Webhooks:

1. Click Enable Webhooks if prompted
2. Click Create a new hook
3. Configure the webhook:

4. Add a header for authentication:
   • Name: X-Supabase-Event-Signature
   • Value: Your SUPABASE_DB_WEBHOOK_SECRET value

Webhook Configuration Reference

For reference, this is equivalent to the SQL trigger used in local development (from seed.sql):

create trigger "subscriptions_delete"
    after delete
    on "public"."subscriptions"
    for each row
execute function "supabase_functions"."http_request"(
    'https://yourdomain.com/api/db/webhook',
    'POST',
    '{"Content-Type":"application/json", "X-Supabase-Event-Signature":"YOUR_SECRET"}',
    '{}',
    '5000'
);

Webhooks for Older Versions

If you're using MakerKit version 2.17.1 or earlier, you need additional webhooks:

Version 2.17.2+ handles invitations through server actions, so only the subscriptions webhook is required.

Set Up Google Auth (Optional)

If you want Google login, configure it in both Google Cloud and Supabase.

In Google Cloud Console

1. Create a project at console.cloud.google.com
2. Navigate to APIs & Services > Credentials
3. Click Create Credentials > OAuth client ID
4. Select Web application
5. Add authorized redirect URI from Supabase (found in Authentication > Providers > Google)

In Supabase Dashboard

1. Go to Authentication > Providers
2. Enable Google
3. Enter your Client ID and Client Secret from Google Cloud

For detailed setup, see the Supabase Google Auth documentation.

MakerKit automatically shows Google login when you enable it in Supabase. No code changes needed.

Troubleshooting

"Invalid PKCE verifier" error

Users see this when clicking email links from a different browser. Update your email templates to use MakerKit's token hash approach. See Authentication Emails.

Webhooks not triggering

1. Verify the URL is publicly accessible
2. Check the X-Supabase-Event-Signature header matches your environment variable
3. Review logs in Database > Webhooks for error messages
4. Ensure your application is deployed and running

Authentication redirect fails

1. Confirm Site URL matches your exact domain (including www if used)
2. Verify Redirect URL includes the ** wildcard
3. Check browser console for specific error messages

Emails not delivered

1. Verify SMTP settings in Supabase Dashboard
2. Check your email provider's dashboard for delivery logs
3. Confirm your sending domain has proper DNS records (SPF, DKIM, DMARC)

Database password lost

If you forgot your database password, reset it in Project Settings > Database > Database Password. You'll need to re-link your local project after resetting.

Next Steps

• Environment Variables: Complete variable reference with Zod schemas
• Vercel Deployment: Deploy your Next.js application to Vercel
• Authentication Configuration: Configure OAuth providers and SMTP