Setup & Installation

Get SAMS running locally in minutes with this comprehensive setup guide.

Setup & Installation

This guide will walk you through setting up SAMS locally for development and customization.

Prerequisites

Before starting, ensure you have:

Node.js 18+ (Download)
pnpm package manager (Install)
PostgreSQL database (local or cloud)
Git for version control

Quick Start

1. Download & Extract

After purchasing SAMS, download and extract the framework to your desired location:

# Extract the framework
unzip supasecure-framework.zip
cd supasecure-framework

# Or if you received it via Git
git clone https://github.com/your-repo/supasecure-framework.git
cd supasecure-framework

2. Install Dependencies

Install all required dependencies using pnpm:

# Install dependencies for all packages
pnpm install

# This will install dependencies for:
# - Main Next.js app
# - All packages (api, auth, database, etc.)
# - Development tools

3. Environment Setup

Copy the example environment file and configure your settings:

# Copy environment template
cp .env.example .env.local

Edit .env.local with your configuration:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/supasecure"

# Next.js Configuration
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# Application Settings
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="SAMS"

# Email Configuration (optional for development)
EMAIL_FROM="noreply@yourdomain.com"
RESEND_API_KEY="your-resend-api-key"

# Payment Configuration (optional for development)
STRIPE_SECRET_KEY="sk_test_your_stripe_secret_key"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_stripe_publishable_key"

4. Database Setup

Set up your PostgreSQL database:

# Generate Prisma client and push schema to database
cd packages/database
pnpm generate
pnpm push

# This will:
# - Generate the Prisma client
# - Create all necessary tables
# - Set up initial database schema

5. Start Development Server

Launch the development server:

# From the root directory
pnpm dev

# Or from the web app directory
cd apps/web
pnpm dev

Your SAMS instance will be available at http://localhost:3000!

Detailed Configuration

Database Configuration

SAMS supports PostgreSQL databases. You can use:

Local PostgreSQL

# Install PostgreSQL locally
# macOS with Homebrew
brew install postgresql
brew services start postgresql

# Create database
createdb supasecure

# Update DATABASE_URL in .env.local
DATABASE_URL="postgresql://username:password@localhost:5432/supasecure"

Cloud Database (Recommended)

Use a cloud provider for easier setup:

Supabase (Recommended):

Create account at supabase.com
Create new project
Copy connection string from Settings > Database
Use the "Connection Pooling" URL with port 6543

DATABASE_URL="postgresql://postgres.[PROJECT_REF]:[PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true"

Neon:

Create account at neon.tech
Create new project
Copy connection string

Railway:

Create account at railway.app
Deploy PostgreSQL service
Copy connection string

Authentication Configuration

SAMS uses Better Auth for authentication. Configure providers in .env.local:

# OAuth Providers (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Magic Link Email (optional)
RESEND_API_KEY="your-resend-api-key"

Payment Configuration

For payment processing, configure Stripe:

# Stripe Configuration
STRIPE_SECRET_KEY="sk_test_your_stripe_secret_key"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_stripe_publishable_key"
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret"

Project Structure

Understanding the codebase structure:

supasecure-framework/
├── apps/
│   └── web/                 # Main Next.js application
│       ├── app/            # Next.js App Router
│       ├── modules/        # Feature modules
│       ├── content/        # MDX content (docs, blog)
│       └── public/         # Static assets
├── packages/
│   ├── api/                # Hono API framework
│   ├── auth/               # Better Auth configuration
│   ├── database/           # Prisma schema and client
│   ├── i18n/               # Internationalization
│   ├── payments/           # Payment provider integrations
│   └── ui/                 # Shared React components
├── config/
│   └── index.ts            # Central configuration
└── docs/                   # Additional documentation

Development Commands

Essential commands for development:

# Development
pnpm dev                    # Start development server
pnpm build                  # Build for production
pnpm start                  # Start production server

# Code Quality
pnpm lint                   # Run ESLint
pnpm type-check            # Run TypeScript checking
pnpm format                # Format code with Prettier

# Database
cd packages/database
pnpm generate              # Generate Prisma client
pnpm push                  # Push schema to database
pnpm migrate               # Create and apply migrations
pnpm studio                # Open Prisma Studio