Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Praashh/buildml/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning Buildml, wiring up the required services, seeding the database, and launching the development server. By the end you will have a fully functional local instance — including Google OAuth sign-in and sample AI/ML challenges ready to solve.

​
Prerequisites

Make sure the following are installed and available in your PATH before you begin:
  • Bun — used as the package manager and script runner (bun install, bun run dev)
  • Node.js — required by the Next.js runtime (Bun ships a compatible version; install separately if needed)
  • PostgreSQL — a running database server (local install, Docker, or a cloud provider such as Neon or Supabase)
  • Google OAuth credentials — a Client ID and Client Secret from Google Cloud Console (needed for NextAuth.js sign-in)
  • Python 3.10+ — required to run the FastAPI executor service that sandboxes and evaluates user code
The FastAPI executor service runs as a separate process from the Next.js application. It must be reachable at the URL you set in EXECUTOR_URL (default: http://localhost:8000). Submissions will not execute until this service is running. Refer to the executor’s own README for startup instructions.

​
Setup

1

Clone the repository

git clone https://github.com/Praashh/buildml.git
cd buildml
2

Install dependencies

Bun resolves and installs all Node dependencies, then automatically runs prisma generate via the postinstall hook to produce the typed Prisma client.
bun install
3

Configure environment variables

Copy the example file and open it in your editor:
cp .env.example .env
Fill in every value listed below. The application uses @t3-oss/env-nextjs with Zod to validate these at startup — missing or malformed values will cause a clear error message rather than a silent failure.
# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/buildml"

# Authentication (NextAuth.js v5)
# Note: src/env.js reads this as NEXTAUTH_SECRET (process.env.NEXTAUTH_SECRET).
# The .env.example file shows AUTH_SECRET, but the correct variable name is NEXTAUTH_SECRET.
NEXTAUTH_SECRET=""              # Random string — generate with: openssl rand -base64 32
GOOGLE_CLIENT_ID=""             # From Google Cloud Console
GOOGLE_CLIENT_SECRET=""         # From Google Cloud Console

# Upstash Redis (rate limiting + run result cache)
UPSTASH_REDIS_REST_URL=""
UPSTASH_REDIS_REST_TOKEN=""

# Upstash QStash (async code-execution queue)
QSTASH_TOKEN=""
QSTASH_CURRENT_SIGNING_KEY=""
QSTASH_NEXT_SIGNING_KEY=""

# Application URLs
# DEPLOYMENT_URL is read from NEXT_PUBLIC_DEPLOYMENT_URL at runtime (see src/env.js).
NEXT_PUBLIC_DEPLOYMENT_URL="http://localhost:3000"  # Public URL QStash posts callbacks to
EXECUTOR_URL="http://localhost:8000"                # FastAPI executor endpoint (default)
EXECUTOR_SECRET="dev-secret"                        # Shared secret for executor auth
DEPLOYMENT_URL in src/env.js is populated from process.env.NEXT_PUBLIC_DEPLOYMENT_URL at runtime. Always set NEXT_PUBLIC_DEPLOYMENT_URL in your .env file — not a variable named DEPLOYMENT_URL.
4

Push the database schema

Apply the Prisma schema to your PostgreSQL database. Use db:push for local development and prototyping — it syncs the schema without creating a migration file.
bun run db:push
When you are ready to generate versioned migration files (for example, before a production deploy), use db:generate instead:
bun run db:generate
5

Seed sample data

Buildml ships three seed scripts that populate the database with real challenge content:
ScriptContent
prisma/seed.tsCore seed data and initial Problem Sets
prisma/seed-numpy.tsNumPy Fundamentals challenge set
prisma/seed-nn.tsNeural Networks challenge set
Run each script with Bun:
bun prisma/seed.ts
bun prisma/seed-numpy.ts
bun prisma/seed-nn.ts
6

Start the development server

Buildml uses Next.js Turbopack in development for fast refresh.
bun run dev
7

Open the app

Navigate to http://localhost:3000 in your browser. Sign in with Google and start solving challenges.
Run bun run db:studio at any time to open Prisma Studio — a visual browser-based interface for inspecting and editing your local database rows. It is especially useful for verifying that seed data loaded correctly or for debugging submission records.

​
Available Dev Commands

# Start development server (Next.js + Turbopack)
bun run dev

# Production build
bun run build

# Start production server
bun run start

# TypeScript type checking (no emit)
bun run typecheck

# Lint and format check (Biome)
bun run check

# Auto-fix linting and formatting
bun run check:write

# Auto-fix with unsafe transformations
bun run check:unsafe

# Push schema changes to the database (no migration file)
bun run db:push

# Create a versioned migration (production changes)
bun run db:migrate

# Run migrations and regenerate Prisma client
bun run db:generate

# Open Prisma Studio GUI
bun run db:studio

Build docs developers (and LLMs) love

Get started for freeTalk to us