Deployment

Overview

Bounty is built with Next.js and can be deployed to various platforms. This guide covers deployment to Vercel (recommended) and self-hosted infrastructure.

Prerequisites

Before deploying, ensure you have:

Environment Variables

All required environment variables configured. See Environment Variables.

Database

PostgreSQL database set up and migrated. See Database Setup.

GitHub App

GitHub OAuth App and GitHub App configured with correct callback URLs.

External Services

Required services (Upstash Redis, GitHub, Better Auth) configured.

Deployment Options

Vercel (Recommended)

Vercel provides the best experience for Next.js applications with:

Zero-configuration deployments
Automatic HTTPS and CDN
Serverless functions for API routes
Edge network for optimal performance
Built-in analytics and monitoring
Cron jobs for scheduled tasks

Self-Hosted

Deploy on your own infrastructure:

Full control over hosting environment
Use existing infrastructure
Deploy to any Node.js hosting platform
Custom domain and SSL configuration

Deploying to Vercel

Initial Setup

Create Vercel Account

Import Repository

Click “Add New Project”
Import your Bounty repository from GitHub
Vercel will auto-detect the Next.js framework

Configure Build Settings

Vercel should auto-detect these settings:

Framework Preset: Next.js
Root Directory: ./ (monorepo root)
Build Command: bun build (or use default)
Output Directory: .next (auto-detected)
Install Command: bun install

Vercel has native Bun support. It will automatically use Bun based on your package.json packageManager field.

Set Environment Variables

In Vercel dashboard → Project Settings → Environment Variables, add all variables from your .env file.

Use different values for Production, Preview, and Development environments.

Required Variables:

DATABASE_URL
BETTER_AUTH_SECRET
BETTER_AUTH_URL (use Vercel domain)
GITHUB_CLIENT_ID & GITHUB_CLIENT_SECRET
GITHUB_APP_* (all GitHub App variables)
UPSTASH_REDIS_REST_URL & UPSTASH_REDIS_REST_TOKEN
NEXT_PUBLIC_BASE_URL (use Vercel domain)

See complete list in Environment Variables.

Deploy

Click “Deploy” - Vercel will:

Clone your repository
Install dependencies with Bun
Build the application
Deploy to edge network

First deployment takes 2-5 minutes.

Post-Deployment Configuration

Update OAuth Callback URLs

Update your GitHub OAuth App and GitHub App settings with your Vercel domain:GitHub OAuth App:

Authorization callback URL: https://your-app.vercel.app/api/auth/callback/github

GitHub App:

Callback URL: https://your-app.vercel.app/api/auth/callback/github
Webhook URL: https://your-app.vercel.app/api/webhooks/github

Environment Variables: Update in Vercel dashboard:

BETTER_AUTH_URL="https://your-app.vercel.app"
NEXT_PUBLIC_BASE_URL="https://your-app.vercel.app"

Configure Custom Domain

Go to Project Settings → Domains
Add your custom domain (e.g., bounty.yourdomain.com)
Follow Vercel’s DNS configuration instructions

Update environment variables with new domain:

BETTER_AUTH_URL="https://bounty.yourdomain.com"
NEXT_PUBLIC_BASE_URL="https://bounty.yourdomain.com"

Update OAuth callback URLs in GitHub to use new domain

Set up Cron Jobs

Bounty includes cron job configuration in vercel.json:

{
  "crons": [
    {
      "path": "/api/cron/cleanup-sessions",
      "schedule": "0 2 * * *"
    }
  ]
}

This runs session cleanup daily at 2 AM UTC.Protect Cron Endpoints: Set CRON_SECRET environment variable and verify in your cron handlers.

Configure Webhooks

Test webhook delivery:

GitHub Webhooks: Trigger test event in GitHub App settings
Stripe Webhooks: Use Stripe CLI or dashboard to send test event
Check Vercel Functions logs for successful processing

All webhooks should be sent to:

GitHub: https://your-domain.com/api/webhooks/github
Stripe: https://your-domain.com/api/webhooks/stripe

Vercel Configuration File

The vercel.json file in the repository root configures Vercel-specific settings:

