Web Deployment

Overview

This guide covers deploying Polaris IDE to production using Vercel, Convex, and Trigger.dev.

Vercel is recommended due to its seamless Next.js integration and automatic deployments.

Prerequisites

Vercel Account

Production Services

Convex production deployment
Trigger.dev production project
Stack Auth production project

Deployment Steps

1. Prepare Convex Production Database

Create production deployment

npx convex deploy --prod

This creates a separate production database and provides a production URL.

Note production URL

Copy the URL shown (format: https://your-deployment.convex.cloud)

Configure authentication

Update convex/auth.config.ts to support both development and production:

import { getConvexProvidersConfig } from "@stackframe/stack";

export default {
  providers: getConvexProvidersConfig({
    projectId: process.env.NEXT_PUBLIC_STACK_PROJECT_ID!,
  }),
};

2. Configure Trigger.dev Production

Create production environment

Go to trigger.dev
Navigate to your project
Create a “Production” environment
Copy the production API key

Deploy tasks

npx trigger.dev deploy

This uploads your background tasks to Trigger.dev’s infrastructure.

3. Set Up Stack Auth Production

Create production project

Go to Stack Auth dashboard
Create a new project or switch to production mode
Copy production keys

Configure allowed domains

Add your production domain to allowed origins:

https://your-app.vercel.app
https://yourdomain.com (if using custom domain)

Set up Convex integration

Configure Stack Auth to work with Convex production URL.

4. Deploy to Vercel

Using Vercel CLI
Using GitHub Integration
Manual Upload

# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Deploy
vercel --prod

Connect repository

Go to vercel.com/new
Import your GitHub repository
Select the Polaris project

Configure build settings

Vercel auto-detects Next.js. Override if needed:

Framework: Next.js
Build Command: npm run build
Output Directory: .next
Install Command: bun install (from vercel.json)

Add environment variables

See Environment Variables section below.

Deploy

Click “Deploy” - Vercel will build and deploy automatically.

# Build locally
npm run build

# Deploy build artifacts
vercel --prebuilt

5. Environment Variables

Add these environment variables in Vercel dashboard:

Authentication (Required)

NEXT_PUBLIC_STACK_PUBLISHABLE_KEY=pk_prod_xxx
STACK_SECRET_KEY=sk_prod_xxx

Database (Required)

NEXT_PUBLIC_CONVEX_URL=https://your-prod-deployment.convex.cloud
CONVEX_DEPLOYMENT=prod:your-deployment-name
POLARIS_CONVEX_INTERNAL_KEY=your_secure_random_string_prod

Background Jobs (Required)

TRIGGER_SECRET_KEY=tr_prod_xxx

AI Providers (At least one required)

# OpenRouter (Recommended)
OPENROUTER_API_KEY=sk-or-xxx

# Or Cerebras (Free alternative)
CEREBRAS_API_KEY=csk-xxx

Optional Services

# Sentry - Error tracking
SENTRY_DSN=https://[email protected]/xxx

# Firecrawl - Documentation scraping
FIRECRAWL_API_KEY=fc-xxx

# Autumn - Subscription billing
AUTUMN_SECRET_KEY=sk_live_xxx
AUTUMN_API_URL=https://api.autumncollective.com
NEXT_PUBLIC_AUTUMN_PRO_MONTHLY_PRODUCT_ID=prod_xxx
NEXT_PUBLIC_AUTUMN_PRO_YEARLY_PRODUCT_ID=prod_xxx

Build Configuration

# Node.js version
NODE_VERSION=20

# Enable standalone output for optimized builds
NEXT_BUILD_STANDALONE=true

Never commit production secrets to Git. Use Vercel’s environment variable dashboard.

6. Configure Custom Domain (Optional)

Add domain in Vercel

Go to Project Settings → Domains
Add your domain (e.g., polaris-ide.com)
Follow DNS configuration instructions

Update Stack Auth

Add custom domain to Stack Auth allowed origins

Update environment variables

If using domain-specific configs, update:

NEXT_PUBLIC_APP_URL
Any hardcoded URLs in code

Post-Deployment

Verify Deployment

Monitor Performance

Vercel Analytics

Monitor Core Web Vitals and performance metrics in Vercel dashboard

Sentry

Track errors, performance issues, and AI monitoring

Convex Dashboard

Monitor database queries, function calls, and real-time connections

Trigger.dev

Track background job executions and failures

Set Up Monitoring

Uptime Monitoring
Error Alerts
Performance Tracking

Use services like:

Monitor endpoints:

/ - Homepage
/api/health - Health check (if implemented)

Configure Sentry alerts:

// sentry.server.config.ts
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.VERCEL_ENV || 'production',
  tracesSampleRate: 0.1, // Lower in production
  beforeSend(event, hint) {
    // Filter out noise
    if (event.exception) {
      // Send to alerting channel
    }
    return event;
  },
});

