Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher) - Download
• npm, yarn, or pnpm (comes with Node.js)
• Git - Download
• PostgreSQL - Local or cloud (Supabase, Neon, Railway, etc.)

Step 1: Clone the Repository

Once you've purchased ShipSecure, you will receive access to the GitHub repository. Clone it to your local machine:

git clone https://github.com/hasankemaldemirci/shipsecure.git my-saas
cd my-saas

Note: Replace my-saas with your desired project name.

Step 2: Install Dependencies

Install the project dependencies using your preferred package manager:

npm install
# or
yarn install
# or
pnpm install

This will install all required packages including Next.js, Prisma, Auth.js, and security libraries.

Step 3: Set Up Environment Variables

Create .env.local File

Copy the example environment file:

cp .env.example .env.local

Required Environment Variables

Open .env.local and configure the following:

Database

# Replace with your actual PostgreSQL connection string
# Format: postgresql://username:password@host:port/database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Where to get a database:

• Local PostgreSQL: Install PostgreSQL locally and create a database
• Supabase: Free tier available, get connection string from dashboard → Settings → Database
• Neon: Serverless PostgreSQL, free tier available, connection string in dashboard
• Railway: Easy setup, free tier available, connection string provided after creating database

Example connection strings:

• Local: postgresql://postgres:password@localhost:5432/mydb
• Supabase: postgresql://postgres.xxxxx:password@aws-0-us-east-1.pooler.supabase.com:6543/postgres

Authentication

# Generate AUTH_SECRET by running: npx auth secret
AUTH_SECRET=your-generated-secret-here

# GitHub OAuth credentials (required for GitHub sign-in)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Google OAuth credentials (optional, only if enabling Google sign-in)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

For detailed OAuth setup: See the Authentication Guide for step-by-step instructions on creating OAuth apps and getting credentials.

Optional: Rate Limiting (Production)

For better rate limiting on serverless platforms (Vercel, Netlify):

# Get these from Upstash Redis dashboard: https://console.upstash.com/
# Create a Redis database, then copy the REST URL and Token
UPSTASH_REDIS_REST_URL=https://your-redis-instance.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_upstash_token_here

Note:

• Rate limiting works without Redis in development (uses in-memory storage)
• Required for production on serverless platforms to prevent rate limit bypass
• Free tier available at Upstash (10,000 requests/day)

Public URL

# Development - keep this for local development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Production - update this to your actual domain after deployment
# Example: https://myapp.com or https://myapp.vercel.app
NEXT_PUBLIC_APP_URL=https://your-domain.com

When to update: After deploying to production, update this URL in your hosting provider's environment variables dashboard.

Google Analytics (Optional)

# Get your Measurement ID from Google Analytics 4
# https://analytics.google.com/ → Admin → Data Streams → Your Web Stream
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Setup steps:

1. Go to Google Analytics
2. Create a property for your domain
3. Add a Web data stream
4. Copy the Measurement ID (starts with G-)
5. Add to your environment variables

Step 4: Initialize Database

After setting up your DATABASE_URL, initialize the database schema:

Development (Quick Setup)

# Creates database tables directly (no migration files)
# Use this for quick development setup
npx prisma db push

What this does: Creates all database tables (users, sessions, accounts) defined in prisma/schema.prisma without creating migration files. Perfect for development when you don't need to track schema changes.

Production (With Migrations)

# Creates migration files for version control
# Use this if you want to track schema changes in Git
npx prisma migrate dev --name init

What this does: Creates migration files in prisma/migrations/ that you can commit to Git and deploy to production. Recommended if you're working in a team or want to track schema history.

Generate Prisma Client

After schema changes or when setting up on a new machine, generate the Prisma Client:

# Generates TypeScript types for your database schema
# Run this after: db push, migrate dev, or pulling schema changes
npx prisma generate

When to run: Prisma usually runs this automatically, but run manually if you see TypeScript errors about missing Prisma types.

Step 5: Run the Development Server

Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

You should see:

• Landing page
• Sign in available (at /api/auth/signin)
• Console warnings about missing OAuth credentials (expected until you configure them)

Verify Installation

Check Database Connection

The app should connect to your database automatically. If you see database errors:

1. Verify DATABASE_URL is correct
2. Ensure PostgreSQL is running (if local)
3. Check database credentials

Test Authentication

1. Navigate to /api/auth/signin
2. You'll see GitHub and Google sign-in buttons
3. They won't work until you configure OAuth (see Authentication Guide)

Troubleshooting

"Module not found" errors

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Database connection errors

Check these in order:

1. Verify DATABASE_URL format is correct:

   Copy code

   # Should be: postgresql://user:password@host:port/database
   # Example: postgresql://postgres:mypass@localhost:5432/mydb
   

2. If using local PostgreSQL, check if it's running:

   Copy code

   # Check PostgreSQL status
   pg_isready
   # Or on macOS with Homebrew:
   brew services list
   

3. Test the connection directly:

   Copy code

   # Test connection (replace with your actual DATABASE_URL)
   psql postgresql://user:password@localhost:5432/dbname
   

4. For cloud databases (Supabase, Neon, Railway):

   • Verify connection string copied correctly (no extra spaces)
   • Check if database is paused (some free tiers pause after inactivity)
   • Ensure IP allowlist includes your IP (if required)

Port 3000 already in use

# Use a different port
PORT=3001 npm run dev

Prisma errors

# Reset Prisma Client
npx prisma generate

Next Steps

• Customization Guide - Customize your branding
• Authentication Setup - Configure OAuth providers
• Billing & Payments - Set up Gumroad integration
• Database & Prisma - Learn about data models
• Security Features - Learn about built-in security
• Deployment - Deploy to production

Need help? Check the Authentication Guide, Security Features, or email support@shipsecure.dev.