Local Development Setup

This guide walks you through setting up Pawtograder for local development.

Prerequisites

Before starting, ensure you have the following installed:

Requirement	Version	Notes
Node.js	v22 (recommended)	Use nvm for version management
Docker	Latest	Required for local Supabase. Can use Docker desktop to quickly setup a docker daemon for development.
Git	Latest	For cloning the repository

Quick Start (Staging Backend)

The fastest way to get started is using our staging environment as a backend. This is ideal for frontend development that doesn’t require database changes.

Steps

Clone the repository

git clone https://github.com/pawtograder/platform.git
cd platform

Install dependencies
npm install
Configure environment
cp .env.local.staging .env.local
Edit .env.local and fill in your own values if needed.
Start the development server
npm run dev
Access the application Open https://localhost:3000 in your browser. You’ll need to accept the self-signed certificate warning (HTTPS is required for camera/microphone access in the help queue).

Creating Test Accounts

In the staging environment, you can register with any email without confirmation:

Student account: Use any email (e.g., test@example.com)
Instructor account: Include “instructor” in your email (e.g., testinstructor@example.com)

New accounts are automatically added to the demo class.

Full Local Setup (Supabase)

For development requiring database changes, RLS policy modifications, or running E2E tests, you’ll need a local Supabase instance.

Prerequisites

Docker installed and running
Node.js v22 or later

Setup Steps

Install dependencies
npm install
Start Supabase
npx supabase start
This starts all Supabase services in Docker containers. First run may take several minutes to download images.
Initialize the database
npx supabase db reset
This applies all migrations and seeds initial data.

Configure environment variables After supabase start, you’ll see output like:

supabase local development setup is running.

╭──────────────────────────────────────╮
│ 🔧 Development Tools                 │
├─────────┬────────────────────────────┤
│ Studio  │ http://127.0.0.1:54323     │
│ Mailpit │ http://127.0.0.1:54324     │
│ MCP     │ http://127.0.0.1:54321/mcp │
╰─────────┴────────────────────────────╯

╭─────────────────────────────────────────────────╮
│ 🌐 APIs                                         │
├─────────────┬───────────────────────────────────┤
│ Project URL │ http://127.0.0.1:54321            │
│ REST        │ http://127.0.0.1:54321/rest/v1    │
│ GraphQL     │ http://127.0.0.1:54321/graphql/v1 │
╰─────────────┴───────────────────────────────────╯

╭───────────────────────────────────────────────────────────────╮
│ ⛁ Database                                                    │
├─────┬─────────────────────────────────────────────────────────┤
│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
╰─────┴─────────────────────────────────────────────────────────╯

╭──────────────────────────────────────────────────────────────╮
│ 🔑 Authentication Keys                                       │
├─────────────┬────────────────────────────────────────────────┤
│ Publishable │ sb_publishable_...                             │
│ Secret      │ sb_secret_...                                  │
╰─────────────┴────────────────────────────────────────────────╯

Update your .env.local:

SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<publishable key from output>
SUPABASE_SERVICE_ROLE_KEY=<secret key from output>
ENABLE_SIGNUPS=true

Never expose SUPABASE_SERVICE_ROLE_KEY to the browser or commit it to version control. Keep it in server-only code and CI secrets.

Start Edge Functions
npx supabase functions serve
Start the development server
npm run dev
Seed test data (optional)
npm run seed
This creates a test class with students and assignments. Scroll up in the output to find “Login Credentials” with email/password pairs.

The build process now runs in GitHub Actions for continuous integration. Local development uses npm run dev for hot-reloading without requiring a separate build step.

Local Services

Once Supabase is running, these services are available:

Service	URL	Description
API	http://127.0.0.1:54321	Supabase REST API
Studio	http://localhost:54323	Database management UI
Inbucket	http://localhost:54324	Email testing interface
MCP Server	http://127.0.0.1:54321/mcp	Model Context Protocol server for AI assistance
Application	https://localhost:3000	Next.js frontend

Supabase Studio

Access the Supabase dashboard at http://localhost:54323 to:

Browse and edit database tables
View and manage auth users
Test RLS policies
Monitor realtime subscriptions
Manage storage buckets

Email Testing

View captured emails at http://localhost:54324. Useful for testing:

Authentication flows (magic links, password reset)
Notification emails
Email verification

CI/CD Pipeline

Pawtograder uses GitHub Actions for continuous integration and deployment. The build process was migrated from Coolify to GitHub Actions to improve reliability and reduce test flakiness.

Build Process

The CI pipeline runs on every push and pull request, executing:

Dependency Installation: Installs npm packages and system dependencies
Type Checking: Validates TypeScript types across the codebase
Linting: Runs ESLint to enforce code quality standards
Unit Tests: Executes Jest test suites
E2E Tests: Runs Playwright tests against a test environment
Build: Compiles the Next.js application

Running CI Checks Locally

Before pushing code, run the same checks that CI will execute:

# Run all checks
npm run lint && npm run typecheck:functions && npm test

# Run E2E tests
npx playwright test

See the MCP server guide for details on the AI assistance endpoint exposed at http://127.0.0.1:54321/mcp.

Development Commands

Daily Development

# Start dev server with hot reload
npm run dev

# Run linting
npm run lint

# Format code
npm run format

# Run type checking
npm run typecheck:functions

Database Operations

# Start Supabase services
npx supabase start

# Stop Supabase services
npx supabase stop

# Reset database (reapply migrations + seed)
npx supabase db reset

# Create a new migration
npx supabase migration new migration_name

# Generate TypeScript types from schema
npm run client-local

Testing

# Run unit tests
npm test

# Run unit tests in watch mode
npm run test:watch

