Production deployment guide

Production Deployment Guide

This guide walks through the complete production deployment process for Dashtray MVP, including environment setup, service configuration, and verification steps.

Prerequisites

Before starting the deployment, ensure you have:

• Cloudflare account with Pages enabled
• Convex account with production deployment
• DodoPayments account configured
• Resend account for transactional emails
• Custom domain registered (optional)
• GitHub repository with CI/CD workflows
• All required API keys and secrets

Table of Contents

1. Environment Variables Setup
2. Convex Production Deployment
3. Cloudflare Pages Setup
4. Custom Domain and SSL
5. DodoPayments Webhook Configuration
6. Staging Environment Testing
7. Production Deployment
8. Post-Deployment Verification
9. Monitoring Setup
10. Rollback Procedures

---

1. Environment Variables Setup

1.1 Convex Environment Variables

Set these variables in your Convex production deployment:

# Navigate to your Convex dashboard or use CLI
npx convex env set SITE_URL "https://dashtray.com" --prod
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)" --prod
npx convex env set RESEND_API_KEY "re_xxxxxxxxxxxxx" --prod
npx convex env set RESET_EMAIL_FROM "[e-mail]" --prod

# Optional: OAuth providers
npx convex env set GOOGLE_CLIENT_ID "your-google-client-id" --prod
npx convex env set GOOGLE_CLIENT_SECRET "your-google-client-secret" --prod

# DodoPayments configuration
npx convex env set DODO_PAYMENTS_API_KEY "dodo_xxxxxxxxxxxxx" --prod
npx convex env set DODO_PAYMENTS_ENVIRONMENT "production" --prod

# Master encryption key for API credentials (32-byte hex)
npx convex env set MASTER_ENCRYPTION_KEY "$(openssl rand -hex 32)" --prod

Important: Store these values securely in a password manager. You’ll need them for disaster recovery.

1.2 GitHub Secrets and Variables

Configure these in your GitHub repository settings:

Secrets (Settings → Secrets and variables → Actions → New repository secret):

CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
BETTER_AUTH_SECRET=same-as-convex-value

Variables (Settings → Secrets and variables → Actions → New repository variable):

PUBLIC_CONVEX_URL=https://your-project.convex.cloud
PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site
SITE_URL=https://dashtray.com
CLOUDFLARE_PROJECT_NAME=dashtray
BETTER_AUTH_URL=https://dashtray.com

1.3 Local .env.local (for reference)

Keep a local copy for development:

# .env.local
PUBLIC_CONVEX_URL=https://your-project.convex.cloud
PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site
SITE_URL=http://localhost:5173

---

2. Convex Production Deployment

2.1 Deploy Convex Functions

# Ensure you're on the main branch
git checkout main
git pull origin main

# Deploy to production
npx convex deploy --prod

# Verify deployment
npx convex env list --prod

2.2 Verify Convex Deployment

1. Check the Convex dashboard: https://dashboard.convex.dev
2. Verify all functions are deployed
3. Check cron jobs are scheduled:
   • sync-pro-metrics (every 3 hours)
   • sync-scale-metrics (every 30 minutes)
   • check-alerts (every 5 minutes)
   • cleanup-old-metrics (daily at 2 AM UTC)

2.3 Test Convex Functions

# Test a simple query
npx convex run projects:list --prod

# Check HTTP endpoints
curl https://your-project.convex.site/api/v1/health

---

3. Cloudflare Pages Setup

3.1 Create Cloudflare Pages Project

1. Log in to Cloudflare Dashboard
2. Navigate to Workers & Pages → Create application → Pages
3. Connect your GitHub repository
4. Configure build settings:
   • Framework preset: SvelteKit
   • Build command: pnpm run build
   • Build output directory: .svelte-kit/cloudflare
   • Root directory: /

3.2 Configure Environment Variables

In Cloudflare Pages project settings → Environment variables:

Production environment:

PUBLIC_CONVEX_URL=https://your-project.convex.cloud
PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site
SITE_URL=https://dashtray.com

Preview environment (optional):

