Skip to main content
This guide will help you install and set up Evaly on your local machine or server for self-hosting.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Bun v1.0.0 or higher
  • Node.js v18.0.0 or higher (required for Convex CLI)
  • Git for cloning the repository
  • A Convex account for backend services
Evaly uses Bun as its runtime, not Node.js. Make sure to use Bun commands for running the application.

​
Quick Start

1

Clone the Repository

Clone the Evaly repository to your local machine:
git clone https://github.com/fahreziadh/evaly.git
cd evaly
2

Install Dependencies

Install all required dependencies using Bun:
bun install
This will install all frontend and backend dependencies including:
  • TanStack Start (React 19 meta-framework)
  • Convex SDK for backend integration
  • Tailwind CSS v4 for styling
  • shadcn/ui components
  • TipTap rich text editor
3

Set Up Convex Backend

Create a new Convex project or link to an existing one:
npx convex dev
This command will:
  • Create a new Convex deployment (if you don’t have one)
  • Generate your deployment credentials
  • Start the Convex development server
  • Watch for changes in the convex/ directory
Keep this terminal window open. The Convex development server needs to run continuously.
4

Configure Environment Variables

The Convex CLI will automatically create a .env.local file with your deployment URL. Verify it contains:
CONVEX_DEPLOYMENT=your-convex-deployment-name
See the Environment Configuration page for detailed environment variable setup.
5

Start the Development Server

Open a new terminal window and start the frontend development server:
bun run dev
The application will be available at http://localhost:3000

​
Tech Stack Overview

​
Frontend

  • Framework: TanStack Start - React 19 meta-framework with file-based routing
  • Runtime: Bun - Fast JavaScript runtime
  • Styling: Tailwind CSS v4 with custom design tokens
  • UI Components: shadcn/ui built on Radix UI primitives
  • Rich Text Editor: TipTap for question creation
  • Build Tool: Vite bundler

​
Backend

  • Backend: Convex - Serverless backend with real-time capabilities
  • Database: Convex’s built-in database with schema validation
  • Authentication: Convex Auth with multi-provider support (Google OAuth)
  • Real-time: WebSocket subscriptions for live updates
  • File Storage: Cloudflare R2 via @convex-dev/r2

​
Additional Components

  • @convex-dev/presence: Real-time presence tracking for test monitoring
  • @convex-dev/agent: AI agent framework for question generation
  • @convex-dev/polar: Subscription and billing integration

​
Project Structure

evaly/
├── convex/                     # Backend logic and database schema
│   ├── organizer/             # Organizer-specific server functions
│   ├── participant/           # Participant-specific server functions
│   ├── ai/                    # AI question generation
│   ├── common/                # Shared utilities (email, storage, permissions)
│   ├── internal/              # Internal scheduled functions
│   ├── schemas/               # Database schema definitions
│   ├── auth.config.ts         # Authentication configuration
│   ├── convex.config.ts       # Convex components configuration
│   └── schema.ts              # Main schema file
├── src/
│   ├── components/
│   │   ├── pages/             # Full page components
│   │   ├── shared/            # Reusable business components
│   │   └── ui/                # Base UI primitives (shadcn/ui)
│   ├── hooks/                 # Custom React hooks
│   ├── lib/                   # Utility functions and configurations
│   ├── routes/                # File-based routing structure
│   │   ├── (organizer)/       # Protected organizer routes
│   │   ├── (participant)/     # Public participant routes
│   │   └── __root.tsx         # Root layout component
│   └── main.tsx               # Application entry point
├── public/                    # Static assets
├── package.json               # Dependencies and scripts
├── vite.config.ts            # Vite configuration
└── wrangler.jsonc            # Cloudflare Workers configuration

​
Development Scripts

# Start frontend development server
bun run dev

# Start Convex backend development server (separate terminal)
npx convex dev

​
Verification

After completing the installation, verify everything is working:
  1. Frontend: Visit http://localhost:3000 - you should see the Evaly landing page
  2. Backend: Check the Convex dashboard at dashboard.convex.dev - your deployment should show as active
  3. Database: The Convex dev server will automatically create all necessary database tables based on your schema
If you encounter any issues, make sure both the Convex backend (npx convex dev) and frontend (bun run dev) servers are running in separate terminal windows.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us