Installation Guide

Comprehensive PULSE installation and setup instructions

Installation Guide

Detailed instructions for installing and configuring PULSE for your environment.

System Requirements

Step 1: Repository Setup

Clone the PULSE repository:

git clone https://github.com/tesorosocial/pulse.git
cd pulse

Step 2: Project Structure

PULSE is organized as follows:

pulse/
├── pulse-app/          # Main Worker application
├── sdk/                # JavaScript/TypeScript SDK
├── dashboard/          # Analytics dashboard (optional)
└── docs-site/          # Documentation (this site)

Navigate to the application directory:

cd pulse/pulse-app

Step 3: Install Dependencies

npm install

This installs:

• wrangler — Cloudflare CLI
• TypeScript development tools
• Testing frameworks (Vitest, Playwright)
• Linting and formatting tools

Step 4: Cloudflare Account Setup

Option A: Using Cloudflare Dashboard

1. Visit Cloudflare Dashboard
2. Go to Workers & Pages → D1
3. Create a new database named pulse_analytics
4. Go to KV and create a namespace named pulse_cache
5. Note the IDs for both resources

Option B: Using Wrangler CLI

# Ensure you're logged in
wrangler login

# Create D1 database
wrangler d1 create pulse_analytics

# Create KV namespace
wrangler kv:namespace create pulse_cache

Step 5: Configuration Files

wrangler.toml

Update wrangler.toml with your resource IDs:

[env.development]
vars = { DATADOG_SITE = "datadoghq.com" }

[[env.development.d1_databases]]
binding = "DB"
database_name = "pulse_analytics"
database_id = "YOUR_DATABASE_ID_HERE"

[[env.development.kv_namespaces]]
binding = "CACHE"
id = "YOUR_KV_NAMESPACE_ID_HERE"

Environment Variables

Create a .dev.vars file for local development:

API_SECRET=your_secret_key_here
DATADOG_API_KEY=optional_datadog_key

Step 6: Database Setup

Run migrations to set up the database schema:

# Apply all migrations
npm run db:migrate

# Or manually:
wrangler d1 execute pulse_analytics --file=migrations/001_initial_schema.sql

Step 7: Verification

Verify your installation:

# Test build
npm run build

# Start development server
npm run dev

# In another terminal, test the API
curl http://localhost:8787/health

Expected response:

{
  "status": "ok",
  "timestamp": 1703001234567
}

Step 8: Deployment

Development Deployment

npm run deploy

Staging Deployment

npm run deploy:staging

Production Deployment

npm run deploy:blue

Optional: Environment-Specific Configuration

Create environment-specific bindings in wrangler.toml:

[env.production]
vars = { DATADOG_SITE = "datadoghq.com" }
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

[[env.production.d1_databases]]
binding = "DB"
database_name = "pulse_analytics"
database_id = "PROD_DATABASE_ID"

[[env.production.kv_namespaces]]
binding = "CACHE"
id = "PROD_KV_NAMESPACE_ID"

Optional: Monitoring with Datadog

To enable Datadog monitoring:

1. Get your Datadog API key from Datadog Dashboard

2. Set the secret:

wrangler secret put DATADOG_API_KEY --env production

3. Update wrangler.toml:

[env.production]
vars = { DATADOG_SITE = "datadoghq.com" }

Verification Checklist

After installation, verify everything is working:

• Node.js 18+ installed (node --version)
• npm 9+ installed (npm --version)
• Repository cloned and dependencies installed
• Cloudflare account configured
• D1 database created and ID in wrangler.toml
• KV namespace created and ID in wrangler.toml
• .dev.vars file configured
• Build successful (npm run build)
• Development server starts (npm run dev)
• /health endpoint responds

Next Steps

1. Basic Setup — Configure your PULSE instance
2. Send First Event — Start tracking data
3. API Reference — Learn the API

Troubleshooting

”database not found” Error

Ensure the database ID in wrangler.toml matches your created database:

wrangler d1 list

Port Already in Use

Use a different port:

wrangler dev --port 8788

Module Not Found

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

TypeScript Errors

Update TypeScript definitions:

npm install --save-dev @cloudflare/workers-types@latest

For more help, see the Troubleshooting Guide.