Deployment Guide

Overview

jøsh is designed to be deployed on Vercel, taking advantage of serverless functions, edge networking, and seamless Next.js integration.

Prerequisites

Before deploying, ensure you have:

A Vercel account (sign up here)
A PostgreSQL database (Supabase, Neon, Railway, etc.)
All required environment variables configured
Git repository connected to Vercel

Deployment Methods

Method 1: Vercel Git Integration (Recommended)

Connect your repository

Log in to Vercel
Click “Add New Project”
Import your Git repository (GitHub, GitLab, or Bitbucket)
Select the repository containing jøsh

Configure project settings

Vercel will auto-detect Next.js. Verify the following settings:

Setting	Value
Framework Preset	Next.js
Build Command	`npm run vercel-build`
Output Directory	`.next`
Install Command	`npm install`

The vercel-build script runs prisma generate && next build to ensure Prisma client is generated before building.

Add environment variables

In the Vercel project settings, navigate to Environment Variables and add:

DATABASE_URL
DIRECT_URL
AI_GATEWAY_API_KEY
SURGE_API_KEY
SURGE_ACCOUNT_ID
SURGE_WEBHOOK_SECRET
SUPABASE_PROJECT_URL
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_UPLOAD_BUCKET
MUTUAL_INTERNAL_API_KEY

Use production credentials, not development values. See Environment Variables for details.

Deploy

Click “Deploy” to trigger your first deployment.Vercel will:

Clone your repository
Install dependencies
Generate Prisma client
Build the Next.js application
Deploy to production

Method 2: Vercel CLI

Deploy directly from your local machine using the Vercel CLI.

Install Vercel CLI

npm install -g vercel

vercel login

Deploy to production

From the project root:

vercel --prod

Follow the prompts to configure your deployment.

Database Migrations

Initial Setup

After your first deployment, run database migrations:

Generate Prisma client locally

npm run db:generate

Apply migrations to production database

Ensure your DATABASE_URL points to your production database before running migrations.

npx prisma migrate deploy

This applies all pending migrations without creating new ones.

Subsequent Migrations

When updating the database schema:

Development: Create and test migrations locally
```
npm run db:migrate
```
Production: Deploy schema changes
```
npx prisma migrate deploy
```

For zero-downtime deployments with schema changes, consider using Prisma’s expand/contract pattern.

Build Configuration

Custom Build Script

The vercel-build script ensures Prisma client generation before build:

package.json

{
  "scripts": {
    "vercel-build": "prisma generate && next build"
  }
}

This prevents “Prisma client not found” errors during deployment.

PostHog Integration

The application includes PostHog analytics with custom rewrites for first-party data collection:

next.config.ts

async rewrites() {
  return [
    {
      source: "/ingest/static/:path*",
      destination: "https://us-assets.i.posthog.com/static/:path*",
    },
    {
      source: "/ingest/:path*",
      destination: "https://us.i.posthog.com/:path*",
    },
  ];
}

These rewrites proxy PostHog requests through your domain, improving data collection reliability.

Environment-Specific Configuration

Vercel supports multiple environments:

Production: Deployed from main/master branch
Preview: Deployed from pull requests and other branches
Development: Local environment

Configure environment variables for each environment in Vercel dashboard:

Environment	Use Case
Production	Live production deployment
Preview	Staging/testing for pull requests
Development	Local development (use `.env` file)

Monitoring & Debugging

Vercel Logs

View deployment logs and runtime errors:

Navigate to your project in Vercel
Click “Deployments”
Select a deployment
View Build Logs and Function Logs

Common Deployment Issues

Prisma Client Not Found

Cause: Prisma client not generated during build Solution: Ensure vercel-build script includes prisma generate

"vercel-build": "prisma generate && next build"

Database Connection Errors

Cause: Incorrect DATABASE_URL or connection pooling issues Solution:

Verify DATABASE_URL format
Use connection pooling URL for DATABASE_URL
Use direct connection URL for DIRECT_URL

Environment Variables Not Available

Cause: Variables not set in Vercel dashboard Solution: Add missing variables in Project Settings → Environment Variables

After adding environment variables, redeploy your application to apply changes.

Continuous Deployment

With Vercel Git integration, deployments are automatic:

