Deployment Guide

Overview

This guide covers deploying Agora to production, with a focus on Vercel deployment (the recommended platform), along with environment setup, database migrations, and monitoring configuration.

Agora is built on Next.js 14 and optimized for deployment on Vercel, the platform from the creators of Next.js.

Pre-Deployment Checklist

Before deploying, ensure you have:

Production environment variables

Prepare all required environment variables for production. See the Configuration Guide for the complete list.

Minimum required variables:

NEXT_PUBLIC_AGORA_INSTANCE_NAME
NEXT_PUBLIC_AGORA_INSTANCE_TOKEN
NEXT_PUBLIC_AGORA_ENV=prod
NEXT_PUBLIC_ALCHEMY_ID
SERVERSIDE_ALCHEMY_ID_PROD
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID
READ_WRITE_WEB2_DATABASE_URL_PROD
READ_ONLY_WEB3_DATABASE_URL_PROD
JWT_SECRET
NEXT_PUBLIC_AGORA_BASE_URL

Production database

Set up production PostgreSQL databases:

Web2 database for user-generated content
Web3 database for blockchain indexed data

Ensure proper backups and replication are configured.

Code quality checks

Run all quality checks before deploying:

npm run prettier-src
npm run lint
npm run typecheck
npm test

Build verification

Test the production build locally:

npm run build
npm start

Verify the application runs correctly on http://localhost:3000

Vercel Deployment

Vercel is the recommended deployment platform for Agora.

Initial Setup

Create Vercel account

Install Vercel CLI (Optional)

For command-line deployment:

npm install -g vercel

Connect repository

Option 1: Via Vercel Dashboard

Go to Vercel Dashboard
Click “Import Project”
Select your Git provider (GitHub, GitLab, Bitbucket)
Choose your Agora repository
Vercel will auto-detect Next.js configuration

Option 2: Via CLI

cd agora-next
vercel

Follow the prompts to link your repository.

Configure environment variables

In the Vercel dashboard:

Go to Project Settings → Environment Variables
Add all production environment variables
Set the environment scope:
- Production for production deployments
- Preview for pull request previews
- Development for local development

Use different values for Preview and Production environments to test safely.

Critical variables to set:

NEXT_PUBLIC_AGORA_ENV=prod
NEXT_PUBLIC_AGORA_INSTANCE_NAME=ens
NEXT_PUBLIC_AGORA_INSTANCE_TOKEN=ENS
NEXT_PUBLIC_AGORA_BASE_URL=https://your-domain.com
# ... add all other required variables

Configure build settings

Vercel auto-detects Next.js projects, but verify:

Framework Preset: Next.js
Build Command: npm run build (or next build)
Output Directory: .next
Install Command: npm install
Development Command: npm run dev

These are usually auto-configured correctly for Next.js projects.

Deploy

Automatic deployment:

Push to your main branch
Vercel automatically builds and deploys

Manual deployment via CLI:

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Custom Domain Setup

Add domain in Vercel

Go to Project Settings → Domains
Click “Add Domain”
Enter your domain (e.g., vote.ens.domains)

Configure DNS

Vercel will provide DNS configuration:Option 1: Using Vercel nameservers (recommended)

Point your domain’s nameservers to Vercel
Vercel manages SSL automatically

Option 2: Using CNAME record

Type: CNAME
Name: @ (or subdomain)
Value: cname.vercel-dns.com

Option 3: Using A record

Type: A
Name: @
Value: 76.76.21.21

Wait for SSL provisioning

Vercel automatically provisions SSL certificates. This usually takes a few minutes.

Your site will be available at https://your-domain.com once SSL is active.

Update environment variables

Update NEXT_PUBLIC_AGORA_BASE_URL to your custom domain:

NEXT_PUBLIC_AGORA_BASE_URL=https://vote.ens.domains

Redeploy for changes to take effect.

Automatic Vercel Environment Variables

Vercel automatically sets these variables (used for monitoring):

VERCEL_ENV - Environment type (production/preview/development)
VERCEL_URL - Deployment URL
VERCEL_REGION - Deployment region
VERCEL_GIT_COMMIT_SHA - Git commit SHA
VERCEL_BRANCH_URL - Branch-specific URL

These are used by Agora’s OpenTelemetry integration for tracing. Do not override them.

Environment Setup for Production

Database Configuration

Provision production databases

Set up two PostgreSQL databases:Recommended providers:

Supabase - Postgres with built-in features
Neon - Serverless Postgres
AWS RDS - Managed PostgreSQL
Google Cloud SQL - Managed databases

Configuration:

Web2 database: User content, requires read-write access
Web3 database: Indexed blockchain data, read-only access

Set connection URLs

Add database URLs to Vercel environment variables:

