Quick Start Guide

Welcome to Chameleon! This guide will help you set up and deploy your AI SaaS application in under 30 minutes.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ installed on your system
• pnpm package manager (npm install -g pnpm)
• A database ready:
  • Option 1: Vercel Postgres (recommended for Vercel deployment)
  • Option 2: MySQL 8.0+ or PostgreSQL 14+
• Git installed for version control

Step 1: Clone the Repository

git clone https://github.com/chameleon-nexus/chameleon-saas.git
cd chameleon-saas

Step 2: Install Dependencies

pnpm install

This will install all required packages including Next.js, React, Drizzle ORM, and AI SDKs.

Step 3: Configure Environment Variables

Understanding Environment Files

This project uses different environment files for different purposes:

• .env.example - Template file with all required variables (safe to commit to Git)
• .env.development - Development environment configuration (team shared, can commit to Git)
• .env.local - Your personal local configuration (contains real API keys, never commit to Git)

For Local Development

Copy the example environment file:

cp .env.example .env.local

Edit .env.local and configure the following required variables:

Database (Required)

# For PostgreSQL (Vercel Postgres, Railway, etc.)
DATABASE_URL="postgresql://user:password@host:5432/database"

# For MySQL (PlanetScale, Railway, etc.)
DATABASE_URL="mysql://user:password@host:3306/database"

Authentication (Required)

# Generate a random secret: openssl rand -base64 32
NEXTAUTH_SECRET="your-random-secret-here"
AUTH_SECRET="your-random-secret-here"

# For local development
NEXTAUTH_URL="http://localhost:3000"

# Google OAuth (optional)
AUTH_GOOGLE_ID="your-google-client-id"
AUTH_GOOGLE_SECRET="your-google-client-secret"

# GitHub OAuth (optional)
AUTH_GITHUB_ID="your-github-client-id"
AUTH_GITHUB_SECRET="your-github-client-secret"

Admin Account (Required)

# Comma-separated list of admin emails
ADMIN_EMAILS="your-email@example.com"

Base URL (Required for production)

# For local development
NEXT_PUBLIC_WEB_URL="http://localhost:3000"

# For production (set in Vercel)
NEXT_PUBLIC_WEB_URL="https://your-domain.com"

Optional: Payment (Stripe)

STRIPE_PRIVATE_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."

AI Providers (Required for AI Features)

AI providers are configured through the Admin System only. See Step 7.2 for detailed configuration instructions.

Step 4: Set Up Database

Run the database setup to create all required tables and initialize the system:

pnpm db:setup

This command will:

• Create all required database tables
• Automatically initialize the credit system with default rules
• Insert initial AI provider configurations (if environment variables are set)
• Set up price tier configurations

Tables Created:

• users - User accounts
• orders - Payment orders
• credits - Credit system
• credit_rules - Credit rules configuration
• price_tier_credits - Price tier configurations
• generations - AI generation history
• ai_provider_keys - AI provider API keys
• posts - Blog posts
• feedbacks - User feedback
• affiliates - Referral system
• apikeys - API key management

Step 5: Start Development Server

pnpm dev

Open http://localhost:3000 in your browser.

Step 6: Create Your Admin Account

1. Click Sign In in the top right
2. Sign in with Google or GitHub (or create an account)
3. Make sure you use the email you set in ADMIN_EMAILS
4. You now have admin access!

Step 7: Configure Admin System (Required)

7.1: Access Admin Panel

1. Make sure you're signed in with an email listed in ADMIN_EMAILS
2. Visit /admin in your browser
3. You should see the admin dashboard

7.2: Configure AI Providers (Required)

You MUST configure at least one AI provider to use AI generation features:

1. Go to /admin/ai-config
2. Click on a provider (e.g., OpenAI, Kling, Seedance)
3. Enter the API key
4. Toggle Enabled to ON
5. Click Save

Recommended providers to start with:

• OpenAI - For text and image generation (most versatile)
• Seedance - For video generation (high quality)
• Kling - For image and video generation (good alternative)

7.3: Verify Credit System

1. Go to /admin/credit-rules (if available)
2. Verify that credit rules are properly initialized
3. Check that price tier configurations are set up

7.4: Test Admin Access

Make sure you can:

• ✅ Access /admin dashboard
• ✅ View user list at /admin/users
• ✅ Configure AI providers at /admin/ai-config
• ✅ See system statistics

Step 8: Test Complete System

8.1: Test AI Generator

1. Visit /ai-generator
2. Select an AI type (Image/Video Generation)
3. Choose a provider you configured in Step 7.2
4. Enter a prompt: "A dancing robot"
5. Click Generate
6. Wait for generation to complete

