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

MCP Server

The Model Context Protocol (MCP) server is available at http://127.0.0.1:54321/mcp for AI assistance features. This endpoint:

Provides AI assistants with secure access to help requests, discussions, and submissions
Requires API token authentication (create tokens via the UI)
Is restricted to instructors and graders only

See the AI assistance documentation for more details on using the MCP server.

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

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

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

Continuous Integration

The project uses GitHub Actions for continuous integration and deployment:

Build Process: Automated builds run in GitHub Actions (migrated from Coolify)
Testing: E2E tests run automatically on pull requests
Deployment: Staging deployments use the dev environment configuration

All CI workflows are defined in .github/workflows/ and handle building, testing, and deploying the application.

Cursor Agent Development

For AI-assisted development using Cursor, see the AGENTS.md file in the repository root for Cursor Cloud-specific setup instructions, including:

Docker daemon configuration for cloud environments
Supabase migration workarounds
Environment variable setup
Pre-commit formatting requirements
Build and test commands

Cursor Agent Development Environment

Pawtograder includes a Cursor agent development environment setup that allows AI assistants to help with development tasks. This environment provides:

Pre-configured development container settings
Access to the codebase structure and conventions
Integration with the local development environment

Setup

The Cursor agent environment is automatically configured when you clone the repository. The configuration files are located in the .cursor directory and include:

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

Usage

When using Cursor or other AI-powered development tools, the agent will have access to:

Project structure and file organization
Database schema and migrations
Component patterns and conventions
Testing setup and examples

This helps AI assistants provide more accurate and context-aware suggestions when working on Pawtograder features.

Next Steps

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

Getting Started

Tools

Documentation Index

​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

​MCP Server

​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

​Continuous Integration

​Cursor Agent Development

​Cursor Agent Development Environment

​Setup

​Usage

​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

MCP Server

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

Continuous Integration

Cursor Agent Development

Cursor Agent Development Environment

Setup

Usage

Next Steps