PUBLIC_CONVEX_URL=https://your-dev-project.convex.cloud
PUBLIC_CONVEX_SITE_URL=https://your-dev-project.convex.site
SITE_URL=https://dev.dashtray.com

3.3 Configure Build Settings

1. Node.js version: 20
2. Compatibility flags: nodejs_compat
3. Compatibility date: 2025-01-01

---

4. Custom Domain and SSL

4.1 Add Custom Domain

1. In Cloudflare Pages project → Custom domains
2. Click Set up a custom domain
3. Enter your domain: dashtray.com
4. Add DNS records as instructed:
   • Type: CNAME
   • Name: @ (or www)
   • Target: your-project.pages.dev

4.2 Configure SSL/TLS

1. Navigate to SSL/TLS in Cloudflare dashboard
2. Set encryption mode to Full (strict)
3. Enable Always Use HTTPS
4. Enable Automatic HTTPS Rewrites
5. Enable HTTP Strict Transport Security (HSTS):
   • Max Age: 12 months
   • Include subdomains: Yes
   • Preload: Yes

4.3 Verify SSL Certificate

# Check SSL certificate
curl -I https://dashtray.com

# Verify HTTPS redirect
curl -I http://dashtray.com

---

5. DodoPayments Webhook Configuration

5.1 Configure Webhook URL

1. Log in to DodoPayments dashboard
2. Navigate to Settings → Webhooks
3. Add webhook endpoint:
   • URL: https://your-project.convex.site/dodopayments-webhook
   • Events: Select all subscription and payment events:
     • subscription.active
     • subscription.renewed
     • subscription.cancelled
     • subscription.expired
     • payment.succeeded
     • payment.failed

5.2 Test Webhook

# Use DodoPayments test mode to trigger a test webhook
# Verify in Convex logs that the webhook is received

# Check Convex logs
npx convex logs --prod

5.3 Verify Webhook Signature

The webhook handler automatically verifies signatures using the DodoPayments SDK. Ensure the DODO_PAYMENTS_API_KEY is correctly set in Convex environment variables.

---

6. Staging Environment Testing

6.1 Deploy to Staging

# Create a staging branch
git checkout -b staging
git push origin staging

# GitHub Actions will automatically deploy to preview environment

6.2 Run Test Suite

# Run unit tests
pnpm test:unit

# Run integration tests
pnpm test:integration

# Run e2e tests against staging
PLAYWRIGHT_BASE_URL=https://staging.dashtray.pages.dev pnpm test:e2e

6.3 Manual Testing Checklist

• User registration and email verification
• Login with email/password
• OAuth login (Google, GitHub)
• Create project
• Connect integration (Stripe, GitHub, etc.)
• View metrics on dashboard
• Create custom dashboard
• Drag and drop widgets
• Create alert (Pro+ tier)
• Test AI chat with BYOK
• Invite team member
• Upgrade subscription
• Test webhook (DodoPayments)
• Export data (Scale+ tier)
• View audit logs (Scale+ tier)
• Test API endpoints (Scale+ tier)

---

7. Production Deployment

7.1 Pre-Deployment Checklist

• All tests passing
• Staging environment verified
• Database migrations completed (if any)
• Environment variables configured
• SSL certificate active
• Webhooks configured
• Monitoring setup complete
• Rollback plan documented

7.2 Deploy to Production

# Merge to main branch
git checkout main
git merge staging
git push origin main

# GitHub Actions will automatically:
# 1. Run code quality checks
# 2. Build the application
# 3. Deploy Convex functions
# 4. Deploy to Cloudflare Pages

7.3 Monitor Deployment

1. Watch GitHub Actions workflow: https://github.com/your-org/dashtray/actions
2. Monitor Convex logs: npx convex logs --prod --watch
3. Check Cloudflare Pages deployment status
4. Verify application is accessible: https://dashtray.com

---

8. Post-Deployment Verification

8.1 Smoke Tests

# Test homepage
curl -I https://dashtray.com

# Test API health endpoint
curl https://your-project.convex.site/api/health

# Test authentication
curl -X POST https://dashtray.com/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"testpass"}'

8.2 Integration Tests