# Run E2E tests with UI
npx playwright test --ui

# Run specific E2E test file
npx playwright test surveys

Build and Deployment

# Build the application for production
npm run build

# Start production server
npm start

Seeding Data

# Create test class with sample data
npm run seed

CLI Operations

# Run the Pawtograder CLI (requires login)
npm run cli -- <command> [options]

# Convenience alias for repo operations
npm run cli:repos -- <command> [options]

# Login with API token
npm run cli -- login

# List classes
npm run cli -- classes list

# Copy assignments between classes
npm run cli -- assignments copy --source-class <slug> --target-class <slug> --all

# Sync grade.yml workflow to student repos
npm run cli:repos -- sync-grade-workflow --class <id> --assignment <id> --workdir <path>

The CLI provides commands for classes, assignments, surveys, flashcards, rubrics, submissions, and repository maintenance. Use --help on any command for detailed options. Repository operations use local SSH git for student repo writes.

Project Structure

platform/
├── app/                    # Next.js app router pages
│   └── course/[course_id]/ # Course-specific routes
├── components/             # Reusable React components
├── hooks/                  # Custom React hooks
├── types/                  # TypeScript type definitions
├── utils/                  # Utility functions
│   └── supabase/           # Supabase client configuration
├── supabase/
│   ├── migrations/         # Database migrations
│   ├── functions/          # Edge Functions (Deno)
│   ├── seed.sql            # Initial seed data
│   └── config.toml         # Supabase configuration
├── tests/
│   └── e2e/                # Playwright E2E tests
├── public/                 # Static assets
└── scripts/                # Build and utility scripts

Environment Variables

Required Variables

Variable	Description
`NEXT_PUBLIC_SUPABASE_URL`	Supabase API URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Supabase anonymous key
`SUPABASE_URL`	Supabase API URL (server-side)
`SUPABASE_SERVICE_ROLE_KEY`	Supabase service role key (server-side only)

Optional Variables

Variable	Description
`ENABLE_SIGNUPS`	Enable user registration UI (`true`/`false`)
`END_TO_END_SECRET`	Secret for E2E test authentication

Troubleshooting

Supabase won’t start

Ensure Docker is running
Check for port conflicts (54321, 54323, 54324)

Try stopping and removing containers:

npx supabase stop --no-backup
docker system prune
npx supabase start

Database connection errors

Verify Supabase is running: npx supabase status
Check .env.local has correct URLs and keys
Ensure you ran npx supabase db reset after starting

TypeScript errors after schema changes

Regenerate types after any database changes:

npm run client-local

HTTPS certificate warnings

The dev server uses a self-signed certificate. This is expected:

Click “Advanced” → “Proceed to localhost”
Or add an exception in your browser settings

Edge Functions not working

Ensure functions are running: npx supabase functions serve
Check the terminal for function errors
Verify function URLs in your requests

Hot reload not working

Check for file system watcher limits (Linux):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Restart the dev server

Cursor Agent Development

Pawtograder includes a Cursor agent development environment that lets AI assistants help with development tasks. Configuration files live in the .cursor directory and cover:

Development container settings
Code style and formatting rules
Project-specific AI assistant guidelines

For Cursor Cloud-specific setup instructions, see the AGENTS.md file in the repository root. It covers Docker daemon configuration for cloud environments, Supabase migration workarounds, environment variable setup, pre-commit formatting requirements, and build/test commands.

Next Steps

Read the Surveys Developer Guide for feature-specific documentation
Join the development discussion on GitHub Issues

Getting Started

Feature Internals

Integrations

Operations

Reference

Local Setup

Local Development Setup

Prerequisites

Quick Start (Staging Backend)

Steps

Creating Test Accounts

Full Local Setup (Supabase)

Prerequisites

Setup Steps

Local Services

Supabase Studio

Email Testing

CI/CD Pipeline

Build Process

Running CI Checks Locally

Development Commands

Daily Development

Database Operations

Testing

Build and Deployment

Seeding Data

CLI Operations

Project Structure

Environment Variables

Required Variables

Optional Variables

Troubleshooting

Supabase won’t start

Database connection errors

TypeScript errors after schema changes

HTTPS certificate warnings

Edge Functions not working

Hot reload not working

Cursor Agent Development

Next Steps

​Local Development Setup

​Prerequisites

​Quick Start (Staging Backend)

​Steps

​Creating Test Accounts

​Full Local Setup (Supabase)

​Prerequisites

​Setup Steps

​Local Services

​Supabase Studio

​Email Testing

​CI/CD Pipeline

​Build Process

​Running CI Checks Locally

​Development Commands

​Daily Development

​Database Operations

​Testing

​Build and Deployment

​Seeding Data

​CLI Operations

​Project Structure

​Environment Variables

​Required Variables

​Optional Variables

​Troubleshooting

​Supabase won’t start

​Database connection errors

​TypeScript errors after schema changes

​HTTPS certificate warnings

​Edge Functions not working

​Hot reload not working

​Cursor Agent Development

​Next Steps

Local Development Setup

Prerequisites

Quick Start (Staging Backend)

Steps

Creating Test Accounts

Full Local Setup (Supabase)

Prerequisites

Setup Steps

Local Services

Supabase Studio

Email Testing

CI/CD Pipeline

Build Process

Running CI Checks Locally

Development Commands

Daily Development

Database Operations

Testing

Build and Deployment

Seeding Data

CLI Operations

Project Structure

Environment Variables

Required Variables

Optional Variables

Troubleshooting

Supabase won’t start

Database connection errors

TypeScript errors after schema changes

HTTPS certificate warnings

Edge Functions not working

Hot reload not working

Cursor Agent Development

Next Steps