{
  "build": {
    "env": {
      "SKIP_ENV_VALIDATION": "true"
    }
  },
  "crons": [
    {
      "path": "/api/cron/cleanup-sessions",
      "schedule": "0 2 * * *"
    }
  ]
}

Configuration Details:

SKIP_ENV_VALIDATION - Allows build to use Vercel environment variables
crons - Defines scheduled tasks (Hobby/Pro plans only)

Monitoring on Vercel

Deployment Logs

View build and deployment logs in Vercel dashboard → Deployments → [deployment] → Building

Function Logs

Monitor serverless function execution in Vercel dashboard → Deployments → [deployment] → Functions

Analytics

Track performance and usage in Vercel dashboard → Analytics (requires Pro plan)

Speed Insights

Monitor Core Web Vitals in Vercel dashboard → Speed Insights (requires Pro plan)

Self-Hosted Deployment

Building for Production

Install Dependencies

bun install

Set Environment Variables

Create .env.production with all required variables:

DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="..."
BETTER_AUTH_URL="https://your-domain.com"
# ... all other variables

Run Database Migrations

bun db:migrate

Build Application

bun build

This runs:

turbo build - Builds all apps and packages
Type checking
Next.js production build
Asset optimization

Build output will be in apps/web/.next/

Deployment Options

Docker
PM2
Systemd
Nginx Reverse Proxy

Create a Dockerfile for containerized deployment:

FROM oven/bun:1.2.17 AS base
WORKDIR /app

# Install dependencies
FROM base AS deps
COPY package.json bun.lockb ./
COPY apps/web/package.json ./apps/web/
COPY packages/*/package.json ./packages/*/
RUN bun install --frozen-lockfile

# Build application
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN bun build

# Production image
FROM base AS runner
ENV NODE_ENV=production

COPY --from=builder /app/apps/web/.next ./apps/web/.next
COPY --from=builder /app/apps/web/public ./apps/web/public
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000
ENV PORT 3000

CMD ["bun", "start"]

Build and Run:

# Build image
docker build -t bounty-app .

# Run container
docker run -p 3000:3000 \
  --env-file .env.production \
  bounty-app

Use PM2 for process management:Install PM2:

npm install -g pm2

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'bounty',
    script: 'bun',
    args: 'start',
    cwd: '/path/to/bounty',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    env_file: '.env.production'
  }]
};

Start Application:

pm2 start ecosystem.config.js
pm2 save
pm2 startup

Create a systemd service:Create /etc/systemd/system/bounty.service:

[Unit]
Description=Bounty Application
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/bounty
EnvironmentFile=/var/www/bounty/.env.production
ExecStart=/usr/local/bin/bun start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start:

sudo systemctl enable bounty
sudo systemctl start bounty
sudo systemctl status bounty

Configure Nginx to proxy to your app:/etc/nginx/sites-available/bounty:

server {
    listen 80;
    server_name bounty.yourdomain.com;
    
    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name bounty.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/bounty.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bounty.yourdomain.com/privkey.pem;
    
    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_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;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable Site:

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

SSL/TLS Configuration

For self-hosted deployments, set up SSL certificates: Using Let’s Encrypt (Certbot):

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d bounty.yourdomain.com

# Auto-renewal (runs twice daily)
sudo systemctl enable certbot.timer

Build Scripts Reference

All build scripts are defined in package.json:

{
  "scripts": {
    "dev": "dotenv -- turbo dev --filter='!@bounty/discord-bot'",
    "start": "dotenv -- turbo start",
    "build": "dotenv -- turbo build",
    "check-types": "dotenv -- turbo check-types",
    "db:push": "dotenv -- turbo -F @bounty/db db:push",
    "db:migrate": "dotenv -- turbo -F @bounty/db db:migrate"
  }
}

# Start development server
bun dev

# Start web app only
bun dev:web

# Type checking
bun check-types

Health Checks

Implement health check endpoint for monitoring:

// app/api/health/route.ts
import { db } from '@bounty/db';

export async function GET() {
  try {
    // Check database connectivity
    await db.execute('SELECT 1');
    
    return Response.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      services: {
        database: 'connected',
        redis: 'connected' // Add Redis check
      }
    });
  } catch (error) {
    return Response.json(
      { status: 'unhealthy', error: error.message },
      { status: 503 }
    );
  }
}

