Deployment Guide

Deploy PULSE to production

Deployment Guide

Deploy PULSE to Cloudflare Workers in production.

Prerequisites

• Cloudflare account with Workers enabled
• D1 database and KV namespace provisioned
• Domain configured in Cloudflare
• Node.js 18+ and npm 9+

Deployment Environments

PULSE supports three deployment environments:

• Development — Local testing (wrangler dev)
• Staging — Pre-production testing (wrangler deploy --env staging)
• Production — Live traffic (wrangler deploy --env production)

Step 1: Configure wrangler.toml

Update wrangler.toml with your Cloudflare credentials:

name = "pulse-app"
main = "src/index.ts"
account_id = "YOUR_ACCOUNT_ID"

[[d1_databases]]
binding = "DB"
database_name = "pulse_analytics"
database_id = "YOUR_DATABASE_ID"

[[kv_namespaces]]
binding = "CACHE"
id = "YOUR_KV_NAMESPACE_ID"

[triggers]
crons = ["0 * * * *"]  # Hourly

Step 2: Set Secrets

# Production API key
wrangler secret put API_SECRET --env production

# Optional: Datadog API key
wrangler secret put DATADOG_API_KEY --env production

Step 3: Build

npm run build

Verify no TypeScript errors:

npx tsc --noEmit

Step 4: Test

Run tests before deploying:

npm run test          # Unit tests
npm run test:e2e      # E2E tests
npm run test:load     # Load tests (optional)

Step 5: Deploy

Staging Deployment

npm run deploy:staging

Production Deployment

npm run deploy:blue

Canary Deployment (10% traffic)

npm run deploy:canary

Step 6: Verify Deployment

Check deployment status:

curl https://api.example.com/health
# Expected: { "status": "ok", "timestamp": ... }

curl https://api.example.com/health/ready
# Expected: { "status": "ready", "dependencies": { ... } }

Blue-Green Deployment Strategy

PULSE uses blue-green deployments:

• Blue — Current production version
• Green — New version being tested
• Canary — 10% traffic to test stability

Rollback

If issues occur:

npm run deploy:rollback

This deploys the last stable blue version.

Environment-Specific Configuration

Development

npm run dev  # Local testing at http://localhost:8787

Staging

wrangler deploy --env staging
# Routes to staging.api.example.com

Production

wrangler deploy --env production
# Routes to api.example.com

Database Migrations

Before deploying, apply any new migrations:

# View migrations
ls -la migrations/

# Apply migrations (before deployment)
wrangler d1 execute pulse_analytics --batch migrations/*.sql

Monitoring Deployment

Monitor deployment health:

# View logs
wrangler tail

# Get deployment info
wrangler deployments list

# Rollback if needed
wrangler rollback

Post-Deployment Checklist

After deploying to production:

• Health check responding (/health)
• Readiness probe passing (/health/ready)
• API authentication working
• Events being ingested
• Queries returning data
• WebSocket streaming working
• Webhooks dispatching
• Monitoring enabled (Datadog)
• Logs being collected
• Error rate < 0.1%

Performance Baseline

After deployment, monitor:

Troubleshooting Deployment

Deploy Fails with “Database not found"

# Verify database exists
wrangler d1 list

# Check wrangler.toml has correct database_id

"Unauthorized” After Deploy

# Verify API secret is set
wrangler secret list --env production

# Re-set if needed
wrangler secret put API_SECRET --env production

High Latency After Deploy

# Check cache is working
curl https://api.example.com/api/v1/stats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-custom-debug: true"

# View KV cache hit rate in dashboard

Next Steps

• Environment Setup — Configure environments
• Monitoring — Set up observability
• Troubleshooting — Resolve issues