READ_WRITE_WEB2_DATABASE_URL_PROD=postgres://user:pass@host:5432/agora_web2_prod
READ_ONLY_WEB3_DATABASE_URL_PROD=postgres://user:pass@host:5432/agora_web3_prod

Use connection pooling for production (e.g., PgBouncer) to handle high traffic.

Enable SSL connections

Ensure SSL is enabled for database connections:

# Add SSL parameters to connection string
postgres://user:pass@host:5432/db?sslmode=require

Configure connection pooling

For serverless environments, use connection pooling:

Supabase: Use the connection pooler endpoint
Neon: Built-in connection pooling
PgBouncer: Set up separately for other providers

Update Prisma configuration in prisma/schema.prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

API Keys and Services

Alchemy Configuration

Set up separate Alchemy API keys:

# Client-side key (domain-whitelisted)
NEXT_PUBLIC_ALCHEMY_ID=your_client_key

# Server-side key (no restrictions needed)
SERVERSIDE_ALCHEMY_ID_PROD=your_server_key

In Alchemy Dashboard:

Create two API keys (client and server)
For client key: Add your domain to whitelist
For server key: No restrictions needed
Monitor usage to stay within limits

WalletConnect Setup

Configure WalletConnect for production:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

In WalletConnect Cloud:

Create a production project
Add your domain to allowed origins
Copy the Project ID

External Services

Configure optional external services:Tenderly (Transaction Simulation):

TENDERLY_USER=your_username
TENDERLY_PROJECT=your_project
TENDERLY_ACCESS_KEY=your_access_key

Pinata (IPFS):

PINATA_JWT=your_pinata_jwt

Etherscan:

NEXT_PUBLIC_ETHERSCAN_API_KEY=your_etherscan_key

Security Keys

Generate and securely store sensitive keys:JWT Secret:

# Generate a strong random secret
openssl rand -base64 64
JWT_SECRET=<generated_secret>

Gas Sponsor Private Key:

GAS_SPONSOR_PK=your_private_key_without_0x

EAS Sender Private Key:

EAS_SENDER_PRIVATE_KEY=your_eas_private_key

Store private keys in Vercel’s encrypted environment variables. Never commit to Git.

Database Migrations

The database schema is managed in a separate repository.

Migration Process

Pull latest schema

On your local machine:

npx prisma db pull

This introspects the production database and updates your Prisma schema.

Generate Prisma Client

Generate the updated client:

npx prisma generate

Test locally

Test the changes locally before deploying:

npm run dev

Deploy to production

Commit the updated schema and push:

git add prisma/schema.prisma
git commit -m "Update Prisma schema"
git push origin main

Vercel will automatically rebuild with the new schema.

For more details on database management, see the Database Manual.

Monitoring and Observability

Agora includes built-in OpenTelemetry (OTel) integration for monitoring.

OpenTelemetry Setup

OpenTelemetry is automatically configured when deploying to Vercel. Configuration file: instrumentation.ts (or instrumentation.js)

import { registerOTel } from '@vercel/otel';

export function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    registerOTel('agora-next');
  }
}

The instrumentation file is automatically loaded by Next.js 14+ when present in the project root.

DataDog Integration

Optionally integrate with DataDog for metrics and monitoring:

Get DataDog credentials

API Key
Application Key

Set environment variables

ENABLE_DD_METRICS=true
DD_API_KEY=your_datadog_api_key
DD_APP_KEY=your_datadog_app_key

Configure DataDog agent

DataDog will automatically collect:

Application metrics
Error tracking
Performance monitoring
Custom metrics from your application

Vercel Analytics

Agora includes Vercel Analytics and Speed Insights:

import { Analytics } from '@vercel/analytics/react';
import { SpeedInsights } from '@vercel/speed-insights/next';

<Analytics />
<SpeedInsights />

Automatic metrics:

Page views
Core Web Vitals (LCP, FID, CLS)
User interactions
Performance data

View analytics in the Vercel dashboard under Analytics and Speed Insights.

Monitoring Best Practices

Monitor these key metrics:

Database Performance
- Query response times
- Connection pool usage
- Slow query logs
API Performance
- Response times for /api/* routes
- Error rates
- Rate limiting metrics
Blockchain RPC
- Alchemy API usage and rate limits
- RPC call success rates
- Block synchronization lag
User Experience
- Core Web Vitals
- Page load times
- Error tracking
Security
- Failed authentication attempts
- Suspicious activity patterns
- API key usage anomalies

Production Optimization

Performance Optimization

Enable caching

Configure caching for static assets and API responses:In next.config.js:

module.exports = {
  // Enable static page generation
  output: 'standalone',
  
  // Configure caching headers
  async headers() {
    return [
      {
        source: '/assets/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=31536000, immutable',
          },
        ],
      },
    ];
  },
};

Optimize images

Use Next.js Image optimization:

import Image from 'next/image';

<Image
  src="/logo.png"
  width={200}
  height={100}
  alt="Logo"
  priority // for above-the-fold images
/>

Vercel automatically optimizes images on-demand.

Database connection pooling

Use connection pooling to prevent connection exhaustion:

Configure connection_limit in Prisma
Use PgBouncer or Supabase Pooler
Monitor active connections

Bundle size optimization

Analyze and optimize bundle size:

npm run analyze

This uses @next/bundle-analyzer to visualize bundle composition.Optimization techniques:

Dynamic imports for large components
Tree shaking unused code
Minimize third-party dependencies

Security Hardening

Set security headers

Configure security headers in next.config.js:

async headers() {
  return [
    {
      source: '/:path*',
      headers: [
        { key: 'X-DNS-Prefetch-Control', value: 'on' },
        { key: 'Strict-Transport-Security', value: 'max-age=63072000' },
        { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
        { key: 'X-Content-Type-Options', value: 'nosniff' },
        { key: 'Referrer-Policy', value: 'origin-when-cross-origin' },
      ],
    },
  ];
}

Rotate secrets regularly

Establish a secret rotation schedule:

JWT secrets: Every 90 days
Private keys: Every 180 days
API keys: Monitor and rotate if compromised

Enable rate limiting

Implement rate limiting for API routes (if not already configured).

Monitor for vulnerabilities

Regularly update dependencies:

npm audit
npm update

Deployment Checklist

Before going live, verify:

Rollback Strategy

Always have a rollback plan in case of deployment issues.

Vercel Rollback

Via Vercel Dashboard

Go to Deployments
Find the last working deployment
Click ⋯ → Promote to Production

Via CLI

# List recent deployments
vercel ls

# Promote a specific deployment
vercel promote <deployment-url>

Verify rollback

Test the rolled-back deployment to ensure it’s working correctly.

Troubleshooting

Build fails on Vercel

Common causes:

Missing environment variables
TypeScript errors
Dependency issues

Solution:

Check build logs in Vercel dashboard
Run npm run build locally to reproduce
Fix errors and redeploy

Database connection fails

Verify:

Database is accessible from Vercel’s IP ranges
Connection strings are correct
SSL is configured if required
Connection pool limits are not exceeded

Test connection:

psql "postgresql://user:pass@host:5432/db?sslmode=require"

Environment variables not updating

Redeploy after changing environment variables:

Update variables in Vercel dashboard
Go to Deployments
Click Redeploy on the latest deployment

Slow API responses

Diagnose:

Check database query performance
Monitor RPC call times (Alchemy)
Review Vercel function logs

Optimize:

Add database indexes
Implement caching (Redis/Upstash)
Use connection pooling

Next Steps

Architecture

Understand the system architecture

Customization

Customize your deployed instance

Configuration

Environment variables and settings

Setup Guide

Initial setup and prerequisites

Get Started

Core Features

Advanced Features

Guides

Deployment Guide

Overview

Pre-Deployment Checklist

Vercel Deployment

Initial Setup

Custom Domain Setup

Automatic Vercel Environment Variables

Environment Setup for Production

Database Configuration

API Keys and Services

Database Migrations

Migration Process

Monitoring and Observability

OpenTelemetry Setup

DataDog Integration

Vercel Analytics

Monitoring Best Practices

Production Optimization

Performance Optimization

Security Hardening

Deployment Checklist

Rollback Strategy

Vercel Rollback

Troubleshooting

Next Steps

Architecture

Customization

Configuration

Setup Guide

Get Started

Core Features

Advanced Features

Guides

Documentation Index

​Overview

​Pre-Deployment Checklist

​Vercel Deployment

​Initial Setup

​Custom Domain Setup

​Automatic Vercel Environment Variables

​Environment Setup for Production

​Database Configuration

​API Keys and Services

​Database Migrations

​Migration Process

​Monitoring and Observability

​OpenTelemetry Setup

​DataDog Integration

​Vercel Analytics

​Monitoring Best Practices

​Production Optimization

​Performance Optimization

​Security Hardening

​Deployment Checklist

​Rollback Strategy

​Vercel Rollback

​Troubleshooting

​Next Steps

Architecture

Customization

Configuration

Setup Guide

Overview

Pre-Deployment Checklist

Vercel Deployment

Initial Setup

Custom Domain Setup

Automatic Vercel Environment Variables

Environment Setup for Production

Database Configuration

API Keys and Services

Database Migrations

Migration Process

Monitoring and Observability

OpenTelemetry Setup

DataDog Integration

Vercel Analytics

Monitoring Best Practices

Production Optimization

Performance Optimization

Security Hardening

Deployment Checklist

Rollback Strategy

Vercel Rollback

Troubleshooting

Next Steps