Deployment

Overview

This guide covers deploying Dub to various hosting platforms. Dub is a Next.js application that can be deployed to any platform that supports Node.js.

Deployment Requirements

System Requirements

Node.js 23.11.0 or higher
pnpm 9.15.9 or higher
2GB+ RAM (4GB+ recommended)
10GB+ disk space
MySQL 8.0+ database

External Services

Ensure you have the following services configured:

MySQL Database - See Database Setup
Tinybird - For analytics
Upstash Redis - For caching
Upstash QStash - For background jobs
Email Service - Resend or SMTP
Domain Provider - For custom domains

Vercel (Recommended)

Vercel is the recommended platform for deploying Next.js applications, including Dub.

Connect Repository

Push your Dub fork to GitHub
Go to vercel.com/new
Import your repository
Select the apps/web directory as the root

Configure Build Settings

Set the following build configuration:

Framework Preset: Next.js
Root Directory: apps/web
Build Command: cd ../.. && pnpm install && pnpm build --filter=web
Install Command: pnpm install
Output Directory: .next

Set Environment Variables

Add all required environment variables in Vercel project settings.See Environment Variables for the complete list.

You don’t need to set NEXTAUTH_URL on Vercel - it’s automatically detected.

Configure Domains

Add your custom domain in Vercel project settings
Update DNS records as instructed
Wait for SSL certificate provisioning

Enable Cron Jobs

Vercel automatically detects cron jobs from vercel.json.Verify cron jobs are enabled in Project Settings → Cron Jobs.

Cron jobs require a Vercel Pro plan or higher.

Deploy

Click “Deploy” and wait for the build to complete.Vercel will:

Install dependencies
Build the application
Deploy to production
Set up automatic deployments for future commits

Vercel Configuration

Dub includes a vercel.json configuration file:

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/domains/verify",
      "schedule": "0 * * * *"
    },
    {
      "path": "/api/cron/streams/update-workspace-clicks",
      "schedule": "* * * * *"
    },
    {
      "path": "/api/cron/usage",
      "schedule": "0 12 * * *"
    },
    {
      "path": "/api/cron/aggregate-clicks",
      "schedule": "0 0 * * *"
    }
  ],
  "functions": {
    "app/(ee)/api/cron/**/*.ts": {
      "maxDuration": 600
    }
  }
}

Railway

Railway provides simple deployment for full-stack applications.

Create New Project

Go to railway.app
Click “New Project”
Select “Deploy from GitHub repo”
Choose your Dub repository

Configure Service

Add the following configuration:

# Root directory
apps/web

# Build command
cd ../.. && pnpm install && pnpm build --filter=web

# Start command
cd apps/web && pnpm start

Set Environment Variables

Add all environment variables in Railway service settings.Railway provides a PostgreSQL database, but Dub requires MySQL. Add a MySQL service separately.

Add MySQL Service

Click “New” → “Database” → “Add MySQL”
Copy the connection string
Add as DATABASE_URL environment variable

Configure Domain

Go to service settings
Add custom domain
Update DNS records as instructed

Deploy

Railway automatically deploys when you push to your repository.

Railway Cron Jobs

Railway doesn’t have built-in cron support. Use external services:

Upstash QStash Schedules - Set up scheduled HTTP requests
Cron-job.org - Free cron job service
EasyCron - Paid cron service with monitoring

Configure scheduled requests to your cron endpoints with the CRON_SECRET header.

Docker Deployment

Deploy Dub using Docker for maximum control.

Create Dockerfile

Create Dockerfile in the repository root:

Dockerfile

FROM node:23-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@9.15.9 --activate

# Copy package files
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY apps/web/package.json ./apps/web/
COPY packages ./packages/

# Install dependencies
RUN pnpm install --frozen-lockfile

# Build the application
FROM base AS builder
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@9.15.9 --activate

COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Generate Prisma client
RUN pnpm --filter=@dub/prisma generate

# Build web app
RUN pnpm build --filter=web

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

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

# Copy built application
COPY --from=builder /app/apps/web/.next/standalone ./
COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=builder /app/apps/web/public ./apps/web/public

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "apps/web/server.js"]

