Set up ShopySeed from scratch, including dependencies, environment configuration, and your first deployment.

This guide will walk you through setting up ShopySeed from scratch, including all dependencies, environment configuration, and your first successful deployment.

Prerequisites

Before starting, ensure you have the following installed:

Required Software

Software	Version	Download	Purpose
Node.js	20+	nodejs.org	Runtime for all JavaScript/TypeScript code
pnpm	8+	`npm install -g pnpm`	Fast, efficient package manager
Docker	24+	docker.com	Container runtime for services
Docker Compose	2.0+	Included with Docker Desktop	Multi-container orchestration
Git	2.40+	git-scm.com	Version control

Verify Installation

node --version    # Should be 20.x or higher
pnpm --version    # Should be 8.x or higher
docker --version  # Should be 24.x or higher
docker compose version  # Should be 2.x or higher

Step 1: Clone and Install

# Clone the repository
git clone <your-repo-url> my-saas-project
cd my-saas-project

# Install all dependencies
pnpm install

What this does:

Downloads all package dependencies for the monorepo
Sets up workspace linking between packages
Installs development tools and type definitions

Step 2: Environment Configuration

Backend Environment (API)

# Copy the example file
cp apps/api/.env.example apps/api/.env

Edit apps/api/.env with your configuration:

# Database Configuration
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/shopyseed_dev?schema=public
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=shopyseed_dev
POSTGRES_PORT=5433

# JWT Secret (generate a secure random string)
JWT_SECRET=your-super-secure-jwt-secret-at-least-32-characters-long

# Development Settings
NODE_ENV=development
PORT=3011
LOG_LEVEL=debug

# CORS (allow frontend access)
CORS_ORIGINS=http://localhost:3000

# Rate Limiting (relaxed for development)
RATE_LIMIT_TTL=60000
RATE_LIMIT_MAX=100

# Redis (optional in development)
REDIS_URL=redis://localhost:6379
REDIS_PORT=6379

# Stripe (get from Stripe Dashboard)
STRIPE_SECRET_KEY=sk_test_your_stripe_test_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# OAuth Providers (optional - configure later)
# 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

Frontend Environment (Web)

# Copy the example file
cp apps/web/.env.example apps/web/.env.local

Edit apps/web/.env.local:

# API URL (development backend)
NEXT_PUBLIC_API_URL=http://localhost:3011

# Stripe Publishable Key (get from Stripe Dashboard)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key

# OAuth URLs (optional)
# NEXT_PUBLIC_GOOGLE_OAUTH_URL=http://localhost:3011/auth/oauth/google
# NEXT_PUBLIC_GITHUB_OAUTH_URL=http://localhost:3011/auth/oauth/github

Environment Variables Explained

Variable	Purpose	Where to Get
`DATABASE_URL`	PostgreSQL connection string	Auto-configured for Docker
`JWT_SECRET`	Signs authentication tokens	Generate: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
`STRIPE_SECRET_KEY`	Stripe API access	Stripe Dashboard
`STRIPE_WEBHOOK_SECRET`	Webhook signature verification	Stripe Webhooks
`CORS_ORIGINS`	Allowed frontend origins	Your frontend URL(s)

Step 3: Start Infrastructure Services

ShopySeed uses Docker Compose to manage development services:

# Start PostgreSQL, Redis, and MailHog
docker compose up -d

# Check services are running
docker compose ps

Expected output:

NAME                   SERVICE             STATUS              PORTS
shopyseed-db             db                  running            0.0.0.0:5433->5432/tcp
shopyseed-redis          redis               running            0.0.0.0:6379->6379/tcp
shopyseed-mailhog        mailhog             running            0.0.0.0:8025->8025/tcp, 0.0.0.0:1025->1025/tcp

Service URLs

Service	URL	Purpose
PostgreSQL	localhost:5433	Primary database
Redis	localhost:6379	Caching and sessions
MailHog	http://localhost:8025	Email testing (catches outbound emails)

Verify Database Connection

# Wait for database to be ready
docker compose logs -f db

# You should see: "database system is ready to accept connections"

Step 4: Database Setup

