Deploying Makerkit SaaS Boilerplate with Supabase and Cloudflare

Deploying Makerkit SaaS Boilerplate with Supabase and Cloudflare

A complete guide on setting up and deploying Makerkit SaaS boilerplate from local development to production using Supabase and Cloudflare. This guide is not a replacement to the official documentation but a simplified version to help you get started quickly. Please always refer to the official documentation for the most up-to-date information .

Prerequisites

To follow this guide, you need the following tools and software installed on your machine:

  1. Node.js 18.x or later - Download Node.js
  2. Docker - Download Docker
  3. Pnpm - Install Pnpm
  4. Supabase Account - Sign up for Supabase
  5. Cloudflare Pages - Sign up for Cloudflare Pages
  6. Access to Makerkit Github Repo - Get Makerkit

Local Setup

The local setup provides us with a development environment to test and make changes to the boilerplate before deploying to production. In this guide we will not setup mail providers, payment processors, or other services. We will only focus on the minimal setup and deploy it to Cloudflare.

  1. Clone the Repository

    This command clones the repository using SSH:

    git clone git@github.com:makerkit/next-supabase-saas-kit-turbo.git <your-project-name>
    

    If you don't have SSH setup, use HTTPS:

    git clone https://github.com/makerkit/next-supabase-saas-kit-turbo <your-project-name>
    
  2. Navigate to the Project Directory

    cd <your-project-name>
    
  3. Remove the Original Origin

    git remote rm origin
    
  4. Add Upstream Repository

    git remote add upstream git@github.com:makerkit/next-supabase-saas-kit-turbo
    
  5. Pull Updates from Upstream

    git pull upstream main
    
  6. Install Dependencies

    pnpm install
    
  7. Add Your Repository

    • Create a new GitHub repository.
    • Link your local repository to the new GitHub repository:
      git remote add origin git@github.com:your-username/<your-repo-name>.git
      git branch -M main
      git push -u origin main
      
  8. Start Docker

    At this point you want to make sure Docker is running on your machine. The boilerplate uses Docker to run Supabase locally. Now that docker is running lets start the Supabase service:

    pnpm run supabase:web:start
    

    You should see a result like this if the service started successfully:

     API URL: http://127.0.0.1:54321
      GraphQL URL: http://127.0.0.1:54321/graphql/v1
    S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
           DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
       Studio URL: http://127.0.0.1:54323
     Inbucket URL: http://127.0.0.1:54324
       JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
         anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
    service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
    S3 Access Key: 625729a08b95bf1b7ff351a663f3a23c
    S3 Secret Key: 850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907
        S3 Region: local
    

    *Take note of your service role key as you will need it in the next step.

  9. Create .env.local File

    • If you have'nt already opened the project in your code editor, do so now.
    • Navigate to apps/web directory.
    • Create a .env.local file and add your Supabase service role key:
      SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
      
  10. Start the Development Server

    pnpm dev
    
  11. Sign in with Makerkit Test Account

    • Email: test@makerkit.dev
    • Password: testingpassword

Congratulations! You have successfully set up the Makerkit SaaS boilerplate locally.

  1. Sign into Supabase and Create a New Project

    • Add a project name
    • Add a password
    • Copy and save the password
    • Select the region closest to you
  2. Copy and save these Supabase Project Details

    • Anon public key
    • Service role key
    • Project URL
  3. Link Local Project to Remote Supabase

    pnpm --filter web supabase link --project-ref <your-project-ref>
    
    • You can find your project ref ID in the Supabase dashboard on the project settings page.
    • You may be required to login to your Supabase account to create an access token.
    • When prompted, enter your project database password.
  4. Push to Supabase

    This command will push the database schema to your remote Supabase project.

    pnpm --filter web supabase db push
    
  5. Verify Success on Supabase Dashboard

Log in to your Supabase dashboard and navigate to table editor and verify that the tables have been created successfully.

Cloudflare Setup

  1. Opt into Edge Runtime, Downgrade Supabase Auth and insert cloudflare scripts

    • Navigate to apps/web/app/layout.tsx

    • Add the following line:

      export const runtime = "edge";
      
    • Place this override in the root package.json file:

       "pnpm": {
          "overrides": {
             "@supabase/auth-js": "2.62.0"
          }
        }
      
    • Add Scripts to apps/web/package.json

      "scripts": {
          "cloudflare:build": "pnpm dlx @cloudflare/next-on-pages",
          "cloudflare:preview": "pnpm dlx wrangler pages dev .next --compatibility-flag=nodejs_compat"
      }
      
    • Push the changes to your repository.

  2. For testing Cloudflare Setup Locally (Optional)

Please refer to the official documentation for more information on installing the cloudflare CLI.

Once you have the CLI installed, you can run the following commands to test the cloudflare setup locally:

  • Build a preview:
    pnpm run cloudflare:build
    
  • Run the preview:
    pnpm run cloudflare:preview
    