Build and Run

# Build image
docker build -t dub .

# Run container
docker run -d \
  --name dub \
  -p 3000:3000 \
  --env-file .env \
  dub

Docker Compose

Create docker-compose.prod.yml:

docker-compose.prod.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      - mysql
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: dub
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped
    command:
      [
        "--max_connections=1000",
        "--default-authentication-plugin=mysql_native_password",
      ]

volumes:
  mysql_data:

Deploy:

docker compose -f docker-compose.prod.yml up -d

AWS EC2

Deploy to Amazon EC2 for full infrastructure control.

Launch EC2 Instance

Choose Ubuntu Server 22.04 LTS
Instance type: t3.medium or larger
Configure security group:
- Allow SSH (port 22)
- Allow HTTP (port 80)
- Allow HTTPS (port 443)

Install Dependencies

SSH into your instance and install Node.js:

# Install Node.js 23
curl -fsSL https://deb.nodesource.com/setup_23.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm@9.15.9

# Install Nginx
sudo apt-get install -y nginx

Clone and Build

# Clone repository
git clone https://github.com/yourusername/dub.git
cd dub

# Install dependencies
pnpm install

# Build application
cd apps/web
pnpm build

Configure Environment

# Create .env file
nano .env
# Add all environment variables

Set Up PM2

Use PM2 for process management:

# Install PM2
npm install -g pm2

# Start application
pm2 start pnpm --name "dub" -- start

# Set up auto-restart
pm2 startup
pm2 save

Configure Nginx

Create Nginx configuration:

/etc/nginx/sites-available/dub

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        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;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/dub /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Set Up SSL

Install Certbot for free SSL certificates:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

EC2 Cron Jobs

Set up cron jobs using crontab:

crontab -e

Add cron jobs:

# Domain verification - hourly
0 * * * * curl -H "Authorization: Bearer $CRON_SECRET" https://yourdomain.com/api/cron/domains/verify

# Update workspace clicks - every minute
* * * * * curl -H "Authorization: Bearer $CRON_SECRET" https://yourdomain.com/api/cron/streams/update-workspace-clicks

# Usage reporting - daily at noon
0 12 * * * curl -H "Authorization: Bearer $CRON_SECRET" https://yourdomain.com/api/cron/usage

# Aggregate clicks - daily at midnight
0 0 * * * curl -H "Authorization: Bearer $CRON_SECRET" https://yourdomain.com/api/cron/aggregate-clicks

DigitalOcean App Platform

Create New App

Go to DigitalOcean App Platform
Click “Create App”
Connect your GitHub repository

Configure Build

Source Directory: apps/web
Build Command: cd ../.. && pnpm install && pnpm build --filter=web
Run Command: cd apps/web && pnpm start

Add Database

Add a managed MySQL database in the same project.

Set Environment Variables

Add all required environment variables in app settings.

Deploy

Click “Deploy” and wait for the build to complete.

Render

Create Web Service

Go to render.com
Click “New” → “Web Service”
Connect your repository

Configure Service

Root Directory: apps/web
Build Command: cd ../.. && pnpm install && pnpm build --filter=web
Start Command: cd apps/web && pnpm start

Set Environment Variables

Add all environment variables in service settings.

Deploy

Render automatically builds and deploys your application.

Cloudflare Pages

Cloudflare Pages has limitations with Next.js API routes and server-side rendering. Use Cloudflare Workers for API routes or choose a different platform.

Environment-Specific Configuration

Production Environment Variables

For production, ensure these are properly configured:

# Use production URLs
NEXTAUTH_URL=https://yourdomain.com
NEXT_PUBLIC_APP_DOMAIN=yourdomain.com

# Strong secret (32+ characters)
NEXTAUTH_SECRET=<generate-strong-secret>

# Production database
DATABASE_URL=<production-mysql-url>

# Production Redis
UPSTASH_REDIS_REST_URL=<production-redis-url>
UPSTASH_REDIS_REST_TOKEN=<production-redis-token>

Cron Jobs Configuration

