Skip to content

Development Setup

!!! info "TL;DR" Install Node 20+, npm, Docker. Clone the repo, run npm install, start Supabase with npx supabase start, apply migrations with npx supabase db reset, and start the dev server with npm run dev.

Prerequisites

Before you begin, ensure you have these tools installed:

  • Node.js 20+: Download or use nvm
  • npm: Comes with Node.js
  • Docker Desktop: Required for local Supabase (Download)
  • Git: For cloning the repository

Clone the Repository

git clone https://github.com/Revoir-Software/feedback.git
cd feedback

Install Dependencies

npm install

This installs all dependencies including Next.js, React, Supabase client, testing frameworks, and development tools.

Start Supabase Locally

Canviq uses Supabase for PostgreSQL and realtime subscriptions (authentication is handled by a custom session system, not Supabase Auth). Start the local Supabase stack:

npx supabase start

This command:

  • Starts Docker containers for PostgreSQL, Auth, Realtime, and Studio
  • Creates a local Supabase project
  • Outputs connection credentials (copy these for .env.local)

Important: The first run takes 5-10 minutes to download Docker images.

Apply Database Migrations

Apply all migrations and seed data:

npx supabase db reset

This command:

  • Drops and recreates the local database
  • Runs all migrations from supabase/migrations/
  • Seeds development data from supabase/seed.sql

You'll see output confirming each migration was applied successfully.

Configure Environment Variables

Create a .env.local file in the project root:

cp .env.example .env.local

Edit .env.local and add the credentials from npx supabase start output:

# Required — from npx supabase start output
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Required — custom auth session signing (min 32 characters)
SESSION_SECRET=change-me-to-a-random-string-at-least-32-chars

!!! warning "SESSION_SECRET is required" The auth system (src/lib/auth.ts) throws an error at runtime if SESSION_SECRET is not set. Generate a secure random string of at least 32 characters.

Optional: Configure these for full functionality (not required for basic development):

  • GITHUB_TOKEN: For GitHub issue creation
  • GITHUB_REPO: Target repository (e.g., Revoir-Software/feedback)
  • RESEND_API_KEY: For magic link emails and notifications
  • ANTHROPIC_API_KEY: For Claude-powered sentiment analysis
  • UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN: For session revocation and MCP rate limiting
  • INNGEST_SIGNING_KEY + INNGEST_EVENT_KEY: For workflow automation

See .env.example for the complete list with descriptions.

Start the Development Server

npm run dev

The app will be available at http://localhost:3000.

Verify the Setup

  1. Visit http://localhost:3000 — you should see the public feedback board
  2. Visit http://localhost:54323 — Supabase Studio for database inspection
  3. Create a test submission — verify it appears in the database

Common Issues

Docker not running

Error: Cannot connect to the Docker daemon

Solution: Start Docker Desktop before running npx supabase start

Port conflicts

Error: Port 54321 is already in use

Solution: Stop other services using those ports, or configure Supabase to use different ports in supabase/config.toml

Missing environment variables

Error: Missing NEXT_PUBLIC_SUPABASE_URL

Solution: Ensure .env.local exists and contains the correct credentials from npx supabase start

What's next