Skip to main content

​
Overview

Resonance is a full-stack Next.js application that requires several cloud services to operate. This guide covers the prerequisites and architecture considerations for deploying to production.

​
Architecture

Resonance consists of three main components:

Next.js App

The web application (SSR + API routes)

PostgreSQL Database

Stores voices, generations, and metadata

Modal GPU Inference

Serverless TTS engine with voice cloning

​
Prerequisites

​
Required Services

Before deploying, you’ll need accounts and configuration for:
1

Node.js Runtime

Node.js 20.9 or later is required. The application uses Next.js 16 with React 19 and server components.
2

PostgreSQL Database

A managed PostgreSQL database with the connection string ready.Recommended: Prisma Postgres for built-in connection pooling.Alternatives: Any managed Postgres provider (Railway, Supabase, Neon, etc.)
3

Cloudflare R2

S3-compatible object storage for audio files.Required credentials:
  • Account ID
  • Access Key ID
  • Secret Access Key
  • Bucket name
R2 offers 10GB free storage and zero egress fees, making it ideal for audio hosting.
4

Modal Account

Serverless GPU platform for the TTS inference engine.What you need:
  • Modal CLI installed (pip install modal)
  • Modal account with billing enabled
  • Three secrets configured (see Self-Hosting)
Modal charges per GPU-second. The A10G GPU costs ~$0.0008/second. Budget accordingly.
5

Clerk Authentication

User authentication with Organizations support.Configuration:
  • Enable Organizations in your Clerk dashboard
  • Set up sign-in/sign-up pages
  • Configure allowed authentication methods
  • Copy API keys to environment variables
6

Polar Billing (Optional)

Usage-based billing and metering.Required for production:
  • Polar account with API token
  • Product ID for pay-as-you-go pricing
  • Webhook endpoint configured
Use POLAR_SERVER="sandbox" for testing with card 4242 4242 4242 4242.

​
Environment Variables

The application validates environment variables using @t3-oss/env-nextjs. All required variables must be present at build time. 
# Database
DATABASE_URL="postgresql://..."

# Chatterbox TTS (Modal)
CHATTERBOX_API_URL="https://your-modal-endpoint.modal.run"
CHATTERBOX_API_KEY="your-api-key"

# Clerk Authentication
CLERK_SECRET_KEY="sk_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..."
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"

# Cloudflare R2
R2_ACCOUNT_ID="your-account-id"
R2_ACCESS_KEY_ID="your-access-key"
R2_SECRET_ACCESS_KEY="your-secret-key"
R2_BUCKET_NAME="your-bucket-name"

# Polar Billing
POLAR_ACCESS_TOKEN="your-polar-token"
POLAR_SERVER="production"
POLAR_PRODUCT_ID="your-product-id"

# Application
APP_URL="https://yourdomain.com"
Missing or invalid environment variables will cause the build to fail. The validation schema is defined in src/lib/env.ts:5-20.

​
Build Requirements

​
Build Process

The application uses Next.js production build with these characteristics:
  1. Dependency installation - npm install runs postinstall script which generates Prisma client
  2. Environment validation - All required env vars are validated at build time
  3. Next.js build - Creates optimized production bundle with SSR
  4. Sentry integration - Uploads source maps if CI env var is set
npm install
npm run build
The next.config.ts includes:
  • Sentry integration for error monitoring
  • Proxy max body size set to 20MB for audio uploads
  • Disabled dev indicators for cleaner production UI
  • Source map uploads (silent unless in CI)
  • Automatic Vercel Cron Monitors support

​
Database Migrations

Prisma migrations must be applied before the application starts. 
# Deploy pending migrations
npx prisma migrate deploy

# Seed system voices (first deployment only)
npx prisma db seed
The seed script uploads 20 system voice WAV files to R2 and creates database entries. This only needs to run once per environment.

​
Deployment Checklist

1

Service Setup

  • PostgreSQL database provisioned
  • Cloudflare R2 bucket created
  • Clerk application configured
  • Modal secrets created
  • Polar product configured (if using billing)
2

Deploy Modal TTS

  • Update chatterbox_tts.py with R2 credentials
  • Run modal deploy chatterbox_tts.py
  • Test endpoint with curl
  • Copy endpoint URL to CHATTERBOX_API_URL
3

Configure Environment

  • All required env vars set on hosting platform
  • Production URLs configured
  • Secrets properly secured (not committed)
4

Database Setup

  • Run npx prisma migrate deploy
  • Run npx prisma db seed
  • Verify 20 system voices created
5

Deploy Application

  • Push code to hosting platform
  • Build succeeds with no errors
  • Application starts and responds to health checks
6

Post-Deployment

  • Test authentication flow
  • Generate sample TTS
  • Verify audio playback
  • Check error monitoring (Sentry)

​
Next Steps

Self-Hosting Guide

Step-by-step deployment instructions for Railway and Docker

Troubleshooting

Common issues and solutions for Modal cold starts, R2, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us