Deployment Guide

This guide covers deploying LiveDash to Cloudflare Workers and managing production environments.

Overview

LiveDash is designed to run on Cloudflare's edge infrastructure:

• Runtime: Cloudflare Workers (workerd)
• Database: Cloudflare D1 (SQLite)
• Build Tool: OpenNext.js for Cloudflare
• CDN: Cloudflare global network

Prerequisites

1. Cloudflare Account Setup

• Create a Cloudflare account
• Install Wrangler CLI globally:

pnpm install -g wrangler

2. Authenticate with Cloudflare

# Login to Cloudflare
wrangler auth login

# Verify authentication
wrangler whoami

3. Create Cloudflare D1 Database

# Create production database
wrangler d1 create livedash-prod

# Create staging database (optional)
wrangler d1 create livedash-staging

Update wrangler.jsonc with your database ID:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_id": "your-database-id-here",
      "database_name": "livedash-prod",
    },
  ],
}

Environment Configuration

1. Production Environment Variables

Set production secrets using Wrangler:

# Required Auth.js secrets
wrangler secret put AUTH_SECRET
wrangler secret put AUTH_TRUST_HOST

# OAuth provider secrets (if using)
wrangler secret put AUTH_GITHUB_ID
wrangler secret put AUTH_GITHUB_SECRET
wrangler secret put AUTH_GOOGLE_ID
wrangler secret put AUTH_GOOGLE_SECRET

# Optional: Custom domain
wrangler secret put AUTH_URL

2. Database Configuration

The database binding is configured in wrangler.jsonc and doesn't require secrets.

Deployment Process

1. Prepare for Deployment

# Install dependencies
pnpm install

# Run type checking
pnpm run check

# Format code
pnpm run format

# Run linting
pnpm run lint

2. Database Migration

Apply database migrations to production before deploying code:

# Apply migrations to production D1
pnpm run predeploy

# Or manually:
wrangler d1 migrations apply DB --remote

3. Deploy to Production

# Build and deploy
pnpm run deploy

# Or step by step:
pnpm run build
wrangler deploy

4. Verify Deployment

# Check deployment status
wrangler deployments list

# View logs
wrangler tail

# Test the deployed application
curl https://your-worker.your-subdomain.workers.dev

Deployment Environments

Production Deployment

# Deploy to production
pnpm run deploy

• URL: https://your-worker.your-subdomain.workers.dev
• Database: Remote Cloudflare D1
• Environment: Production secrets from Wrangler

Staging/Preview Deployment

# Deploy to staging environment
wrangler deploy --env staging

# Or use preview (temporary deployment)
pnpm run preview

For staging environments, update wrangler.jsonc:

{
  "env": {
    "staging": {
      "d1_databases": [
        {
          "binding": "DB",
          "database_id": "staging-database-id",
          "database_name": "livedash-staging",
        },
      ],
    },
  },
}

Custom Domain Setup

1. Add Domain to Cloudflare

1. Add your domain to Cloudflare
2. Update nameservers to Cloudflare's
3. Ensure DNS is properly configured

2. Configure Worker Route

# Add custom route
wrangler route add "yourdomain.com/*" your-worker-name

# Or add subdomain
wrangler route add "app.yourdomain.com/*" your-worker-name

3. Update Auth Configuration

# Set custom AUTH_URL
wrangler secret put AUTH_URL
# Enter: https://yourdomain.com

Database Management

Production Database Operations

# View database info
wrangler d1 info livedash-prod --remote

# Execute queries
wrangler d1 execute livedash-prod --remote --command "SELECT COUNT(*) FROM users"

# Create backup
wrangler d1 export livedash-prod --remote --output backup-$(date +%Y%m%d).sql

# Import data (be careful!)
wrangler d1 execute livedash-prod --remote --file backup.sql

Migration Management

# Check migration status
wrangler d1 migrations list DB --remote

# Apply pending migrations
wrangler d1 migrations apply DB --remote

# View migration history
wrangler d1 migrations list DB --remote

Monitoring & Debugging

Application Logs

# Real-time logs
wrangler tail

# Filter logs by status
wrangler tail --status error

# Save logs to file
wrangler tail > deployment.log

Performance Monitoring

Access Cloudflare Analytics:

1. Go to Cloudflare Dashboard
2. Select your account
3. Navigate to Workers & Pages
4. Select your worker
5. View Analytics tab

Error Tracking

# View recent errors
wrangler tail --status error

# Check deployment health
curl -I https://your-worker.your-subdomain.workers.dev

CI/CD Setup

GitHub Actions Example

Create .github/workflows/deploy.yml:

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: latest

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Run type check
        run: pnpm run check

      - name: Apply migrations
        run: pnpm run predeploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

      - name: Deploy to Cloudflare Workers
        run: pnpm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Required GitHub Secrets

1. Go to your GitHub repository
2. Navigate to Settings → Secrets and variables → Actions
3. Add the following secrets:

• CLOUDFLARE_API_TOKEN: Your Cloudflare API token

Rollback Strategy

Quick Rollback

# List recent deployments
wrangler deployments list

# Rollback to previous version
wrangler rollback [deployment-id]

Database Rollback

# Create database backup before changes
wrangler d1 export livedash-prod --remote --output pre-migration-backup.sql

# If rollback needed, restore from backup
wrangler d1 execute livedash-prod --remote --file pre-migration-backup.sql

Performance Optimization

Build Optimization

The project uses OpenNext.js for optimal Cloudflare Workers deployment:

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig({
  // Enable R2 cache for better performance
  // incrementalCache: r2IncrementalCache,
});

Edge Caching

Leverage Cloudflare's edge caching:

// Add to API routes for caching
export const runtime = "edge";

export async function GET() {
  return new Response(data, {
    headers: {
      "Cache-Control": "public, max-age=3600",
    },
  });
}

Security Considerations

Environment Security

• Use Wrangler secrets for sensitive data
• Never commit secrets to version control
• Rotate secrets regularly
• Use different secrets for staging/production

Database Security

• Regularly backup production database
• Monitor database access logs
• Use principle of least privilege
• Enable Cloudflare security features

Cost Management

Cloudflare Workers Pricing

• Free Tier: 100,000 requests/day
• Paid Plan: $5/month for 10M requests
• D1: First 5M reads/day free

Optimization Tips

• Cache static assets
• Optimize database queries
• Use edge caching effectively
• Monitor usage in Cloudflare dashboard

Troubleshooting

Common Deployment Issues

Build Failures

# Clear build cache
rm -rf .next .open-next
pnpm run build

Database Connection Issues

# Verify database binding
wrangler d1 info DB --remote

# Check migration status
wrangler d1 migrations list DB --remote

Auth Issues in Production

• Verify AUTH_SECRET is set
• Check AUTH_URL matches your domain
• Ensure OAuth redirect URLs are configured

Performance Issues

# Check worker logs
wrangler tail

# Monitor resource usage
# View Cloudflare Analytics dashboard

Getting Support

• Cloudflare Workers Documentation
• OpenNext.js Documentation
• Auth.js Documentation
• Project Issues

Maintenance Tasks

Regular Maintenance

# Weekly database backup
wrangler d1 export livedash-prod --remote --output weekly-backup-$(date +%Y%m%d).sql

# Update dependencies
pnpm update

# Security audit
pnpm audit

Health Checks

Set up monitoring for:

• Application availability
• Database performance
• Error rates
• Response times

Consider using external monitoring services or Cloudflare's built-in analytics.