Deployment Guide

Overview

This guide covers deploying the Openlane Console to production, including environment variable configuration, build optimization, and deployment best practices.

Never commit environment files (.env, .env.local, etc.) to version control. Use secure secret management services in production.

Prerequisites

Before deploying, ensure you have:

Node.js: Version 24.14.x (required)
Package Manager: Bun 1.2.16+ (recommended) or pnpm/npm
Database: PostgreSQL instance for backend API
Object Storage: Cloudflare R2 or S3-compatible storage for file uploads
Domain: Custom domain with SSL certificate
API Endpoint: Backend GraphQL API deployed and accessible

Environment Variables

The Console requires various environment variables for different features. These are defined in /turbo.json for build-time validation.

Core Configuration

# Node environment
NODE_ENV=production

# API Configuration
API_REST_URL=https://api.yourdomain.com
NEXT_PUBLIC_OPENLANE_URL=https://console.yourdomain.com
NEXT_PUBLIC_API_GQL_URL=https://api.yourdomain.com/graphql

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Keep sensitive values in server-side variables only.

Authentication Settings

OAuth Providers
Session Configuration
Domain Restrictions
reCAPTCHA

# GitHub OAuth
AUTH_GITHUB_ID=your_github_client_id
AUTH_GITHUB_SECRET=your_github_client_secret

# Google OAuth
AUTH_GOOGLE_ID=your_google_client_id.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=your_google_client_secret

Setup Instructions:

GitHub OAuth App

Go to GitHub Developer Settings
Create new OAuth App

Set Authorization callback URL:

https://console.yourdomain.com/api/auth/callback/github

Copy Client ID and Client Secret

Google OAuth Client

Go to Google Cloud Console
Create OAuth 2.0 Client ID

Add authorized redirect URI:

https://console.yourdomain.com/api/auth/callback/google

Copy Client ID and Client Secret

# Session cookie name (optional, defaults to next-auth.session-token)
SESSION_COOKIE_NAME=openlane-session

# Cookie domain for subdomain sharing (optional)
SESSION_COOKIE_DOMAIN=.yourdomain.com

# Session max age in seconds (optional, defaults to 30 days)
SESSION_NEXAUTH_MAX_AGE=2592000

Cookie Domain Configuration

# Restrict signups to specific email domains (optional)
NEXT_PUBLIC_ALLOWED_LOGIN_DOMAINS=yourcompany.com,partner.com

Comma-separated list of allowed email domains. If set, users can only sign up with emails from these domains.

# Google reCAPTCHA v3 secret key (optional but recommended)
RECAPTCHA_SECRET_KEY=your_recaptcha_v3_secret_key

Setup:

Create reCAPTCHA v3 site at https://www.google.com/recaptcha/admin
Add your domain
Copy the secret key
Add the site key to your app’s HTML

Integration Settings

Billing (Stripe)
Customer Support (DevRev)
Analytics (Pirsch)
API Tokens

# Stripe secret key for billing integration
STRIPE_SECRET_KEY=sk_live_...

Required for:

Subscription management
Invoice generation
Payment processing
Usage tracking

Use Stripe test mode keys for development and live mode keys for production.

# DevRev authentication token for customer support chat
DEVREV_AAT=your_devrev_app_access_token

Enables in-app customer support chat widget.

# Pirsch Analytics for trust center (privacy-focused)
PIRSCH_SECRET=your_pirsch_secret
PIRSCH_CLIENT_ID=your_pirsch_client_id

Used for privacy-friendly analytics on public trust center pages.

# Write token for API operations (e.g., subscriber management)
OPENLANE_API_WRITE_TOKEN=your_write_token

Used for server-side API operations that require write access.

AI/ML Settings (Optional)

Google Vertex AI
Amazon Bedrock

# Enable AI-powered suggestions
NEXT_PUBLIC_AI_SUGGESTIONS_ENABLED=true

# Google AI Configuration
GOOGLE_AI_PROJECT_ID=your-gcp-project-id
GOOGLE_AI_REGION=us-central1
GOOGLE_AI_MODEL_NAME=gemini-pro
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key

