Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 14+ running locally
• npm or pnpm

Installation

git clone <repo> saas-core
cd saas-core
cp .env.example .env
npm install

Edit .env to set your database connection string and admin token:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/saas_core
ADMIN_TOKEN=your_admin_token_min_16_chars
BETTER_AUTH_SECRET=your_secret_at_least_32_chars
BETTER_AUTH_BASE_URL=http://localhost:3000
AUTH_COOKIE_DOMAIN=.localhost
SAAS_TRUSTED_ORIGINS=http://localhost:5173,http://localhost:5175,http://localhost:5176

Database Migration

npm run db:migrate

Start Development

Start all services:

./scripts/dev.sh start

Or start services individually:

npm run dev             # Backend on :3000
npm run dev:admin       # Admin console on :5176
npm run dev:client      # Auth demo on :5173
npm run dev:oauth       # OAuth demo on :5175

Verify

1. Open http://localhost:3000/api/auth/jwks — you should see JWKS keys
2. Open http://localhost:5176 and log in with your ADMIN_TOKEN
3. Register a test application via the admin console
4. Open http://localhost:5173 to verify the auth flow end-to-end

Service Ports

Port	Service	Purpose
3000	saas-core backend	All API endpoints
5173	saas-client-demo	Path A direct auth demo
5175	saas-oauth-demo	Path B OAuth redirect demo
5176	saas-admin	Admin console