Installation¶

!!! info "TL;DR" Self-host Canviq with Next.js 15 and Supabase. Clone the repo, configure environment variables, run migrations, and start the development server. Production deployment via Vercel or Docker.

Prerequisites¶

Before you begin, ensure you have:

• Node.js 20+ and npm 9+
• Git for cloning the repository
• Supabase CLI (npm install -g supabase)
• PostgreSQL 15+ (local or cloud)
• A Supabase project (create one for free)

Quick Install (Local Development)¶

Step 1: Clone the Repository¶

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

Step 2: Install Dependencies¶

npm install

This installs Next.js, Supabase client, and all required packages.

Step 3: Set Up Supabase¶

Start a local Supabase instance:

npx supabase start

This launches PostgreSQL, PostgREST, and the Supabase Studio UI at http://localhost:54323.

Alternative: Use a cloud Supabase project. Copy the project URL and anon key from the Supabase dashboard.

Step 4: Configure Environment Variables¶

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

cp .env.example .env.local

Edit .env.local with your Supabase credentials:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Site
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# GitHub (optional, for issue sync)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_REPO=YourOrg/your-repo

# Email (optional, for notifications)
RESEND_API_KEY=re_xxxxxxxxxxxx

# AI (optional, for sentiment analysis)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

# Workflow Automation (optional)
INNGEST_SIGNING_KEY=signkey-prod-xxxxxxxxxxxx
INNGEST_EVENT_KEY=eventkey-prod-xxxxxxxxxxxx

# Rate Limiting (optional, for MCP)
UPSTASH_REDIS_REST_URL=https://xxxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxxxx

Step 5: Run Database Migrations¶

Apply schema migrations to create tables:

npx supabase db reset

This runs all migrations in supabase/migrations/ and seeds the database with sample data (categories, tags, and test submissions).

!!! tip For production, use npx supabase db push to apply migrations without seeding.

Step 6: Generate TypeScript Types¶

Generate type definitions from the database schema:

npx supabase gen types typescript --local > src/types/database.ts

This creates type-safe Supabase client helpers.

Step 7: Start the Development Server¶

npm run dev

Navigate to http://localhost:3000 to see the Canviq feedback board.

Production Deployment¶

Option 1: Vercel (Recommended)¶

Canviq is optimized for Vercel deployment:

1. Push to GitHub: Commit your changes and push to a GitHub repository
2. Import to Vercel: Go to vercel.com and import the repo
3. Configure Environment Variables: Add production environment variables in the Vercel dashboard
4. Deploy: Vercel automatically builds and deploys on push to main

Environment Variables for Production:

NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_SITE_URL=https://canviq.app
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_REPO=YourOrg/your-repo
RESEND_API_KEY=re_xxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
INNGEST_SIGNING_KEY=signkey-prod-xxxxxxxxxxxx
INNGEST_EVENT_KEY=eventkey-prod-xxxxxxxxxxxx
UPSTASH_REDIS_REST_URL=https://xxxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxxxx

Option 2: Docker¶

Build and run Canviq in a Docker container:

# Build the image
docker build -t canviq .

# Run the container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co \
  -e NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  -e SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  canviq

Option 3: Node.js Server¶

Build and run with the standalone output:

# Build for production
npm run build

# Start the production server
npm run start

Canviq will run on http://localhost:3000 by default. Use a reverse proxy (Nginx, Caddy) for HTTPS and custom domains.

Post-Installation Setup¶

Create an Admin Account¶

1. Navigate to /auth/signup
2. Create an account with your email
3. Manually add your user ID to the team_members table:

INSERT INTO team_members (user_id, role, organization_id)
VALUES ('your-user-id', 'admin', 'your-org-id');

Configure GitHub Integration¶

1. Create a GitHub personal access token with repo scope
2. Add the token to GITHUB_TOKEN in environment variables
3. Set GITHUB_REPO to your repository (e.g., YourOrg/your-repo)

Test Email Notifications¶

Send a test email via the Resend dashboard to verify SMTP configuration.

Enable MCP Server¶

Generate an API key for your AI agent:

POST /api/auth/keys
Authorization: Bearer <your-session-token>
Content-Type: application/json

{
  "name": "Claude Agent",
  "scopes": ["survey:create", "response:read", "workflow:write"]
}

Troubleshooting¶

Database Connection Errors¶

Symptom: Error: relation "submissions" does not exist

Fix: Run migrations:

npx supabase db reset

Supabase Auth Errors¶

Symptom: Error: Invalid JWT

Fix: Verify NEXT_PUBLIC_SUPABASE_ANON_KEY matches your Supabase project. Copy from the Supabase dashboard under Settings → API.

Build Errors¶

Symptom: Type error: Property 'x' does not exist on type 'Database'

Fix: Regenerate types:

npx supabase gen types typescript --local > src/types/database.ts

Missing Environment Variables¶

Symptom: Error: NEXT_PUBLIC_SUPABASE_URL is not defined

Fix: Ensure .env.local exists and contains all required variables. Restart the dev server after changes.

Updating Canviq¶

Pull the latest changes from GitHub:

git pull origin main
npm install
npx supabase db push
npm run build

For production, trigger a redeploy in Vercel or rebuild the Docker image.

What's Next?¶

• Set up authentication
• Create your first submission
• Configure the admin dashboard
• Enable GitHub integration

Need help? Check the GitHub Issues or join the Discord community.