Documentation

System setupDetailed guide

Installation and environment setup for the current repository.

Use this guide when you need the full environment blueprint, service integration checklist, and database bootstrap flow for a clean local or staging installation.

Before you begin
Have a working PostgreSQL instance available, use a current Node.js runtime supported by your Next.js setup, and decide whether your email delivery will use Resend or SMTP.

Prerequisites

Node.js

Use a recent Node.js runtime compatible with Next.js 16.

PostgreSQL

A local or managed PostgreSQL database reachable from your app.

Email provider

Resend is preferred. SMTP is supported as the fallback path.

External services

OAuth, Stripe, and OpenRouter can be added after the first local boot.

Install the project

Terminalbash
git clone <your-repository-url> saaskit
cd saaskit
npm install
cp .env.example .env
PowerShell
If you are working on Windows PowerShell, use Copy-Item .env.example .env instead of cp when needed.

Environment blueprint

The block below reflects the variables currently referenced by the app, the docs, and the deployment flow.

.envbash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# Core application
DATABASE_URL="postgresql://user:password@localhost:5432/saaskit?schema=public"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="replace-with-a-strong-secret"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
APP_NAME="AI SaaS"
# OAuth
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
GITHUB_ID="..."
GITHUB_SECRET="..."
# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_PRO_MONTHLY_PRICE_ID="price_..."
STRIPE_PRO_YEARLY_PRICE_ID="price_..."
STRIPE_BUSINESS_MONTHLY_PRICE_ID="price_..."
STRIPE_BUSINESS_YEARLY_PRICE_ID="price_..."
# OpenRouter
OPENROUTER_API_KEY="sk-or-v1-..."
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
# Email: preferred production path
RESEND_API_KEY="re_..."
# Email: SMTP fallback
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="you@example.com"
SMTP_PASS="app-password"
SMTP_FROM="AI SaaS <you@example.com>"
ADMIN_EMAIL="ops@example.com"
# Optional monitoring
SENTRY_DSN=""
SENTRY_ORG=""
SENTRY_PROJECT=""
# Optional CI helper
PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING="1"
Secrets
Never commit .env to version control. Keep secrets in local env files, CI secret stores, or your hosting platform's environment manager.

Bootstrap the app

1

Generate the Prisma client

Terminalbash
npm run prisma:generate
2

Push the schema to PostgreSQL

Use the current bootstrap flow for this repository.

Terminalbash
npm run db:push
3

Seed starter data

The seed creates roles, permissions, plans, categories, and tags.

Terminalbash
npm run db:seed
4

Run the development server

Terminalbash
npm run dev
Prisma note
The current repo does not ship checked-in Prisma migrations. For first-time installs, use db:push. If you later introduce migrations, production deploys should switch to prisma migrate deploy.

Configure the product services

Authentication

Set up Google and GitHub OAuth, session behavior, credentials sign-in, and RBAC.

Billing

Create Stripe products, wire price IDs, and configure the webhook endpoint.

AI Integration

Add your OpenRouter key, choose models, and validate credits and request flow.

Deployment

Take the local install to Vercel, Railway, or your own Node host.

Build verification

Production checkbash
npm run build
npm run start

Installation checklist

The app loads at localhost:3000 and the docs shell renders correctly.

The database connection works and seed data is visible in Prisma Studio.

Auth pages load without missing-secret or callback errors.

Email delivery is configured for verification and notifications.

Stripe and OpenRouter credentials are ready for the next integration pass.

Next step

Once installation is complete, move into deployment to align production domains, Stripe webhooks, and the database bootstrap sequence with your hosting platform.