8.2: Verify System Components

Test these key features:

✅ Authentication:

• Sign in/out works
• Admin access works

✅ Database:

• User data is saved
• Generation history is recorded

✅ Credit System:

• Credits are displayed
• Generation costs credits

✅ AI Generation:

• At least one provider works
• Results are displayed

✅ Admin System:

• Can access /admin
• Can configure AI providers
• Can view user data

Step 9: Deploy to Vercel (Production)

9.1: Prepare for Deployment

Before deploying, make sure you have:

• ✅ All environment variables configured in .env.local
• ✅ Database setup completed (pnpm db:setup)
• ✅ Admin system configured
• ✅ At least one AI provider configured

9.2: Deploy to Vercel

1. Push your code to GitHub:

   git add .
   git commit -m "Ready for deployment"
   git push
   

2. Import project in Vercel:

   • Go to vercel.com/new
   • Import your GitHub repository
   • Select the repository and click "Import"

3. Configure Environment Variables in Vercel:

   Option A: Upload Environment File (Recommended)

   • In Vercel project settings, go to "Environment Variables"
   • Click "Upload .env File"
   • Upload your .env.local file directly
   • Vercel will automatically parse and set all variables

   Option B: Manual Configuration

   • Add each environment variable manually in Vercel dashboard
   • Copy values from your .env.local file

4. Deploy:

   • Click "Deploy" in Vercel
   • Wait for deployment to complete
   • Your app will be available at https://your-project.vercel.app

9.3: Post-Deployment Setup

After deployment:

1. Update URLs:

   • Update NEXTAUTH_URL and NEXT_PUBLIC_WEB_URL to your Vercel domain
   • Redeploy to apply changes

2. Configure Admin System:

   • Visit https://your-domain.com/admin
   • Configure AI providers in /admin/ai-config
   • Verify credit system is working

3. Test Complete System:

   • Test authentication
   • Test AI generation
   • Test payment (if enabled)

Step 10: Configure Stripe (Optional)

If you want to enable payments:

1. Create a Stripe account at stripe.com
2. Get your API keys from the Stripe dashboard
3. Configure Stripe Price IDs in pricing files (src/i18n/pages/pricing/)
4. Set environment variables in Vercel (see above)
5. Note: This system uses webhook-based payment processing for reliable payment handling

See the Payment Documentation for detailed setup.

What's Next?

Deploy to Production

• Deploy to Vercel - Detailed Vercel deployment guide
• Deploy to Cloudflare - Alternative option

Customize Your Site

• Edit Landing Page - Customize content
• Add New Pages - Create custom pages
• Internationalization - Add more languages

Explore Features

• AI Integration - Deep dive into AI features
• Payment System - Set up subscriptions
• Credit System - Manage user credits
• Referral Program - Enable affiliate system

API Reference

• User APIs - User-related endpoints
• AI APIs - AI generation endpoints
• Payment APIs - Payment processing

Need Help?

• FAQ - Frequently asked questions
• Troubleshooting - Common issues
• GitHub Issues - Report bugs

Common Issues

Build Errors

If you encounter build errors:

# Clean install
rm -rf node_modules .next
pnpm install
pnpm build

Database Connection Issues

Make sure your DATABASE_URL is correctly formatted and the database server is accessible.

Environment Variables Not Working

• Restart the dev server after changing .env.local
• On Vercel, redeploy after updating environment variables
• Check for typos and spaces around = signs
• Make sure you're using .env.local for local development, not .env.development

AI Generator Not Working

Symptoms: AI Generator shows no providers or generation fails

Solutions:

1. Check Admin System: Visit /admin/ai-config and ensure at least one provider is configured and enabled
2. Verify API Keys: Make sure API keys are valid and have proper permissions
3. Restart Server: Restart the development server after making changes
4. Admin System Only: AI providers must be configured through the Admin System at /admin/ai-config

Admin Panel Access Issues

Symptoms: Can't access /admin or see "No access" message

Solutions:

1. Check ADMIN_EMAILS: Make sure your email is in the ADMIN_EMAILS environment variable
2. Restart Server: Restart after adding ADMIN_EMAILS
3. Sign Out/In: Sign out and sign back in after admin configuration
4. Email Match: Ensure the email you sign in with exactly matches the one in ADMIN_EMAILS

Credit System Issues

Symptoms: Credits not showing or generation not consuming credits

Solutions:

1. Run Database Setup: Ensure you ran pnpm db:setup to initialize credit rules
2. Check Admin Panel: Verify credit rules are properly configured in admin panel
3. User Credits: Make sure user has sufficient credits for generation

---

You're all set! 🎉 Start building your AI SaaS with Chameleon.