Self-Hosting Installation Guide
This guide walks you through setting up Studley AI on your own infrastructure. Perfect for organizations, schools, or developers who want full control over their study platform.Prerequisites
Before you begin, ensure you have:- Node.js 18+ installed on your system
- PostgreSQL database (local or hosted)
- Git for cloning the repository
- Text editor (VS Code, Vim, etc.)
- Terminal/Command line access
- Basic knowledge of JavaScript/TypeScript and command line
This installation uses Supabase for authentication and database management. You can use Supabase Cloud (free tier available) or self-host Supabase.
Installation Steps
Step 1: Clone the Repository
First, clone the Studley AI repository to your local machine:Replace
your-org/studley-ai with the actual repository URL provided by your organization.Step 2: Install Dependencies
Install all required npm packages:package.json, including:
Step 3: Set Up Database
Option A: Using Supabase Cloud (Recommended)
Create Supabase Project
- Go to supabase.com
- Sign up or log in
- Click “New Project”
- Fill in project details:
- Name: studley-ai-production
- Database Password: Choose a strong password
- Region: Select closest to your users
Get Your Credentials
Once created, navigate to Project Settings → API:
- Copy your Project URL (NEXT_PUBLIC_SUPABASE_URL)
- Copy your anon/public key (NEXT_PUBLIC_SUPABASE_ANON_KEY)
Option B: Local PostgreSQL
Install PostgreSQL
Download and install PostgreSQL from postgresql.org if not already installed.
Step 4: Run Database Schema
Execute the database initialization script to create all necessary tables:- Supabase Dashboard
- Command Line
- Go to SQL Editor in your Supabase dashboard
- Click “New Query”
- Copy and paste the SQL script above
- Click “Run” or press
Cmd/Ctrl + Enter
Additional migration scripts in the
scripts/ folder can be run in numerical order for enhanced features like shared sessions, feedback tables, and user profiles.Step 5: Configure Environment Variables
Create your environment configuration file:Getting Your API Keys
Supabase Keys
Supabase Keys
- Go to your Supabase project dashboard
- Navigate to Settings → API
- Copy Project URL (NEXT_PUBLIC_SUPABASE_URL)
- Copy anon public key (NEXT_PUBLIC_SUPABASE_ANON_KEY)
NextAuth Secret
NextAuth Secret
Generate a secure random string:Copy the output and use it as your NEXTAUTH_SECRET.
Groq API Key (AI Generation)
Groq API Key (AI Generation)
- Go to console.groq.com
- Sign up or log in
- Navigate to API Keys
- Click Create API Key
- Copy the generated key (save it securely - you can’t view it again)
Resend API Key (Optional Email)
Resend API Key (Optional Email)
- Go to resend.com
- Sign up for a free account
- Navigate to API Keys
- Create a new API key
- Verify your domain or use the test domain for development
Step 6: Build and Run
Now you’re ready to build and run Studley AI!Development Mode
Run the development server with hot reloading:http://localhost:3000
Development mode includes hot module replacement (HMR) - changes to your code will automatically refresh the browser.
Production Build
For production deployment:Step 7: Verify Installation
Test that everything is working correctly:Access the Application
Open your browser and navigate to
http://localhost:3000You should see the Studley AI homepage with animated hero section.Create a Test Account
- Click “Sign Up” in the navigation
- Fill in your details:
- Email: [email protected]
- First Name: Test
- Last Name: User
- Password: testpassword123
- Submit the form
Check Database
Verify the user was created in your database:You should see the user with 5000 starting credits.
Test AI Generation
- Navigate to the Quiz Generator
- Enter a topic: “Solar System”
- Click “Generate Quiz”
- Verify that the AI generates a quiz successfully
This requires a valid GROQ_API_KEY. If generation fails, check your API key configuration.
Project Structure
Understanding the codebase structure:Configuration Files
Supabase Client Setup
Production Deployment
Deploying to Vercel (Recommended)
Connect to Vercel
- Go to vercel.com
- Click “New Project”
- Import your GitHub repository
- Configure project settings
Set Environment Variables
In Vercel project settings, add all your environment variables from
.env.local:- NEXT_PUBLIC_SUPABASE_URL
- NEXT_PUBLIC_SUPABASE_ANON_KEY
- NEXTAUTH_SECRET
- GROQ_API_KEY
- etc.
Deploy
Click “Deploy” and wait for the build to complete. Vercel will automatically:
- Install dependencies
- Build the project
- Deploy to production
- Provide a production URL
Deploying to Other Platforms
- Docker
- Ubuntu Server
- AWS EC2
Create a Build and run:
Dockerfile:Troubleshooting
Database connection failed
Database connection failed
Error:
Error: connect ECONNREFUSED 127.0.0.1:5432Solutions:- Check PostgreSQL is running:
sudo service postgresql status - Verify DATABASE_URL is correct in
.env.local - Check firewall isn’t blocking port 5432
- For Supabase, verify project is not paused
Supabase authentication not working
Supabase authentication not working
Error:
Invalid API key or supabase.auth is not definedSolutions:- Verify NEXT_PUBLIC_SUPABASE_URL is correct
- Check NEXT_PUBLIC_SUPABASE_ANON_KEY is the anon/public key, not service role
- Ensure environment variables start with NEXT_PUBLIC_ for client access
- Restart dev server after changing env variables
AI generation not working
AI generation not working
Error:
API key invalid or Generation failedSolutions:- Verify GROQ_API_KEY is set correctly
- Check your Groq account has available credits
- Test API key with a curl request:
Build fails with TypeScript errors
Build fails with TypeScript errors
Error:
Type error: ...Solutions:- Run
npm installto ensure all types are installed - Check
tsconfig.jsonis properly configured - Clear Next.js cache:
rm -rf .next - Update TypeScript:
npm install -D typescript@latest
Port 3000 already in use
Port 3000 already in use
Error:
Error: listen EADDRINUSE: address already in use :::3000Solutions:- Kill the process using port 3000:
- Or use a different port:
Credits not deducting
Credits not deducting
Solutions:
- Check database user table has credits column
- Verify credit_usage table exists
- Check server logs for SQL errors
- Ensure atomic credit deduction function is working:
Performance Optimization
Database Indexing
Ensure all indexes are created (they’re in the init script):
idx_users_emailidx_sessions_userIdidx_credit_usage_userIdidx_generations_userId
Image Optimization
Next.js automatically optimizes images. Use the
Image component:Caching
Enable Next.js caching for static content:
Environment Variables
For production, set:
Security Best Practices
Secure Environment Variables
- Never commit
.env.localto version control - Use strong random values for secrets
- Rotate API keys regularly
- Use different keys for dev/staging/production
Database Security
- Use Row Level Security (RLS) in Supabase
- Create separate database users with minimal permissions
- Enable SSL for database connections
- Regular backups (Supabase does this automatically)
Authentication
- Enforce strong password requirements (minimum 6 characters)
- Implement rate limiting on auth endpoints
- Use HTTPS in production (required)
- Enable email verification if needed
Maintenance
Regular Tasks
- Monitor logs: Check for errors and unusual activity
- Database backups: Automate daily backups (Supabase handles this)
- Update dependencies: Run
npm auditand update packages monthly - Monitor costs: Keep track of AI API usage and database size
- Performance monitoring: Use Vercel Analytics or similar tools
Updating Studley AI
Next Steps
Customize Branding
Update colors, logo, and text in
app/globals.css and components to match your brand.Add Custom Generators
Create new generator types by following the pattern in
app/tools/ and lib/generators-config.ts.Configure Email
Set up Resend for welcome emails and notifications. Update email templates in
lib/email.ts.Set Up Analytics
Add Vercel Analytics, Google Analytics, or PostHog for user insights.
Support
Need help with installation?- Check the GitHub repository for issues
- Review Next.js documentation
- Check Supabase documentation
- Contact your system administrator or development team