Deploy on Cloudflare

  1. Navigate to Cloudflare Pages

    • Click Create an application.
    • Choose the pages tab.
    • Connect to your GitHub and select a repository.
    • Choose a project name (this will make up your site url https://project-name.pages.dev/ )
    • Set the framework preset to Next.js. (this should apply default settings)
  2. Set Root Directory Path

    • Advanced: /apps/web
  3. Add Environment Variables

    It is required to manually add environment variables to Cloudflare Pages. You can add them in the settings tab of your Cloudflare Pages application. Here are some of the required environment variables:

    NEXT_PUBLIC_PRODUCT_NAME = Project Name
    NEXT_PUBLIC_SITE_DESCRIPTION = "Your Site Description"
    NEXT_PUBLIC_SITE_TITLE = "Your site title"
    NEXT_PUBLIC_SITE_URL = https://project-name.pages.dev
    NEXT_PUBLIC_SUPABASE_URL = https://your-supabase-url.supabase.co
    NEXT_PUBLIC_SUPABASE_ANON_KEY = your-supabase-anon-key
    SUPABASE_DB_WEBHOOK_SECRET = your-supabase-webhook-secret (This is a secret key you generate)
    NEXT_PUBLIC_LOCALES_PATH = apps/web/public/locales
    NEXT_PUBLIC_AUTH_MAGIC_LINK = false
    NEXT_PUBLIC_AUTH_PASSWORD = true
    NEXT_PUBLIC_DEFAULT_THEME_MODE = light
    NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING = false
    NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION = true
    NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS = true
    NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING = true
    NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION = true
    NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION = true
    NEXT_PUBLIC_ENABLE_THEME_TOGGLE = true
    NEXT_PUBLIC_LANGUAGE_PRIORITY = application
    CMS_CLIENT = keystatic
    MAILER_PROVIDER = resend
    NEXT_PUBLIC_THEME_COLOR = "#ffffff"
    NEXT_PUBLIC_THEME_COLOR_DARK = "#0a0a0a"
    
  4. Save and Deploy on Cloudflare

    • Click Save and Deploy.
    • Wait for the deployment to complete.
    • On completion your site will be live at https://project-name.pages.dev/
    • You will likely have an error on your first deploy and that is due to not setting the compatibility flags.
  5. Setting compatibility flags - Final Settings in Cloudflare

    • Navigate to Project > Settings > Functions.
    • Add nodejs_compat to both production and preview compatibility flags.
    • Navigate to Workers & Pages > View Details > Manage Deployment > Retry Deployment.

Final Steps on Supabase

  1. Setup Supabase Webhooks

    • Navigate to Supabase > Database > Webhooks > Create Webhook

    • Add the following webhooks:

      • Name: accounts_teardown
        Table: public.accounts
        Event: delete
        URL: https://project-name.pages.dev/api/db/webhooks
        Timeout: 5000
        Add New Header: X-Supabase-Event-Signature SUPABASE_DB_WEBHOOK_SECRET

      • Name: subscriptions_delete
        Table: public.subscriptions
        Event: delete
        URL: https://project-name.pages.dev/api/db/webhooks
        Timeout: 5000
        Add New Header: X-Supabase-Event-Signature SUPABASE_DB_WEBHOOK_SECRET

      • Name: invitations_insert
        Table: public.invitations
        Event: insert
        URL: https://project-name.pages.dev/api/db/webhooks
        Timeout: 5000
        Add New Header: X-Supabase-Event-Signature SUPABASE_DB_WEBHOOK_SECRET

  2. Set Authentication URL

    • Navigate to Supabase > Authentication > URL Configuration
    • Add the following URL: https://project-name.pages.dev
    • Add a redirect URL: https://project-name.pages.dev/auth/callback

Testing and Final Configuration

  1. Test the Site

    • Navigate to your Cloudflare Pages URL.
    • Sign up with a new account.
    • Verify that you can sign in and out.
    • Test the functionality of the site.
  2. Set Up Payment Processor

    • Select either Stripe or Lemonsqueezy as your payment processor.
    • Add your payment processor to the .env.local file, test and add them to cloudflare environment variables.
  3. Set Up CMS

    • By default Makerkit uses Keystatic as the CMS. If you wish to use keystatics this will require github mode. Please follow these instructions to monkey-patch the fetch function.
    • Alternatively, you can use the Wordpress CMS. Please follow these instructions to set up the Wordpress CMS.
  4. Set up Mail Provider

    • Default is Supabase mail, which is rate-limited.
    • Use either Cloudflare or Resend as mail provider:
      MAILER_PROVIDER=resend
      
      MAILER_PROVIDER=cloudflare
      

By following these steps, you will have successfully set up and deployed your Makerkit SaaS boilerplate to production using Supabase and Cloudflare. If you need help or have any questions, please refer to the official documentation or reach out to the Makerkit discord community for support.