CI/CD Pipeline

Automatic Deployments

Vercel automatically deploys:

Production: Pushes to main branch
Preview: Pull requests and feature branches

Custom Build Process

Add vercel.json for custom configuration:

vercel.json

{
  "installCommand": "bun install",
  "buildCommand": "bun run build",
  "framework": "nextjs",
  "regions": ["iad1"],
  "env": {
    "NODE_VERSION": "20"
  }
}

Pre-deployment Checks

Create GitHub Actions workflow:

.github/workflows/ci.yml

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linter
        run: npm run lint
      
      - name: Type check
        run: npx tsc --noEmit
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build

Scaling Considerations

Database Scaling

Convex scales automatically, but consider:

Index optimization for large datasets
Query pagination for large result sets
Archiving old conversations/messages

Background Jobs

Trigger.dev handles scaling, but:

Set appropriate concurrency limits
Use queues for high-volume tasks
Monitor job execution times

Static Assets

Use Vercel’s CDN for static files
Optimize images with next/image
Implement lazy loading

API Rate Limits

Monitor and implement rate limiting:

AI API calls (OpenRouter/Cerebras)
Convex function calls
Trigger.dev job invocations

Rollback Strategy

Identify issue

Use Sentry and Vercel logs to diagnose the problem

Instant rollback

In Vercel dashboard:

Go to Deployments
Find last working deployment
Click ”…” → “Promote to Production”

Or revert Git commit

git revert HEAD
git push origin main

Verify rollback

Test critical functionality after rollback

Troubleshooting

Build failures

Issue: Build fails on VercelSolutions:

Check build logs in Vercel dashboard
Verify all environment variables are set
Test build locally: npm run build
Check Node.js version compatibility

Authentication errors

Issue: Users can’t sign inSolutions:

Verify Stack Auth production keys
Check allowed domains in Stack Auth dashboard
Ensure NEXT_PUBLIC_STACK_PUBLISHABLE_KEY is set
Check browser console for CORS errors

Database connection issues

Issue: Convex queries failSolutions:

Verify NEXT_PUBLIC_CONVEX_URL is correct
Check Convex deployment status
Ensure auth integration is configured
Test queries in Convex dashboard

Background jobs not running

Issue: Trigger.dev tasks don’t executeSolutions:

Verify TRIGGER_SECRET_KEY is set
Check task deployment: npx trigger.dev deploy
Monitor Trigger.dev dashboard for errors
Ensure webhook endpoints are accessible

Next Steps

Electron Deployment

Build and distribute desktop app

Error Tracking

Set up comprehensive error monitoring

Architecture

Understand the system design

Contributing

Contribute improvements

Development

Deployment

Advanced

Overview

Prerequisites

Vercel Account

Production Services

Deployment Steps

1. Prepare Convex Production Database

2. Configure Trigger.dev Production

3. Set Up Stack Auth Production

4. Deploy to Vercel

5. Environment Variables

6. Configure Custom Domain (Optional)

Post-Deployment

Verify Deployment

Monitor Performance

Vercel Analytics

Sentry

Convex Dashboard

Trigger.dev

Set Up Monitoring

CI/CD Pipeline

Automatic Deployments

Custom Build Process

Pre-deployment Checks

Scaling Considerations

Rollback Strategy

Troubleshooting

Next Steps

Electron Deployment

Error Tracking

Architecture

Contributing

Build docs developers (and LLMs) love

Development

Deployment

Advanced

​Overview

​Prerequisites

Vercel Account

Production Services

​Deployment Steps

​1. Prepare Convex Production Database

​2. Configure Trigger.dev Production

​3. Set Up Stack Auth Production

​4. Deploy to Vercel

​5. Environment Variables

​6. Configure Custom Domain (Optional)

​Post-Deployment

​Verify Deployment

​Monitor Performance

Vercel Analytics

Sentry

Convex Dashboard

Trigger.dev

​Set Up Monitoring

​CI/CD Pipeline

​Automatic Deployments

​Custom Build Process

​Pre-deployment Checks

​Scaling Considerations

​Rollback Strategy

​Troubleshooting

​Next Steps

Electron Deployment

Error Tracking

Architecture

Contributing

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Steps

1. Prepare Convex Production Database

2. Configure Trigger.dev Production

3. Set Up Stack Auth Production

4. Deploy to Vercel

5. Environment Variables

6. Configure Custom Domain (Optional)

Post-Deployment

Verify Deployment

Monitor Performance

Set Up Monitoring

CI/CD Pipeline

Automatic Deployments

Custom Build Process

Pre-deployment Checks

Scaling Considerations

Rollback Strategy

Troubleshooting

Next Steps