Installation

This guide provides detailed instructions for setting up Uxie on your local machine, including all required services and environment configurations.

Prerequisites

Before installing Uxie, ensure you have the following:

Required Software

Node.js v18 or later (download)
pnpm package manager (installation)
PostgreSQL database (local or cloud-hosted)
Git for version control

Required Service Accounts

You’ll need accounts for the following services:

Supabase

PostgreSQL database hosting

Uploadthing

PDF file storage and CDN

Pinecone

Vector database for embeddings

Google Cloud

OAuth and AI services

Hugging Face

AI model embeddings

Liveblocks

Real-time collaboration (optional)

Installation Steps

Clone the Repository

git clone https://github.com/zeus-12/uxie.git
cd uxie

Install Dependencies

pnpm install

The postinstall script will automatically run prisma generate to create the Prisma client.

Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Open .env in your editor and configure all required variables (see below).

Set Up Database

After configuring DATABASE_URL, push the Prisma schema:

pnpm prisma db push

This creates all necessary tables in your PostgreSQL database.

Start Development Server

pnpm dev

The application will be available at http://localhost:3000

Environment Variables

Uxie requires several environment variables to function properly. Below is a comprehensive guide for each variable.

Database Configuration

.env

DATABASE_URL="postgresql://user:password@localhost:5432/uxie"

How to get it:

Create Supabase Project

Go to Supabase and create a new project
Wait for the project to be provisioned

Get Connection String

Navigate to Project Settings → Database
Find the Connection String section
Copy the Connection pooling string (recommended for serverless)
Replace [YOUR-PASSWORD] with your database password

For local PostgreSQL, use: postgresql://postgres:password@localhost:5432/uxie

Authentication (NextAuth.js)

.env

NEXTAUTH_SECRET="your-secret-here"
NEXTAUTH_URL="http://localhost:3000"

NEXTAUTH_SECRET: Generate a secure random string:

openssl rand -base64 32

NEXTAUTH_URL: Your application URL

