Quick Start

1. Install Dependencies

npm install --legacy-peer-deps

If you encounter issues, try a clean install:

npm cache clean --force
rm -rf package-lock.json node_modules
npm cache verify
npm install --legacy-peer-deps

Optional: Use the correct Node.js version with nvm:

nvm install
nvm use

2. Environment Setup

Duplicate the example environment file:

cp .env.example .env

Configure the minimum required variables in .env:

• APP_NAME: Your application name
• SESSION_SECRET: A random secret string for session encryption
• DATABASE_URL: SQL Server connection string

SQL Server Connection String Format:

DATABASE_URL="sqlserver://localhost:1433;database=BlendX;user=sa;password=YourPassword;encrypt=true;trustServerCertificate=true"

3. Database Setup

Create and seed the database:

npx prisma db push --schema=prisma/schema
npm run seed

If you encounter issues:

1. Try pushing the schema manually:

   npx prisma db push --schema=prisma/schema

2. Then seed separately:

   npm run seed

Important: Never run npx prisma db push --accept-data-loss

4. Start Development Server

npm run dev

Open http://localhost:3000 to see your application.

Default Seed Data

The seed script (SeedService.ts) creates:

Admin User

• Email: admin@email.com
• Password: password
• Access: Admin panel at /admin

App Users

• Email: john.doe@company.com / Password: password
• Email: luna.davis@company.com / Password: password
• Access: App panel at /app/:tenant

Tenants

• Acme Corp 1 - Slug: acme-corp-1
• Acme Corp 2 - Slug: acme-corp-2

Production Deployment

Seed Production Database

1. Create .env.production with your production DATABASE_URL

2. Update default credentials in SeedService.ts:

   const adminUser = {
     email: "your-admin@email.com",
     password: "secure-password",
   };

3. Push schema and seed:

   npx prisma db push --schema=prisma/schema
   npm run seed:prod

4. Important: Revert SeedService.ts changes to avoid committing credentials

Database Connection Pooling

If you exhaust your database connection limit, use DIRECT_URL for direct connections:

DATABASE_URL="sqlserver://..."
DIRECT_URL="sqlserver://..."

See Prisma connection management docs for details.

Deployment Guides

• Deploy to Fly.io
• Deploy to Vercel
• Deploy to AWS Lightsail

Troubleshooting

Database Connection Errors

Ensure your SQL Server:

• Accepts TCP/IP connections
• Allows authentication with username/password
• Has the correct firewall rules configured

Package Installation Fails

Use --legacy-peer-deps flag and ensure you're using Node.js 18+:

nvm use 18
npm install --legacy-peer-deps

Prisma Schema Errors

The schema files are located at prisma/schema/. The main schema file is prisma/schema/schema.prisma with database provider set to sqlserver.

Next Steps

After installation:

1. Explore the Admin Panel: Visit /admin with admin credentials
2. Check App Panel: Visit /app/acme-corp-1 with app user credentials
3. Review Core Concepts: Read the concepts documentation
4. Customize: Update branding, add features, configure settings

Related

• Core Concepts - Understand the architecture
• Admin Panel - Manage users and tenants
• App Panel - Tenant workspace overview