Skip to main content

Quick Start Guide

This guide will help you set up your development environment and run Tutor Nexus locally.

Prerequisites​

ToolVersionPurpose
Node.js>= 20.0.0Runtime for web apps
pnpm>= 9.0.0Package manager
GitLatestVersion control
Cloudflare WranglerLatestWorkers deployment
Go1.25+MCP server development
RustLatestCLI development

Installation​

1. Clone the Repository​

git clone https://github.com/eschmechel/tutornexus.git
cd tutornexus

2. Install Dependencies​

# Install pnpm if not already installed
npm install -g pnpm

# Install all workspace dependencies
pnpm install

3. Configure Environment​

Copy the example environment file and fill in your values:

cp .env.example .env

Required variables:

# Database (D1)
DATABASE_URL=.wrangler/state/d1/.sqlite

# Auth
AUTH_SECRET=your-lucia-auth-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# API Keys (for BYOK feature)
OPENAI_API_KEY=your-openai-key
ELEVENLABS_API_KEY=your-elevenlabs-key

# Cloudflare
CLOUDFLARE_API_TOKEN=your-cloudflare-token
CLOUDFLARE_ACCOUNT_ID=your-account-id

4. Set Up Database​

# Create local D1 databases
pnpm db:setup

# Run migrations
pnpm db:migrate

5. Start Development Servers​

All Services​

pnpm dev

This starts:

  • API server at http://localhost:8787
  • Web app at http://localhost:5173
  • Docs at http://localhost:3000

Individual Services​

# API only
pnpm dev:api

# Web only
pnpm dev:web

# Docs only
pnpm dev:docs

Verifying the Setup​

Health Check​

curl http://localhost:8787/health

Expected response:

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-02-04T00:00:00Z"
}

API Documentation​

Visit http://localhost:8787/docs for the Swagger UI.

Common Issues​

Port Already in Use​

# Find and kill the process
lsof -ti:8787 | xargs kill -9

# Or use a different port
pnpm dev:api -- --local-port 8788

Database Errors​

# Reset the database
rm -rf .wrangler/state/d1
pnpm db:setup
pnpm db:migrate

Node Version Mismatch​

# Using nvm
nvm use 20

# Using volta
volta install node@20

Next Steps​

Once your environment is set up:

  1. Read the Development Guide - Learn coding conventions
  2. Explore the API - Understand the endpoints
  3. Review Architecture - Understand design decisions
  4. Check the Testing Guide - Learn how to test

Support​

  • GitHub Issues: Report bugs and request features
  • Discord: Join our community server
  • Documentation: See the full docs