Development: http://localhost:3000
Production: Your deployed domain (e.g., https://uxie.vercel.app)

Google OAuth

.env

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

Create OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID

Configure OAuth Consent Screen

Click Configure Consent Screen
Choose External user type
Fill in application name and support email
Add scopes: email, profile, openid

Create OAuth Client

Application type: Web application
Add authorized redirect URIs:
- http://localhost:3000/api/auth/callback/google (development)
- https://yourdomain.com/api/auth/callback/google (production)
Copy the Client ID and Client Secret

File Upload (Uploadthing)

.env

UPLOADTHING_TOKEN="your-uploadthing-token"

Create Uploadthing Account

Go to Uploadthing
Sign up and create a new application

Get API Token

Navigate to your app’s settings
Copy the Secret Key (starts with sk_live_ or sk_test_)
Use this as UPLOADTHING_TOKEN

Keep your Uploadthing token secret. Never commit it to version control.

AI Features (Google Generative AI)

.env

GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"

Enable Generative AI API

Go to Google AI Studio
Click Get API Key
Create a new API key or use an existing one

This powers:

Document summarization
Question answering
Flashcard generation and evaluation
Text enhancement and autocompletion

Vector Database (Pinecone)

.env

PINECONE_API_KEY="your-pinecone-api-key"
PINECONE_ENVIRONMENT="your-environment"

Create Pinecone Account

Sign up at Pinecone
Create a new project

Create Index

Click Create Index
Configure:
- Name: uxie (or your preferred name)
- Dimensions: 768 (for Hugging Face embeddings)
- Metric: cosine
- Pod Type: Starter (free tier) or as needed
Click Create Index

Get API Key and Environment

Go to API Keys in your project
Copy the API key
Note your environment (e.g., us-west1-gcp, eu-west1-aws)

Pinecone stores vector embeddings of your PDFs for semantic search and RAG (Retrieval Augmented Generation).

Embeddings (Hugging Face)

.env

HUGGINGFACE_API_KEY="hf_your_token_here"

Create Access Token

Go to Hugging Face Settings
Click New token
Name: uxie-embeddings
Role: Read (inference API access)
Copy the token

Uxie uses Hugging Face models to generate 768-dimensional embeddings for document vectorization.

Supabase Configuration

.env

PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_SERVICE_KEY="your-service-role-key"

Get Supabase Credentials

In your Supabase project, go to Project Settings → API
Copy:
- Project URL → PUBLIC_SUPABASE_URL
- service_role secret → SUPABASE_SERVICE_KEY

The service role key bypasses Row Level Security. Keep it secret and only use it server-side.

Real-time Collaboration (Liveblocks)

.env

NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY="pk_live_your_key"

Create Liveblocks Account

Sign up at Liveblocks
Create a new project

Get Public API Key

Go to your project settings
Copy the Public API key (starts with pk_)

Collaboration features may be limited in the free tier. This is optional for basic functionality.

Node Environment

.env

NODE_ENV="development"

Set to:

development for local development
production for deployed environments
test for testing

Database Setup

Uxie uses Prisma as the ORM and PostgreSQL as the database.

Schema Overview

The database includes models for:

User: Authentication and user profiles
Account: OAuth provider accounts
Document: PDF documents and metadata
Highlight: Text and image highlights
Message: AI chat messages
Flashcard: Learning flashcards
FlashcardAttempt: User responses and AI evaluations
Collaborator: Document sharing and permissions
Feedback: User feedback submissions

Applying Schema Changes

# Push schema to database (development)
pnpm prisma db push

# Generate Prisma client
pnpm prisma generate

# Open Prisma Studio (database GUI)
pnpm prisma studio

prisma db push is recommended for development. For production, use migrations:

pnpm prisma migrate deploy

Database Relationships

Key relationships:

Users have many Documents (one-to-many)
Documents have many Highlights, Messages, and Flashcards
Collaborators link Users to Documents with specific roles (OWNER, EDITOR, VIEWER)
FlashcardAttempts track user responses and AI evaluations

Verification

After setup, verify everything works:

Check Database Connection

pnpm prisma studio

This should open Prisma Studio at http://localhost:5555

Test Development Server

pnpm dev

Visit http://localhost:3000 and verify the page loads.

Test Authentication

Click “Sign in”
Authenticate with Google
Verify you’re redirected to the dashboard

Test File Upload

Upload a small PDF
Check that it appears in your documents
Verify you can open and view it

Production Build

To test the production build locally:

# Build the application
pnpm build

# Start production server
pnpm start

The production build:

Optimizes and minifies code
Generates static pages where possible
Validates environment variables
Creates optimized images and assets

Troubleshooting

Prisma Client errors

If you see “Prisma Client not found” errors:

pnpm prisma generate

This regenerates the Prisma client based on your schema.

Database connection fails

Check DATABASE_URL format:

postgresql://user:password@host:port/database?schema=public

Test connection:

pnpm prisma db push

Common issues:

Incorrect password or username
Database doesn’t exist
PostgreSQL not running
Firewall blocking connection
SSL mode mismatch (add ?sslmode=require for cloud databases)

Environment variables not loading

Verify .env file location:

Must be in the root directory (same level as package.json)
Named exactly .env (not .env.local or .env.development)

Restart dev server:

# Kill the server (Ctrl+C)
pnpm dev

Check variable validation: Look in src/env.mjs for required variables and their validation rules.

OAuth redirect URI mismatch

Error: “redirect_uri_mismatch”Solution:

Go to Google Cloud Console
Check Authorized redirect URIs
Ensure it includes: http://localhost:3000/api/auth/callback/google
URIs must match exactly (no trailing slashes)

Uploadthing upload fails

Check:

UPLOADTHING_TOKEN is valid and not expired
File size is within limits (check your Uploadthing plan)
Network connection is stable

Test with smaller file: Try uploading a small (under 1MB) PDF first.

Pinecone errors

Index configuration mismatch:

Dimensions must be 768
Metric should be cosine

Check index exists:

# Index name should match what's used in the code
# Default: uses PINECONE_INDEX_NAME from env

Recreate index if needed with correct dimensions.

Build fails

Type errors:

pnpm typecheck

Clear cache and rebuild:

rm -rf .next
pnpm build

Check Node.js version:

node --version  # Should be v18 or later

Optional Configuration

Custom Port

Change the development port:

package.json

"dev": "next dev -p 3001"

Or use an environment variable:

PORT=3001 pnpm dev

TypeScript Configuration

Uxie uses strict TypeScript settings. See tsconfig.json for configuration.

Code Quality

# Run ESLint
pnpm lint

# Type checking
pnpm typecheck

# Format code
pnpm format

Next Steps

Quickstart Guide

Get up and running quickly

Architecture

Understand how Uxie works

API Reference

Explore the tRPC API

Contributing

Join the development

Architecture

Understand Uxie’s technical architecture

API Reference

Explore the tRPC API endpoints

Contributing

Contribute to Uxie’s development

Getting Help

If you encounter issues not covered here:

Check GitHub Issues for similar problems
Review the README for additional context
Open a new issue with:
- Your Node.js version (node --version)
- Error messages (full stack trace)
- Steps to reproduce
Join the community discussion on GitHub

For production deployments, consider using Vercel for easy setup with automatic environment variable management and zero-config deployments.

Get Started

Core Features

Advanced Features

Configuration

​Prerequisites

​Required Software

​Required Service Accounts

Supabase

Uploadthing

Pinecone

Google Cloud

Hugging Face

Liveblocks

​Installation Steps

​Environment Variables

​Database Configuration

​Authentication (NextAuth.js)

​Google OAuth

​File Upload (Uploadthing)

​AI Features (Google Generative AI)

​Vector Database (Pinecone)

​Embeddings (Hugging Face)

​Supabase Configuration

​Real-time Collaboration (Liveblocks)

​Node Environment

​Database Setup

​Schema Overview

​Applying Schema Changes

​Database Relationships

​Verification

​Production Build

​Troubleshooting

​Optional Configuration

​Custom Port

​TypeScript Configuration

​Code Quality

​Next Steps

Quickstart Guide

Architecture

API Reference

Contributing

Architecture

API Reference

Contributing

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Required Software

Required Service Accounts

Installation Steps

Environment Variables

Database Configuration

Authentication (NextAuth.js)

Google OAuth

File Upload (Uploadthing)

AI Features (Google Generative AI)

Vector Database (Pinecone)

Embeddings (Hugging Face)

Supabase Configuration

Real-time Collaboration (Liveblocks)

Node Environment

Database Setup

Schema Overview

Applying Schema Changes

Database Relationships

Verification

Production Build

Troubleshooting

Optional Configuration

Custom Port

TypeScript Configuration

Code Quality

Next Steps

Getting Help