Set up the database schema and seed data:

cd apps/api

# Generate Prisma client
pnpm prisma generate

# Run migrations to create tables
pnpm prisma migrate dev --name init

# Seed the database with test data
pnpm db:seed

What this creates:

Database tables for users, organizations, subscriptions
Test user: admin@shopyseed.com / password123
Test organization: "Acme Corp"
Sample subscription data

Verify Database Setup

# Open Prisma Studio to browse data
pnpm prisma studio

Navigate to http://localhost:5555 and verify you see tables with data.

Step 5: Start Development Servers

From the project root, start all services:

# Start API + Web + Shared packages in watch mode
pnpm dev

What starts:

API Server: http://localhost:3011 (NestJS backend)
Web Server: http://localhost:3000 (Next.js frontend)
Shared Types: Auto-compiles when changed

Verify Everything Works

API Health Check: http://localhost:3011/health

{ "status": "ok", "timestamp": "2024-01-15T10:30:00.000Z" }

API Documentation: http://localhost:3011/api
- Should show Swagger UI with all endpoints
Web Application: http://localhost:3000
- Should show ShopySeed landing page
- Try registering a new account
- Verify email in MailHog: http://localhost:8025

Step 6: First Steps

Create Your First Account

Navigate to http://localhost:3000
Click "Sign Up"
Create account: you@example.com / password123
Check MailHog for verification email: http://localhost:8025
Click verification link
Login to dashboard

Create Your First Organization

In the dashboard, click "Create Organization"
Name: "My SaaS Company"
Slug: "my-saas-company" (auto-generated)
You're now in a multi-tenant environment!

Test Stripe Billing (Optional)

Set up test Stripe account at https://dashboard.stripe.com
Add your Stripe keys to environment files
Restart the API: pnpm dev (in apps/api)
In your organization, try upgrading to a paid plan
Use Stripe test cards: 4242424242424242

Development Workflow

File Watching

All development servers automatically reload when you change files:

API Changes: NestJS automatically restarts
Web Changes: Next.js hot reloads the browser
Shared Types: Auto-rebuilds and updates both API and Web

Database Changes

When you modify the Prisma schema:

cd apps/api

# Create migration
pnpm prisma migrate dev --name your_change_description

# If you need to reset everything (CAUTION: deletes all data)
pnpm prisma migrate reset
pnpm db:seed

Running Tests

# All tests
pnpm test

# Backend only
cd apps/api && pnpm test

# Frontend only
cd apps/web && pnpm test

# Watch mode
pnpm test:watch

Troubleshooting

Common Issues

1. Port Already in Use

Error: EADDRINUSE: address already in use :::3000

Solution: Kill the process using the port:

# Find and kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different ports in .env files

2. Database Connection Failed

Error: Can't connect to database

Solution: Ensure Docker services are running:

docker compose down
docker compose up -d
docker compose logs db

3. Prisma Client Not Generated

Error: PrismaClient is unable to find your Prisma schema

Solution: Regenerate the client:

cd apps/api
pnpm prisma generate

4. Email Verification Not Working

Issue: Not receiving verification emails

Solution: Check MailHog at http://localhost:8025 - all development emails are captured there.

5. API 502/504 Errors

Error: Frontend can't connect to API

Solution: Verify API is running and check CORS configuration:

# Check API health
curl http://localhost:3011/health

# Verify CORS_ORIGINS in apps/api/.env includes http://localhost:3000

Getting Help

Check the logs:

# API logs
cd apps/api && pnpm dev

# Web logs  
cd apps/web && pnpm dev

# Docker services
docker compose logs

Reset everything (nuclear option):

# Stop all services
docker compose down -v
pnpm dev:stop

# Clean and reinstall
pnpm clean
pnpm install

# Restart setup from Step 3

Community Support:
- Discord Community
- GitHub Issues

Next Steps

Once your development environment is running:

Read the Architecture Guide: docs/architecture.md
Explore the API: docs/api-reference.md
Customize Your App: docs/customization.md
Deploy to Production: docs/deployment.md

You're now ready to build your SaaS! 🚀

Getting Started