# Service account for Vertex AI (base64 encoded JSON)
GOOGLE_SERVICE_ACCOUNT_KEY_B64=base64_encoded_service_account_json

# RAG Corpus for enhanced context
GOOGLE_RAG_CORPUS_ID=your-corpus-id

# GCS bucket for AI logs
GCS_LOG_BUCKET=your-logs-bucket

Setup Service Account:

# Encode service account JSON to base64
cat service-account.json | base64 -w 0 > service-account-b64.txt

# AWS region for Bedrock (optional, for development/testing)
AWS_REGION=us-east-1

The Console includes Amazon Bedrock SDK (@ai-sdk/amazon-bedrock) but it’s primarily used for development/testing. Production uses Google Vertex AI.

Feature Flags

# Enable subscription plan features (optional)
NEXT_PUBLIC_ENABLE_PLAN=true

# Google Maps API for location features (optional)
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-google-maps-api-key

# Custom domain CNAME value for trust center (optional)
NEXT_PUBLIC_CUSTOMDOMAIN_CNAME=trust.yourdomain.com.cdn.cloudflare.net

Build Configuration

The Console uses Next.js with custom build settings in next.config.mjs:

const nextConfig = {
  reactStrictMode: true,
  
  // Transpile monorepo packages
  transpilePackages: [
    '@repo/dally',
    '@repo/ui',
    '@repo/codegen',
    'survey-core',
    'survey-react-ui'
  ],
  
  // Optimize for production
  experimental: {
    webpackMemoryOptimizations: false,
  },
  
  // Redirects
  async redirects() {
    return [
      {
        source: '/tasks',
        destination: '/automation/tasks',
        permanent: true,
      },
    ]
  },
  
  // Image optimization for Cloudflare R2
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '*.r2.cloudflarestorage.com',
        pathname: '/**',
      },
    ],
  },
}

Build and Deploy

Local Build

Install Dependencies

pnpm install

Build Application

# From monorepo root
pnpm --filter console build

# Or using task runner
task build:console

This creates an optimized production build in .next/ directory.

Test Production Build

pnpm --filter console start

# Or
task start:console

Runs the production server on port 3001.

Docker Deployment

Create a Dockerfile for containerized deployment:

FROM node:20-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

# Copy package files
COPY package.json pnpm-lock.yaml ./
COPY apps/console/package.json ./apps/console/

# Install dependencies
RUN pnpm install --frozen-lockfile

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Build console app
ENV NEXT_TELEMETRY_DISABLED 1
RUN pnpm --filter console build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/apps/console/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/apps/console/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/apps/console/.next/static ./.next/static

USER nextjs

EXPOSE 3001

ENV PORT 3001

CMD ["node", "server.js"]

Build and run:

docker build -t openlane-console .
docker run -p 3001:3001 --env-file .env.production openlane-console

Vercel Deployment

Install Vercel CLI

pnpm install -g vercel

Configure Project

Create vercel.json in console directory:

{
  "buildCommand": "pnpm build",
  "devCommand": "pnpm dev",
  "installCommand": "pnpm install",
  "framework": "nextjs",
  "outputDirectory": ".next"
}

Set Environment Variables

In Vercel dashboard:

Go to Project Settings → Environment Variables
Add all required environment variables
Set appropriate environments (Production, Preview, Development)

Deploy

vercel --prod

Platform-Specific Deployments

AWS (ECS/Fargate)
Google Cloud (Cloud Run)
Azure (App Service)
Self-Hosted

Build Docker image
Push to ECR
Create ECS task definition
Configure ALB with SSL certificate
Set environment variables in task definition
Deploy ECS service

# Build and push to GCR
gcloud builds submit --tag gcr.io/PROJECT_ID/openlane-console

# Deploy to Cloud Run
gcloud run deploy openlane-console \
  --image gcr.io/PROJECT_ID/openlane-console \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="$(cat .env.production)"

Using PM2 for process management:

