Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
343 lines (245 loc) · 8.68 KB

SETUP_GUIDE.md

File metadata and controls

343 lines (245 loc) · 8.68 KB

📋 Complete Setup Guide

This guide will walk you through setting up the AI Chatbot from scratch.

🎯 Prerequisites

Before you begin, make sure you have:

🚀 Step-by-Step Installation

Step 1: Clone the Repository

git clone <your-repo-url>
cd Chatbot

Step 2: Run the Setup Script

We've created an automated setup script for Windows PowerShell:

.\setup.ps1

This will:

  • ✅ Check Node.js and Python installations
  • ✅ Install all frontend dependencies
  • ✅ Install all backend dependencies
  • ✅ Create environment files from templates

Alternative (Manual Installation):

# Install frontend dependencies
npm install

# Install backend dependencies
cd backend
pip install -r requirements.txt
cd ..

Step 3: Set Up Supabase Database

3.1 Create a Supabase Project

  1. Go to supabase.com
  2. Click "New Project"
  3. Fill in:
    • Name: AI Chatbot (or your preferred name)
    • Database Password: Choose a strong password
    • Region: Select closest to you
  4. Click "Create new project"
  5. Wait 2-3 minutes for setup to complete

3.2 Run the Database Migration

  1. In your Supabase Dashboard, go to SQL Editor (left sidebar)
  2. Click "New Query"
  3. Open supabase/migrations/001_initial_schema.sql in your code editor
  4. Copy all the SQL code (Ctrl+A, Ctrl+C)
  5. Paste into the Supabase SQL Editor
  6. Click "Run" button (or press Ctrl+Enter)
  7. You should see "Success. No rows returned"

✅ Your database is now configured with all tables and security policies!

3.3 Get Your Supabase Credentials

  1. In Supabase Dashboard, go to Project Settings (gear icon)
  2. Click API in the left menu
  3. You'll need two keys:
    • Project URL - Copy the URL under "Project URL"
    • anon/public key - Copy the key under "Project API keys" → "anon public"
    • service_role key - Click "Reveal" next to service_role and copy it

⚠️ IMPORTANT: Keep the service_role key secret! Never commit it to Git.

Step 4: Configure Environment Variables

4.1 Frontend Environment (.env.local)

Open .env.local in your code editor and update:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_public_key_here
NEXT_PUBLIC_API_URL=http://localhost:8000

Replace:

  • your-project-id with your actual Supabase project ID
  • your_anon_public_key_here with the anon key you copied

4.2 Backend Environment (backend/.env)

Open backend/.env in your code editor and update:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key_here

Replace:

  • your-project-id with your actual Supabase project ID
  • your_service_role_key_here with the service_role key you copied

Step 5: Start the Application

You need two terminal windows running simultaneously:

Terminal 1 - Backend (FastAPI)

cd backend
python main.py

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

Terminal 2 - Frontend (Next.js)

npm run dev

You should see:

  ▲ Next.js 14.2.0
  - Local:        http://localhost:3000
  - Ready in X.Xs

Step 6: Access the Application

  1. Open your browser
  2. Go to http://localhost:3000
  3. You should see the login/signup page! 🎉

🔑 Getting AI Provider API Keys

To use the chatbot, you'll need API keys from at least one AI provider:

ChatGPT (OpenAI)

  1. Go to platform.openai.com
  2. Sign in or create an account
  3. Click "Create new secret key"
  4. Copy the key (starts with sk-...)
  5. Add billing information if needed

Cost: Pay-as-you-go, ~$0.002 per 1K tokens

Google Gemini

  1. Go to makersuite.google.com/app/apikey
  2. Sign in with your Google account
  3. Click "Create API key"
  4. Copy the key (starts with AI...)

Cost: Free tier available with generous limits!

DeepSeek

  1. Go to platform.deepseek.com
  2. Sign up for an account
  3. Navigate to API Keys section
  4. Create a new API key
  5. Copy the key (starts with sk-...)

Cost: Very affordable, ~$0.0001 per 1K tokens

Grok (xAI)

  1. Go to x.ai
  2. Sign up for access
  3. Get your API key from the dashboard
  4. Copy the key (starts with xai-...)

Cost: Pricing varies, check their website

📝 Adding API Keys to the App

  1. Log in to your account on http://localhost:3000
  2. Click Settings in the sidebar
  3. Paste your API keys in the respective fields
  4. Click "Save API Keys"
  5. Select a provider and start chatting! 💬

✅ Verification Checklist

Make sure everything is working:

  • Backend server running on http://localhost:8000
  • Frontend server running on http://localhost:3000
  • Can create an account and log in
  • Can access Settings and save API keys
  • Provider buttons show correct status (enabled/disabled)
  • Can send a message and get a response
  • Prompt counter updates after each message
  • Conversations are saved in sidebar

🐛 Common Issues & Solutions

Issue: "Cannot find module 'react'"

Solution: Run npm install in the project root directory.

Issue: "Module not found: Can't resolve '@supabase/supabase-js'"

Solution: Dependencies not installed. Run:

npm install

Issue: Backend won't start / ModuleNotFoundError

Solution: Install Python dependencies:

cd backend
pip install -r requirements.txt

Issue: "Invalid token" or auth errors

Solution: Check your Supabase credentials:

  1. Verify .env.local has the correct anon key
  2. Verify backend/.env has the correct service_role key
  3. Make sure URLs match your Supabase project

Issue: CORS errors in browser console

Solution:

  1. Make sure backend is running on port 8000
  2. Check NEXT_PUBLIC_API_URL in .env.local is http://localhost:8000

Issue: Messages not streaming / "Failed to send message"

Solution:

  1. Check API keys are saved in Settings
  2. Verify selected provider has a valid API key
  3. Check backend logs for errors

Issue: "Prompt limit reached" immediately

Solution: Check the database:

-- In Supabase SQL Editor
SELECT * FROM user_model_limits WHERE user_id = '<your-user-id>';

-- Reset limits if needed
DELETE FROM user_model_limits WHERE user_id = '<your-user-id>';

🎨 Customization Tips

Change the Color Scheme

Edit app/globals.css:

/* Change gradient background */
body {
  @apply bg-gradient-to-br from-your-color-900 via-your-color-800 to-your-color-900;
}

Adjust Prompt Limits

Edit supabase/migrations/001_initial_schema.sql (before running migration):

limit INTEGER DEFAULT 100  -- Change to your desired limit

Or update existing limits in Supabase Dashboard:

UPDATE user_model_limits SET limit = 200;

Modify Animation Speeds

Edit tailwind.config.js:

animation: {
  'slide-up': 'slideUp 500ms ...', // Change duration
}

🚢 Deployment

Deploy Frontend (Vercel)

  1. Push your code to GitHub
  2. Go to vercel.com
  3. Import your repository
  4. Add environment variables in Vercel dashboard
  5. Deploy!

Deploy Backend (Railway/Render)

  1. Push your code to GitHub
  2. Sign up on railway.app or render.com
  3. Create a new service from your GitHub repo
  4. Set build command: pip install -r backend/requirements.txt
  5. Set start command: python backend/main.py
  6. Add environment variables
  7. Deploy!

Don't forget to update NEXT_PUBLIC_API_URL in your frontend to your deployed backend URL!

📚 Additional Resources

💬 Need Help?

If you encounter any issues:

  1. Check the README.md for quick reference
  2. Review this setup guide carefully
  3. Check browser console and backend logs for errors
  4. Open an issue on GitHub with:
    • Description of the problem
    • Error messages
    • Steps to reproduce
    • Your environment (OS, Node version, Python version)

Happy chatting! 🤖✨