Skip to main content
This guide provides detailed instructions for installing and configuring Maxw AI for both development and production environments.

​
System Requirements

Before installing Maxw AI, ensure your system meets these requirements:

​
Hardware Requirements

  • RAM: Minimum 4GB, recommended 8GB or more
  • Storage: At least 2GB free space for dependencies and database
  • CPU: Modern multi-core processor (development servers can be resource-intensive)

​
Software Requirements

Operating System

  • macOS 11 or later
  • Linux (Ubuntu 20.04+, Debian 11+)
  • Windows 10/11 with WSL2

Runtime & Database

  • Bun 1.2.21 or later
  • PostgreSQL 14 or later
  • Node.js 18+ (for React Native)

​
Installing Bun Package Manager

Maxw AI uses Bun as its package manager and runtime. Bun is significantly faster than npm or yarn and provides excellent TypeScript support.

​
macOS and Linux

Install Bun using the official installer: 
curl -fsSL https://bun.sh/install | bash
Restart your terminal, then verify the installation: 
bun --version
# Should output: 1.2.21 or later

​
Windows

Bun runs on Windows via WSL2 (Windows Subsystem for Linux):
  1. Install WSL2 following Microsoft’s guide
  2. Open your WSL2 terminal (Ubuntu recommended)
  3. Install Bun using the Linux instructions above
Bun is required for this project. npm, yarn, and pnpm are not supported.

​
Setting Up PostgreSQL

Maxw AI requires a PostgreSQL database for storing user data, todos, study sets, and AI memory.

​
Option 1: Local PostgreSQL

brew install postgresql@16
brew services start postgresql@16

# Create database
createdb maxw_ai
Maxw AI is optimized for Neon, a serverless PostgreSQL provider:
  1. Sign up at neon.tech
  2. Create a new project
  3. Copy the connection string
  4. Use it as your DATABASE_URL environment variable
Neon offers a generous free tier and is recommended for production deployments on Vercel.

​
Verify PostgreSQL Connection

Test your database connection: 
psql "postgresql://user:password@localhost:5432/maxw_ai" -c "SELECT version();"

​
Installing Project Dependencies

​
Clone the Repository

Clone the Maxw AI repository: 
git clone https://github.com/maxwiseman/maxw-ai-v3.git
cd maxw-ai-v3

​
Install Dependencies

Install all dependencies for the monorepo: 
bun install
This single command installs dependencies for:
  • Web application (apps/web)
  • Mobile application (apps/native)
  • Shared packages (if any)
The project uses Bun workspaces to manage the monorepo. Key dependencies include:Web App:
  • Next.js 16 with React 19
  • AI SDK with Anthropic integration
  • Drizzle ORM and database tools
  • TailwindCSS 4 and shadcn/ui
  • Better-Auth for authentication
  • Upstash Search for Canvas indexing
Mobile App:
  • React Native with Expo
  • Shared UI components
  • Better-Auth Expo integration
Development Tools:
  • Biome for linting and formatting
  • Turborepo for build orchestration
  • TypeScript for type checking

​
Environment Configuration

​
Create Environment File

Create a .env file in the repository root (not in apps/web/): 
touch .env
The environment file must be at the root of the repository. Drizzle ORM’s configuration (drizzle.config.ts) reads from the root .env file.

​
Required Environment Variables

Add these variables to your .env file:
.env
# ============================================
# DATABASE
# ============================================
# PostgreSQL connection string (required)
DATABASE_URL="postgresql://user:password@localhost:5432/maxw_ai"

# ============================================
# AUTHENTICATION
# ============================================
# Better-Auth secret (generate with: openssl rand -base64 32)
AUTH_SECRET="your-generated-secret-here"

# ============================================
# UPSTASH SEARCH (Canvas Content Indexing)
# ============================================
# Upstash Search endpoint
UPSTASH_SEARCH_URL="https://your-instance.upstash.io"
# Upstash Search token (server-side)
UPSTASH_SEARCH_TOKEN="your-token"
# Upstash Search token (client-side)
NEXT_PUBLIC_UPSTASH_SEARCH_TOKEN="your-public-token"

# ============================================
# AI API KEYS
# ============================================
# Anthropic API key (required for Claude Sonnet 4.5)
ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI API key (required for embeddings)
OPENAI_API_KEY="sk-..."

# Google Generative AI API key (optional)
GOOGLE_GENERATIVE_AI_API_KEY="..."

​
Optional: Mobile App Environment

For mobile development, create apps/native/.env:
apps/native/.env
# Server URL (points to your local dev server)
EXPO_PUBLIC_SERVER_URL="http://localhost:3000"

​
Optional: Web App Environment

For web-specific configuration, create apps/web/.env:
apps/web/.env
# Public server URL (for production)
NEXT_PUBLIC_SERVER_URL="https://your-domain.com"

​
Environment Variable Reference

Here’s a complete reference of all environment variables:
PostgreSQL connection string in the format:
postgresql://[user]:[password]@[host]:[port]/[database]
Example with Neon:
postgresql://user:[email protected]/maxw_ai?sslmode=require
Secret key for Better-Auth session encryption. Generate with:
openssl rand -base64 32
Must be at least 32 characters long and kept secure.
Anthropic API key for Claude Sonnet 4.5. Required for the AI chat feature.Get your API key from console.anthropic.com.Format: sk-ant-api03-...
OpenAI API key used for generating embeddings when indexing Canvas content.Get your API key from platform.openai.com.Format: sk-...
Optional Google AI API key for additional AI features.Get from ai.google.dev.