# Install PM2
npm install -g pm2

# Start application
pm2 start npm --name "openlane-console" -- start

# Configure startup script
pm2 startup
pm2 save

# Monitor
pm2 monit

Use Nginx as reverse proxy:

server {
  listen 443 ssl http2;
  server_name console.yourdomain.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}

Production Checklist

Security

All environment variables secured (use secret manager)
HTTPS enabled with valid SSL certificate
reCAPTCHA configured for login pages
OAuth callback URLs whitelisted
CORS configured properly in API
Rate limiting enabled on auth endpoints
Session secrets rotated
CSP headers configured

Performance

Next.js production build optimized
Image optimization configured
CDN configured for static assets
Database connection pooling enabled
Redis cache for session storage
Monitoring and APM configured
Load balancer health checks configured

Reliability

Database backups automated
Application logs aggregated
Error tracking configured (Sentry, etc.)
Uptime monitoring enabled
Auto-scaling policies configured
Disaster recovery plan documented
Fallback mechanisms tested

Compliance

Data encryption at rest and in transit
Audit logging enabled
Data retention policies configured
Privacy policy and ToS linked
GDPR compliance measures (if applicable)
SOC 2 controls implemented (if applicable)

Monitoring and Logging

Application Logs

# View logs in production
pm2 logs openlane-console

# Docker logs
docker logs -f container_id

# Cloud platform logs
vercel logs
gcloud logging read
aws logs tail

Health Checks

Implement health check endpoint:

// app/api/health/route.ts
export async function GET() {
  return Response.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    version: process.env.npm_package_version,
  })
}

Metrics

Track key metrics:

Response times
Error rates
Active sessions
API latency
Database query performance
Cache hit rates

Troubleshooting

Build Failures

Problem: Build fails with TypeScript errorsSolutions:

Ensure all dependencies are installed: pnpm install
Clear build cache: rm -rf .next
Check TypeScript version compatibility
Verify @repo/codegen is built first

Environment Variable Issues

Problem: Features not working due to missing env varsSolutions:

Check turbo.json for required variables
Verify variables are set in deployment platform
Restart application after updating env vars
Check browser console for NEXT_PUBLIC_ variable issues

Authentication Errors

Problem: OAuth or SSO not workingSolutions:

Verify callback URLs match exactly
Check OAuth credentials are for correct environment
Ensure HTTPS is enabled in production
Verify cookie domain settings
Check NextAuth configuration

Next Steps

Authentication

Configure auth providers and SSO

Monitoring

Set up monitoring and alerting

API Reference

Integrate with Console APIs

Troubleshooting

Common issues and solutions

Getting Started

Console

Component Library

Architecture

Development

Overview

Prerequisites

Environment Variables

Core Configuration

Authentication Settings

Integration Settings

AI/ML Settings (Optional)

Feature Flags

Build Configuration

Build and Deploy

Local Build

Docker Deployment

Vercel Deployment

Platform-Specific Deployments

Production Checklist

Monitoring and Logging

Application Logs

Health Checks

Metrics

Troubleshooting

Next Steps

Authentication

Monitoring

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Console

Component Library

Architecture

Development

​Overview

​Prerequisites

​Environment Variables

​Core Configuration

​Authentication Settings

​Integration Settings

​AI/ML Settings (Optional)

​Feature Flags

​Build Configuration

​Build and Deploy

​Local Build

​Docker Deployment

​Vercel Deployment

​Platform-Specific Deployments

​Production Checklist

​Monitoring and Logging

​Application Logs

​Health Checks

​Metrics

​Troubleshooting

​Next Steps

Authentication

Monitoring

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Overview

Prerequisites

Environment Variables

Core Configuration

Authentication Settings

Integration Settings

AI/ML Settings (Optional)

Feature Flags

Build Configuration

Build and Deploy

Local Build

Docker Deployment

Vercel Deployment

Platform-Specific Deployments

Production Checklist

Monitoring and Logging

Application Logs

Health Checks

Metrics

Troubleshooting

Next Steps