Access at: https://your-domain.com/api/health

Troubleshooting

Build Failures

Common Issues:

Missing environment variables during build
Type errors in TypeScript
Dependency conflicts

Solutions:

Set SKIP_ENV_VALIDATION=true for build
Run bun check-types locally first
Clear node_modules and reinstall: rm -rf node_modules && bun install

Runtime Errors

Common Issues:

Database connection errors
Missing environment variables
OAuth redirect mismatches

Solutions:

Verify DATABASE_URL is correct and accessible
Check all required env vars are set
Ensure callback URLs match environment

Webhook Delivery Failures

Common Issues:

GitHub webhooks timing out
Invalid webhook signatures
Firewall blocking requests

Solutions:

Check webhook endpoint is publicly accessible
Verify GITHUB_WEBHOOK_SECRET matches GitHub App
Review webhook delivery logs in GitHub App settings

Performance Issues

Common Issues:

Slow database queries
High memory usage
Rate limiting

Solutions:

Add database indexes for frequently queried columns
Increase serverless function memory (Vercel)
Configure Redis rate limiting properly
Use database connection pooling

Production Checklist

Before going live, verify:

Continuous Deployment

Vercel (Automatic)

Vercel automatically deploys:

Production: Commits to main branch
Preview: Pull requests and other branches

GitHub Actions (Self-Hosted)

Set up automated deployments:

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: 1.2.17
      
      - name: Install dependencies
        run: bun install
      
      - name: Run migrations
        run: bun db:migrate
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
      
      - name: Build application
        run: bun build
        env:
          SKIP_ENV_VALIDATION: true
      
      - name: Deploy to server
        run: |
          rsync -avz --delete \
            --exclude '.env*' \
            --exclude 'node_modules' \
            ./ user@your-server:/var/www/bounty/
          
          ssh user@your-server 'cd /var/www/bounty && pm2 restart bounty'

Next Steps

Installation Guide

Set up local development environment

API Reference

Explore Bounty’s API endpoints

Environment Variables

Configure your environment

GitHub Repository

View source code and report issues

Get Started

Core Features

Integrations

Self-Hosting

Overview

Prerequisites

Deployment Options

Vercel (Recommended)

Self-Hosted

Deploying to Vercel

Initial Setup

Post-Deployment Configuration

Vercel Configuration File

Monitoring on Vercel

Deployment Logs

Function Logs

Analytics

Speed Insights

Self-Hosted Deployment

Building for Production

Deployment Options

SSL/TLS Configuration

Build Scripts Reference

Health Checks

Troubleshooting

Production Checklist

Continuous Deployment

Vercel (Automatic)

GitHub Actions (Self-Hosted)

Next Steps

Installation Guide

API Reference

Environment Variables

GitHub Repository

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Self-Hosting

​Overview

​Prerequisites

​Deployment Options

​Vercel (Recommended)

​Self-Hosted

​Deploying to Vercel

​Initial Setup

​Post-Deployment Configuration

​Vercel Configuration File

​Monitoring on Vercel

Deployment Logs

Function Logs

Analytics

Speed Insights

​Self-Hosted Deployment

​Building for Production

​Deployment Options

​SSL/TLS Configuration

​Build Scripts Reference

​Health Checks

​Troubleshooting

​Production Checklist

​Continuous Deployment

​Vercel (Automatic)

​GitHub Actions (Self-Hosted)

​Next Steps

Installation Guide

API Reference

Environment Variables

GitHub Repository

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Options

Vercel (Recommended)

Self-Hosted

Deploying to Vercel

Initial Setup

Post-Deployment Configuration

Vercel Configuration File

Monitoring on Vercel

Self-Hosted Deployment

Building for Production

Deployment Options

SSL/TLS Configuration

Build Scripts Reference

Health Checks

Troubleshooting

Production Checklist

Continuous Deployment

Vercel (Automatic)

GitHub Actions (Self-Hosted)

Next Steps