• Stripe integration connects successfully
• GitHub integration fetches metrics
• Vercel integration syncs deployments
• Google Analytics OAuth flow works
• Plausible integration retrieves data

8.3 Webhook Tests

# Trigger test subscription event in DodoPayments
# Verify webhook is received and processed

# Check Convex logs
npx convex logs --prod | grep "Subscription"

8.4 Performance Tests

• Homepage loads in < 2s
• Dashboard loads in < 3s
• API response time < 200ms
• Widget render time < 500ms

8.5 Security Tests

• HTTPS enforced
• HSTS header present
• CSP headers configured
• API authentication required
• Rate limiting active
• Webhook signatures verified

---

9. Monitoring Setup

9.1 Uptime Monitoring

Set up uptime monitoring with a service like:

• UptimeRobot
• Pingdom
• StatusCake

Endpoints to monitor:

• https://dashtray.com (every 5 minutes)
• https://your-project.convex.site/api/health (every 5 minutes)

Alert conditions:

• 3 consecutive failures
• Response time > 5s
• HTTP status code 5xx

9.2 Error Tracking

Configure Sentry or similar:

// src/hooks.client.ts
import * as Sentry from '@sentry/sveltekit';

if (import.meta.env.PROD) {
  Sentry.init({
    dsn: 'your-sentry-dsn',
    environment: 'production',
    tracesSampleRate: 0.1
  });
}

9.3 Performance Monitoring

Monitor Core Web Vitals:

• LCP (Largest Contentful Paint) < 2.5s
• FID (First Input Delay) < 100ms
• CLS (Cumulative Layout Shift) < 0.1

9.4 Usage Analytics

Configure analytics (optional):

• Plausible Analytics
• Mixpanel
• PostHog

---

10. Rollback Procedures

10.1 Rollback Convex Deployment

# List recent deployments
npx convex deployments list --prod

# Rollback to previous deployment
npx convex deployments rollback <deployment-id> --prod

10.2 Rollback Cloudflare Pages

1. Go to Cloudflare Pages dashboard
2. Navigate to Deployments
3. Find the last working deployment
4. Click Rollback to this deployment

10.3 Rollback GitHub

# Revert to previous commit
git revert HEAD
git push origin main

# Or reset to specific commit
git reset --hard <commit-hash>
git push origin main --force

---

Troubleshooting

Common Issues

Issue: Convex functions not deploying

• Solution: Check convex.json configuration, ensure functions path is correct

Issue: Environment variables not loading

• Solution: Verify variables are set in both Convex and Cloudflare Pages

Issue: Webhooks not received

• Solution: Check webhook URL, verify signature validation, check Convex logs

Issue: SSL certificate errors

• Solution: Ensure DNS records are correct, wait for propagation (up to 24 hours)

Issue: Build failures

• Solution: Check Node.js version (should be 20), verify dependencies are installed

Support Contacts

• Convex Support: [e-mail]
• Cloudflare Support: https://dash.cloudflare.com/support
• DodoPayments Support: [e-mail]

---

Deployment Checklist Summary

Pre-Deployment

• Environment variables configured (Convex, GitHub, Cloudflare)
• Convex functions deployed to production
• Cloudflare Pages project created
• Custom domain configured with SSL
• DodoPayments webhooks configured
• Staging environment tested
• All tests passing

Deployment

• Code merged to main branch
• GitHub Actions workflow completed successfully
• Application accessible at production URL
• SSL certificate active

Post-Deployment

• Smoke tests passed
• Integration tests passed
• Webhook tests passed
• Performance tests passed
• Security tests passed
• Monitoring configured
• Error tracking configured
• Team notified of deployment

---

Next Steps

After successful production deployment:

1. Monitor for 24 hours: Watch for errors, performance issues, or user reports
2. Set up alerts: Configure monitoring alerts for critical issues
3. Document incidents: Keep a log of any issues and resolutions
4. Plan next release: Schedule regular deployments (weekly/bi-weekly)
5. Gather feedback: Collect user feedback and prioritize improvements

---

Additional Resources

• Convex Documentation
• Cloudflare Pages Documentation
• SvelteKit Deployment Guide
• DodoPayments Documentation
• Better Auth Documentation