Dub requires several cron jobs for proper operation:

Required Cron Jobs

Endpoint	Schedule	Description
`/api/cron/domains/verify`	`0 * * * *`	Verify domain DNS records
`/api/cron/email-domains/verify`	`0 * * * *`	Verify email domains
`/api/cron/streams/update-workspace-clicks`	`* * * * *`	Update workspace click counts
`/api/cron/streams/update-partner-stats`	`/2 * * *`	Update partner statistics
`/api/cron/usage`	`0 12 * * *`	Generate usage reports
`/api/cron/aggregate-clicks`	`0 0 * * *`	Aggregate daily click data

Securing Cron Endpoints

Set CRON_SECRET environment variable and include it in cron requests:

CRON_SECRET=<random-secret>

Cron job example:

curl -H "Authorization: Bearer $CRON_SECRET" https://yourdomain.com/api/cron/usage

Health Checks

Set up health checks for monitoring:

# Basic health check
curl https://yourdomain.com/api/health

# Database connectivity
curl https://yourdomain.com/api/health/db

Monitoring & Logging

Application Monitoring

Configure Axiom for logging:

AXIOM_TOKEN=<your-token>
AXIOM_DATASET=dub-production

Uptime Monitoring

Use services like:

UptimeRobot - Free uptime monitoring
Pingdom - Advanced monitoring and alerts
Better Uptime - Status pages and incident management

Scaling Considerations

Horizontal Scaling

For high traffic:

Deploy multiple instances
Use a load balancer (AWS ALB, Cloudflare, etc.)
Ensure session affinity if using in-memory sessions
Use Redis for session storage

Vertical Scaling

Increase server resources:

CPU: 2+ cores for production
RAM: 4GB minimum, 8GB+ recommended
Storage: SSD with 20GB+ free space

Database Scaling

Use read replicas for analytics queries
Enable query caching
Optimize indexes
Consider database connection pooling

Troubleshooting

Build Failures

# Clear cache and rebuild
find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +
find . -name '.next' -type d -prune -exec rm -rf '{}' +
pnpm install
pnpm build

Runtime Errors

Check logs:

# PM2 logs
pm2 logs dub

# Docker logs
docker logs dub

# Vercel logs
vercel logs

Database Connection Issues

Verify connectivity:

# Test connection
pnpm prisma:studio

# Check environment variables
env | grep DATABASE_URL

Get Started

Core Features

Guides

Self-Hosting

Integrations

​Overview

​Deployment Requirements

​System Requirements

​External Services

​Vercel (Recommended)

​Vercel Configuration

​Railway

​Railway Cron Jobs

​Docker Deployment

​Create Dockerfile

​Build and Run

​Docker Compose

​AWS EC2

​EC2 Cron Jobs

​DigitalOcean App Platform

​Render

​Cloudflare Pages

​Environment-Specific Configuration

​Production Environment Variables

​Cron Jobs Configuration

​Required Cron Jobs

​Securing Cron Endpoints

​Health Checks

​Monitoring & Logging

​Application Monitoring

​Uptime Monitoring

​Scaling Considerations

​Horizontal Scaling

​Vertical Scaling

​Database Scaling

​Troubleshooting

​Build Failures

​Runtime Errors

​Database Connection Issues

​Production Checklist

​Next Steps

Build docs developers (and LLMs) love

Overview

Deployment Requirements

System Requirements

External Services

Vercel (Recommended)

Vercel Configuration

Railway

Railway Cron Jobs

Docker Deployment

Create Dockerfile

Build and Run

Docker Compose

AWS EC2

EC2 Cron Jobs

DigitalOcean App Platform

Render

Cloudflare Pages

Environment-Specific Configuration

Production Environment Variables

Cron Jobs Configuration

Required Cron Jobs

Securing Cron Endpoints

Health Checks

Monitoring & Logging

Application Monitoring

Uptime Monitoring

Scaling Considerations

Horizontal Scaling

Vertical Scaling

Database Scaling

Troubleshooting

Build Failures

Runtime Errors

Database Connection Issues

Production Checklist

Next Steps