​
Database Initialization

After configuring your environment variables, initialize the database:

​
Push Schema to Database

Push the Drizzle schema to your PostgreSQL database: 
bun db:push
This command:
  1. Reads your DATABASE_URL from the root .env file
  2. Connects to PostgreSQL
  3. Creates all tables defined in apps/web/src/db/schema/:
    • user - User accounts
    • session - Authentication sessions
    • account - OAuth provider credentials
    • verification - Email verification tokens
    • todo - Task items with Canvas linking
    • studySet and studySetItem - Study materials
    • memory - AI persistent memory
For development, use bun db:push. For production, use migrations with bun db:migrate.

​
Generate Migration Files (Optional)

If you need to create migration files for version control: 
bun db:generate
This generates SQL migration files in apps/web/src/db/migrations/.

​
View Database with Drizzle Studio

Explore your database visually: 
bun db:studio
This opens Drizzle Studio at http://localhost:4983 where you can:
  • View all tables and relationships
  • Browse and edit data
  • Run SQL queries
  • Inspect schema structure

​
Development Setup

​
Start Development Servers

Start all applications in development mode: 
bun dev

​
Development Server Details

Web App (bun dev:web):
  • Runs on http://localhost:3000
  • Uses Next.js 16 with Turbopack for fast refresh
  • API routes available at /api/*
  • Hot module replacement enabled
Mobile App (bun dev:native):
  • Starts Expo development server
  • Accessible via Expo Go app (scan QR code)
  • iOS simulator: Press i
  • Android emulator: Press a

​
Code Quality Tools

Run Biome for formatting and linting: 
bun check
This automatically:
  • Formats all code with Biome’s rules (double quotes, spaces)
  • Sorts imports and Tailwind classes
  • Fixes auto-fixable issues
  • Reports remaining errors
This project uses Biome, not ESLint or Prettier. Biome is configured for double quotes and space indentation.

​
Production Setup

​
Build for Production

Build all applications: 
bun build

​
Production Environment Variables

For production deployments, add these additional variables:
.env.production
# Production database (use connection pooling)
DATABASE_URL="postgresql://..."

# Production server URL
NEXT_PUBLIC_SERVER_URL="https://your-domain.com"

# Vercel-specific (if deploying to Vercel)
VERCEL_URL="your-app.vercel.app"

​
Database Migrations for Production

For production, use migrations instead of db:push:
  1. Generate migration files: 
    bun db:generate
  2. Review generated SQL in apps/web/src/db/migrations/
  3. Run migrations: 
    bun db:migrate

​
Deployment Recommendations

Vercel

Recommended for Web App
  • Zero-config deployment
  • Automatic preview URLs
  • Built-in analytics
  • Edge function support

Expo EAS

Recommended for Mobile App
  • Build iOS and Android apps
  • Over-the-air updates
  • Submission to app stores
  • Integrated with Expo ecosystem

​
Troubleshooting

If Bun installation fails:macOS/Linux:
  • Ensure you have curl installed: which curl
  • Try manual installation from bun.sh/install
  • Check system requirements: 64-bit system required
Windows:
  • Ensure WSL2 is properly installed and updated
  • Run wsl --update to get latest WSL version
  • Install Bun inside WSL, not in Windows directly
If you can’t connect to PostgreSQL:
  1. Check if PostgreSQL is running: 
    pg_isready
  2. Verify the port (usually 5432): 
    sudo lsof -i :5432
  3. Check pg_hba.conf for connection permissions
  4. For Docker, ensure container is running: 
    docker ps | grep postgres
If bun db:push fails:
  1. Verify your DATABASE_URL in root .env (not apps/web/.env)
  2. Check PostgreSQL version: psql --version (need 14+)
  3. Ensure database exists: createdb maxw_ai
  4. Check database permissions
  5. Review error message for specific table/column issues
If you see module resolution errors:
  1. Clear Bun cache: 
    rm -rf node_modules
bun install
  2. Clear Next.js cache: 
    rm -rf apps/web/.next
  3. Ensure you’re using Bun, not npm: 
    which bun
bun --version
If you see TypeScript errors in your IDE:
  1. Ensure TypeScript extension is installed
  2. Reload IDE window
  3. Check TypeScript version: 
    bun check-types
  4. Verify workspace is opened at repo root, not subdirectory
If AI chat fails with API errors:
  1. Verify your ANTHROPIC_API_KEY is correct
  2. Check API key has not expired
  3. Ensure you have API credits: console.anthropic.com
  4. Check browser console (F12) for detailed error messages
  5. Review server logs for API response details
If mobile app can’t connect to server:
  1. Ensure web server is running: bun dev:web
  2. Check EXPO_PUBLIC_SERVER_URL in apps/native/.env
  3. Use your computer’s local IP, not localhost: 
    # macOS/Linux
ifconfig | grep "inet "
# Use: http://192.168.1.x:3000
  4. Ensure mobile device is on same WiFi network
  5. Check firewall isn’t blocking port 3000

​
Next Steps

Your installation is complete! Here’s what to do next:

Quickstart Guide

Follow the quickstart to create your first account and chat

AI Features

Learn about the AI assistant capabilities

Canvas Integration

Connect your Canvas LMS account

Development Guide

Learn about the codebase architecture
For questions or issues, check the GitHub repository’s issues page or join the community discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us