Push to branch → Creates preview deployment
Merge to main → Deploys to production
Open pull request → Generates preview URL

Deployment Protection

Enable deployment protection for production:

Go to Project Settings → Deployment Protection
Enable Vercel Authentication for production
Restrict access to team members only

Performance Optimization

Image Optimization

jøsh uses Next.js Image optimization with configured remote patterns:

next.config.ts

images: {
  remotePatterns: [
    {
      protocol: "https",
      hostname: "lh3.googleusercontent.com",
      port: "",
      pathname: "/d/**",
    },
  ],
}

Caching Strategy

Vercel automatically caches:

Static assets (images, CSS, JS)
API responses with proper cache headers
Edge functions for low-latency responses

Rollback & Version Control

Rollback to a previous deployment:

Navigate to Deployments in Vercel
Find the stable deployment
Click ”…” → “Promote to Production”

Instant rollback allows you to revert to any previous deployment without redeploying code.

Custom Domains

Add a custom domain to your Vercel deployment:

Add domain in Vercel

Go to Project Settings → Domains
Enter your domain name
Click “Add”

Configure DNS

Add the DNS records provided by Vercel:

Type	Name	Value
A	@	76.76.21.21
CNAME	www	cname.vercel-dns.com

Verify domain

Vercel will automatically verify and provision SSL certificates.

Webhooks & API Routes

Surge SMS Webhook

Configure your Surge webhook URL to point to your production deployment:

https://your-domain.vercel.app/api/tpo/webhook

Update webhook URLs in your Surge SMS dashboard after each domain change.

Security Considerations

Environment variable security

Use Vercel’s encrypted environment variables
Never commit secrets to Git
Rotate API keys regularly

Webhook validation

Ensure SURGE_WEBHOOK_SECRET is set to validate incoming webhooks.

Database access

Restrict database access to Vercel IP ranges if possible
Use SSL/TLS for database connections
Enable connection pooling for serverless functions

Next Steps

Local Setup

Set up jøsh locally for development

Environment Variables

Configure required environment variables

Architecture

Core Systems

Development

Deployment Guide

Overview

Prerequisites

Deployment Methods

Method 1: Vercel Git Integration (Recommended)

Method 2: Vercel CLI

Database Migrations

Initial Setup

Subsequent Migrations

Build Configuration

Custom Build Script

PostHog Integration

Environment-Specific Configuration

Monitoring & Debugging

Vercel Logs

Common Deployment Issues

Prisma Client Not Found

Database Connection Errors

Environment Variables Not Available

Continuous Deployment

Deployment Protection

Performance Optimization

Image Optimization

Caching Strategy

Rollback & Version Control

Custom Domains

Webhooks & API Routes

Surge SMS Webhook

Security Considerations

Next Steps

Local Setup

Environment Variables

Build docs developers (and LLMs) love

Architecture

Core Systems

Development

​Overview

​Prerequisites

​Deployment Methods

​Method 1: Vercel Git Integration (Recommended)

​Method 2: Vercel CLI

​Database Migrations

​Initial Setup

​Subsequent Migrations

​Build Configuration

​Custom Build Script

​PostHog Integration

​Environment-Specific Configuration

​Monitoring & Debugging

​Vercel Logs

​Common Deployment Issues

​Prisma Client Not Found

​Database Connection Errors

​Environment Variables Not Available

​Continuous Deployment

​Deployment Protection

​Performance Optimization

​Image Optimization

​Caching Strategy

​Rollback & Version Control

​Custom Domains

​Webhooks & API Routes

​Surge SMS Webhook

​Security Considerations

​Next Steps

Local Setup

Environment Variables

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Methods

Method 1: Vercel Git Integration (Recommended)

Method 2: Vercel CLI

Database Migrations

Initial Setup

Subsequent Migrations

Build Configuration

Custom Build Script

PostHog Integration

Environment-Specific Configuration

Monitoring & Debugging

Vercel Logs

Common Deployment Issues

Prisma Client Not Found

Database Connection Errors

Environment Variables Not Available

Continuous Deployment

Deployment Protection

Performance Optimization

Image Optimization

Caching Strategy

Rollback & Version Control

Custom Domains

Webhooks & API Routes

Surge SMS Webhook

Security Considerations

Next Steps