Setup

Get running in 10-15 minutes. This guide walks through cloning, configuring environment variables, running migrations, and verifying everything works.

Clone and install

git clone <your-repo-url> my-saas
cd my-saas
pnpm install

Create environment file

cp .env.example .env.local

Open .env.local and configure the required values below.

Site URL

NEXT_PUBLIC_SITE_URL=http://localhost:3001

Used for SEO (sitemap, canonical URLs, OG images) and magic link emails.

Database (required)

You need a PostgreSQL database. Options:

Supabase (recommended):

  1. Create account at supabase.com
  2. Create a new project
  3. Go to Project Settings > Database > Connection string > URI
  4. Copy and replace [YOUR-PASSWORD] with your password

Neon:

  1. Create account at neon.tech
  2. Create a project and copy the connection string

Local Docker:

docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16

Then use: postgres://postgres:postgres@localhost:5432/postgres

DATABASE_URL=postgres://user:password@host:5432/database

Auth secret (required)

Generate a secret for signing tokens:

openssl rand -base64 32

AUTH_SECRET=<paste-generated-secret>

OAuth providers (optional)

Skip if using magic links only.

Google OAuth:

  1. Go to console.cloud.google.com/apis/credentials
  2. Create OAuth 2.0 credentials
  3. Add redirect URI: http://localhost:3001/api/auth/callback/google

GitHub OAuth:

  1. Go to github.com/settings/developers
  2. Create a new OAuth App
  3. Set callback URL: http://localhost:3001/api/auth/callback/github
AUTH_GOOGLE_ID=xxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=GOCSPX-xxx
AUTH_GITHUB_ID=Iv1.xxx
AUTH_GITHUB_SECRET=xxx

Email (optional to start)

Get API key from resend.com. Sandbox mode works for development.

RESEND_API_KEY=re_xxx
EMAIL_FROM_ADDRESS=noreply@yourdomain.com
EMAIL_FROM_NAME=My App

Billing (optional to start)

Configure when ready to monetize. See Billing for details.

Run database migrations

pnpm db:migrate

Start development server

pnpm dev

Open http://localhost:3001

Verify setup

After setup, verify everything works:

  • Visit / - You see the home page
  • Visit /login - You see magic link form + OAuth buttons
  • Visit /app/dashboard - Dashboard (after sign-in)
  • Visit /app/billing - Billing page
  • Visit /app/dashboard/setup - Setup status

Common issues

"Invalid OAuth callback"

Check callback URLs match exactly (including port 3001)

"Database connection failed"

  • Verify DATABASE_URL format
  • Check database is running

"AUTH_SECRET missing"

  • Generate with openssl rand -base64 32
  • Add to .env.local

Next: Explore the Features or dive into Authentication