> ## Documentation Index
> Fetch the complete documentation index at: https://dashtray.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#1-environment-variables-setup)
2. [Convex Production Deployment](#2-convex-production-deployment)
3. [Cloudflare Pages Setup](#3-cloudflare-pages-setup)
4. [Custom Domain and SSL](#4-custom-domain-and-ssl)
5. [DodoPayments Webhook Configuration](#5-dodopayments-webhook-configuration)
6. [Staging Environment Testing](#6-staging-environment-testing)
7. [Production Deployment](#7-production-deployment)
8. [Post-Deployment Verification](#8-post-deployment-verification)
9. [Monitoring Setup](#9-monitoring-setup)
10. [Rollback Procedures](#10-rollback-procedures)

***

## 1. Environment Variables Setup

### 1.1 Convex Environment Variables

Set these variables in your Convex production deployment:

```bash  theme={null}
# 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 "noreply@dashtray.com" --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  theme={null}
# .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

```bash  theme={null}
# 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](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

```bash  theme={null}
# 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

```bash  theme={null}
# 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

```bash  theme={null}
# 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

```bash  theme={null}
# 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

```bash  theme={null}
# 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

```bash  theme={null}
# 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](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](https://dashtray.com)

***

## 8. Post-Deployment Verification

### 8.1 Smoke Tests

```bash  theme={null}
# 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":"test@example.com","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

```bash  theme={null}
# 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:

```typescript  theme={null}
// 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

```bash  theme={null}
# 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

```bash  theme={null}
# 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**: [support@convex.dev](mailto:support@convex.dev)
* **Cloudflare Support**: [https://dash.cloudflare.com/support](https://dash.cloudflare.com/support)
* **DodoPayments Support**: [support@dodopayments.com](mailto:support@dodopayments.com)

***

## 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](https://docs.convex.dev)
* [Cloudflare Pages Documentation](https://developers.cloudflare.com/pages)
* [SvelteKit Deployment Guide](https://kit.svelte.dev/docs/adapter-cloudflare)
* [DodoPayments Documentation](https://docs.dodopayments.com)
* [Better Auth Documentation](https://www.better-auth.com/docs)


Built with [Mintlify](https://mintlify.com).