Quick start docs for Ship SaaS

Step 1: Fork the repository

After purchasing the Ship SaaS boilerplate you will receive an invite to the GitHub repository. Accept the invitation and fork the repository.

Step 2: Configure Supabase

Create a free Supabase account at supabase.com.

Step 2.1: Create a Supabase project

Create a new Supabase project. Then, copy the Supabase URL, anon public key and service role key and add it as environment variables for your application. These values can be found on the API settings page of your Supabase project (https://app.supabase.io/project/{project_id}/settings/api).

The environment variables are named:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY

To configure environment variables locally for this project rename the .env.example file in the root directory to .env.local and modify the values in the file.

Step 2.2: Create Supabase database tables and storage bucket

In the src/sql folder you will find a quick_start.sql script. Run this script on your Supabase database to create the required tables, storage buckets and policies. To run this script go to the SQL editor page (https://app.supabase.io/project/{project_id}/editor/sql) of your Supabase project.

After you created the "avatars" storage bucket (using the quick_start.sql script) you should change the bucket's access to public. This can be done by navigating to the storage buckets page (https://app.supabase.io/project/{project_id}/storage/buckets), clicking on the options menu for the bucket, and then clicking "Make public".

A more detailed description with screenshots about how to configure Supabase can be found here.

Step 3: Configure Stripe

Create a free Stripe account at stripe.com

To complete the following steps, ensure that "test mode" in Stripe is enabled.

Step 3.1: Configure webhooks

Stripe webhooks are used to sync data from Stripe to your Supabase database. To configure Stripe webhooks follow these steps:

• Create a new endpoint on the Stripe Test endpoints page.
• Set the endpoint URL to the URL of your application - e.g. https://url-of-your-application/api/webhooks. If this URL is not yet known, use any placeholder URL for now.
• Select the events that you want to receive. The events handled by this app are:
  • product.created
  • product.updated
  • product.deleted
  • price.created
  • price.updated
  • price.deleted
  • checkout.session.completed
  • customer.updated
  • customer.deleted
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
• Finally, copy the Signing secret for the webhook - it is needed in the next step.

Step 3.2: Set environment variables

To securely interact with Stripe, add the following environment variables for your application:

• For local environment

  • NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET

• For deployed applications

  • NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY_LIVE
  • STRIPE_SECRET_KEY_LIVE
  • STRIPE_WEBHOOK_SECRET_LIVE

• For both local and deployed applications (these settings will depend on your pricing structure)

  • NEXT_PUBLIC_PRICE_BASIC_MONTHLY
  • NEXT_PUBLIC_PRICE_BASIC_YEARLY
  • NEXT_PUBLIC_PRICE_PRO_MONTHLY
  • NEXT_PUBLIC_PRICE_PRO_YEARLY
  • NEXT_PUBLIC_PRICE_MASTER_MONTHLY
  • NEXT_PUBLIC_PRICE_MASTER_YEARLY

The first two keys can be found on the API keys page in Stripe. The STRIPE_WEBHOOK_SECRET or STRIPE_WEBHOOK_SECRET_LIVE value is the webhook Signing secret you copied in the previous step.

Step 3.3: Test webhooks

* Remember to update your webhook with the correct URL if you haven't done it in the previous step.

To ensure that the webhooks work with your deployed application, send a product.created test event from your Stripe test dashboard by clicking the Send test event button. If everything is configured correctly, a test product will be created in your Supabase database.

If the configuration is working, delete the test products created via the webhook from your database.

Step 3.4: Create product and pricing information

Create your products with prices in your Stripe Dashboard. When you create or update your product and price information, the changes will automatically be synced to your Supabase database.

For example, this boilerplate has been set up to support 3 different products with 2 different prices (monthly/yearly) each.

E.g.:

• Product 1: Basic
  • Price 1: 19.99 USD per month
  • Price 2: 199.99 USD per year
• Product 2: Professional
  • Price 1: 24.99 USD per month
  • Price 2: 249.99 USD per year
• Product 3: Master
  • Price 1: 39.99 USD per month
  • Price 2: 399.99 USD per year

Set this up according to your business model and pricing structure.

Once you have configured your products and prices, add the price ID environment variables:

• NEXT_PUBLIC_PRICE_BASIC_MONTHLY
• NEXT_PUBLIC_PRICE_BASIC_YEARLY
• NEXT_PUBLIC_PRICE_PRO_MONTHLY
• NEXT_PUBLIC_PRICE_PRO_YEARLY
• NEXT_PUBLIC_PRICE_MASTER_MONTHLY
• NEXT_PUBLIC_PRICE_MASTER_YEARLY

Step 3.5: Configure your Stripe customer portal

• Set your business branding and identity in the Stripe settings
• Configure your Customer Portal settings
• Toggle on "Allow customers to update their payment methods"
• Toggle on "Allow customers to update subscriptions"
• Toggle on "Allow customers to cancel subscriptions"
• Set up the required business information and links (e.g. terms and conditions, usage policy, etc.)

Step 4: Run the project locally

Clone the repository to your PC.

Duplicate the .env.example file in the root directory and rename it to .env.local. Add all the required environment variables.

A complete list of required environment variables with descriptions can be found here: list of environment variables

To run this project locally run the following commands in the root directory:

npm install
npm run dev
# or
yarn
yarn dev

Navigate to http://localhost:3000 to view the application.

Step 5: Deploy to production

* Optional step before deploying the project: run the npm run lint command to see possible warnings and errors in the application.

Ensure that you have all the required environment variables ready as listed here.

Disable "test mode" on Stripe. To verify that you are running in production mode, test checking out with the Stripe test card. The test card should not work.

Deploy your application on your preferred hosting platform or check out the following guides for:

• Deploying on Vercel
• Deploying on Heroku
• Deploying on AWS Amplify
• Deploying on Digital Ocean (coming soon - get notified)
• Deploying on Netlify (coming soon - get notified)
• Deploying on Render (coming soon - get notified)