Quick Start

Get PULSE up and running in 5 minutes

5-Minute Quick Start

Get PULSE running locally in just a few minutes.

Prerequisites

• Cloudflare account (free tier works)
• Node.js 18+
• npm or yarn
• Git

Step 1: Clone the Repository

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

Step 2: Install Dependencies

npm install

Step 3: Set Up Cloudflare Resources

# Log in to Cloudflare
wrangler login

# Create D1 database
wrangler d1 create pulse_analytics

# Create KV namespace
wrangler kv:namespace create CACHE

# Note the IDs and update wrangler.toml

Step 4: Update Configuration

Edit wrangler.toml and add your Cloudflare resources:

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

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

Step 5: Deploy

# Build
npm run build

# Deploy to Cloudflare
npm run deploy

Step 6: Get Your API Key

# Create an API key (via Cloudflare dashboard)
# Copy the key for use in your application

Step 7: Send Your First Event

curl https://your-worker.dev/collect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "site_id": "site_123",
    "event_type": "page_view",
    "timestamp": '$(date +%s000)',
    "session_id": "session_abc"
  }'

Step 8: Query Your Data

curl "https://your-worker.dev/api/v1/stats?site_id=site_123&metric=event_count" \
  -H "Authorization: Bearer YOUR_API_KEY"

What’s Next?

• Full Installation Guide — Detailed setup with environment variables
• First Event — Comprehensive event examples
• API Reference — Complete API documentation
• Architecture — How PULSE works under the hood

Troubleshooting

Port 8787 already in use?

# Use a different port
wrangler dev --port 8788

Authentication failed?

Check your API key:

# Verify the key exists
curl https://your-worker.dev/api/v1/auth \
  -H "Authorization: Bearer YOUR_API_KEY"

D1 database not found?

Ensure your wrangler.toml has the correct database ID and your development environment is configured:

wrangler d1 list

Still stuck?

See the Troubleshooting Guide for more help.