dubs-server 1.0.0

package/documentation/HEROKU_DEPLOYMENT.md

@@ -0,0 +1,134 @@
+# 🚀 Heroku Deployment Guide - Dubs Server
+
+## Quick Deploy Commands
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+
+# 1. Commit latest changes
+git add .
+git commit -m "Update jackpot keeper and fix program ID"
+
+# 2. Deploy to Heroku
+git push heroku-dev main
+
+# 3. Set environment variables (if not already set)
+heroku config:set SOLANA_NETWORK=https://api.devnet.solana.com -a dubs-server-dev
+heroku config:set PROGRAM_ID=8DJTkgk6MDr6tPtw4v2VzYAz9WWvmCg6786vZrEK3o5q -a dubs-server-dev
+heroku config:set JACKPOT_PROGRAM_ID=bqoSjTSPLweMuqNG6jy39jmzGyZvZdWjsr4csGfD8F6 -a dubs-server-dev
+
+# 4. Enable jackpot keeper dyno
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev
+
+# 5. Check status
+heroku ps -a dubs-server-dev
+
+# 6. View logs
+heroku logs --tail -a dubs-server-dev
+```
+
+## What's Running
+
+Your Heroku app should have 3 processes:
+
+1. **web** - API server (always on)
+2. **oracle** - Sports betting oracle (for automatic game resolution)
+3. **jackpot-keeper** - Jackpot round manager (NEW!)
+
+## Verify Deployment
+
+```bash
+# Health check
+curl https://dubs-server-dev.herokuapp.com/jackpot/health | python3 -m json.tool
+
+# Current round
+curl https://dubs-server-dev.herokuapp.com/jackpot/round/current | python3 -m json.tool
+
+# Config
+curl https://dubs-server-dev.herokuapp.com/jackpot/config | python3 -m json.tool
+```
+
+## Troubleshooting
+
+### Check Logs
+
+```bash
+# All logs
+heroku logs --tail -a dubs-server-dev
+
+# Keeper logs only
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+
+# API logs only
+heroku logs --tail --ps web -a dubs-server-dev
+```
+
+### Restart Services
+
+```bash
+# Restart everything
+heroku ps:restart -a dubs-server-dev
+
+# Restart keeper only
+heroku ps:restart jackpot-keeper -a dubs-server-dev
+```
+
+### Check Process Status
+
+```bash
+heroku ps -a dubs-server-dev
+```
+
+Expected output:
+```
+=== web (Free): node server.js (1)
+web.1: up 2024/11/16 14:00:00 -0500 (~ 1h ago)
+
+=== jackpot-keeper (Free): node scripts/jackpot-keeper.js (1)
+jackpot-keeper.1: up 2024/11/16 14:00:00 -0500 (~ 1h ago)
+
+=== oracle (Free): node cron/oracleMonitor.js (1)
+oracle.1: up 2024/11/16 14:00:00 -0500 (~ 1h ago)
+```
+
+## Important Notes
+
+⚠️ **Free Tier Limitations:**
+- Heroku free tier only allows 550 dyno hours per month
+- With 3 processes, that's ~183 hours each (~7.6 days)
+- Consider upgrading to Hobby tier ($7/month per dyno) for 24/7 operation
+
+💡 **Optimization Tip:**
+If on free tier, you can disable the oracle dyno when not using sports betting:
+```bash
+heroku ps:scale oracle=0 -a dubs-server-dev
+```
+
+## Environment Variables
+
+View all config vars:
+```bash
+heroku config -a dubs-server-dev
+```
+
+Set a config var:
+```bash
+heroku config:set VARIABLE_NAME=value -a dubs-server-dev
+```
+
+## Deploy Process
+
+1. Make code changes locally
+2. Test locally: `node server.js` and `node scripts/jackpot-keeper.js`
+3. Commit changes: `git add . && git commit -m "Your message"`
+4. Push to Heroku: `git push heroku-dev main`
+5. Watch logs: `heroku logs --tail -a dubs-server-dev`
+
+## Success Indicators
+
+✅ API responds at `/jackpot/health`  
+✅ Current round exists at `/jackpot/round/current`  
+✅ Keeper logs show round management activity  
+✅ New rounds open automatically every ~1 minute  
+✅ Frontend can connect and place bets  
+

package/documentation/HEROKU_SCHEDULER_SETUP.md

@@ -0,0 +1,271 @@
+# ⏰ Heroku Scheduler Setup Guide
+
+**Purpose:** Automate daily database cleanup  
+**Cost:** FREE (included with Heroku)
+
+---
+
+## 🚀 Quick Setup (5 minutes)
+
+### Step 1: Add Scheduler Addon
+
+```bash
+heroku addons:create scheduler:standard -a dubs-server-dev
+```
+
+**Output:**
+```
+Creating scheduler:standard on dubs-server-dev... free
+Created scheduler-regular-12345
+Use heroku addons:docs scheduler to view documentation
+```
+
+### Step 2: Open Scheduler Dashboard
+
+```bash
+heroku addons:open scheduler -a dubs-server-dev
+```
+
+This opens the web interface in your browser.
+
+### Step 3: Add Daily Cleanup Job
+
+**In the Scheduler Dashboard, click "Add Job":**
+
+```
+Command:        node scripts/cleanup-database.js
+Frequency:      Daily
+Time (UTC):     03:00 (3:00 AM UTC = 10pm PST / 11pm EST)
+Dyno Size:      Standard-1X
+```
+
+Click **"Save Job"**
+
+### Step 4: Test It Works
+
+```bash
+# Trigger job manually (doesn't wait for schedule)
+heroku run node scripts/cleanup-database.js -a dubs-server-dev
+```
+
+Should see:
+```
+🧹 DATABASE CLEANUP STARTING
+📊 Before Cleanup: ...
+✅ CLEANUP COMPLETE
+```
+
+---
+
+## 📊 What Gets Cleaned Daily
+
+**At 3am UTC every day, the job:**
+
+1. Deletes `keeper_actions` older than 30 days
+2. Deletes `keeper_health` snapshots older than 90 days
+3. Archives incomplete `keeper_rounds` older than 30 days
+4. Runs VACUUM to reclaim disk space
+5. Logs summary to scheduler logs
+
+**Keeps forever:**
+- ✅ All resolved rounds (`keeper_rounds` where status='resolved')
+- ✅ All jackpot history (`jackpot_rounds` for user verification)
+
+---
+
+## 🔍 Verify Scheduler is Running
+
+### **Check if addon is active:**
+
+```bash
+heroku addons -a dubs-server-dev | grep scheduler
+```
+
+Should show:
+```
+scheduler (scheduler:standard)  free
+```
+
+### **View scheduled jobs:**
+
+```bash
+heroku addons:open scheduler -a dubs-server-dev
+```
+
+Or via CLI:
+```bash
+heroku run:detached heroku scheduler:jobs -a dubs-server-dev
+```
+
+### **Check scheduler logs:**
+
+```bash
+heroku logs --ps scheduler -a dubs-server-dev --tail
+```
+
+**After cleanup runs, you'll see:**
+```
+2025-11-18T03:00:15 app[scheduler.1]: 🧹 DATABASE CLEANUP STARTING
+2025-11-18T03:00:16 app[scheduler.1]: ✅ CLEANUP COMPLETE
+```
+
+---
+
+## ⚙️ Advanced Configuration
+
+### **Change Cleanup Time:**
+
+1. Open dashboard: `heroku addons:open scheduler -a dubs-server-dev`
+2. Click on the job
+3. Change "Time (UTC)"
+4. Save
+
+**Best times:**
+- **3:00 AM UTC** - Off-peak for US/Europe
+- **10:00 AM UTC** - Off-peak for Asia
+
+### **Change Frequency:**
+
+**Daily:** Current setting (recommended)  
+**Hourly:** Overkill unless you have 1000s of rounds/day  
+**Every 10 min:** Never needed
+
+### **Run Cleanup Manually:**
+
+```bash
+# One-time execution
+heroku run node scripts/cleanup-database.js -a dubs-server-dev
+```
+
+---
+
+## 🔧 Modify Retention Policies
+
+**Edit `scripts/cleanup-database.js`:**
+
+```javascript
+const RETENTION_POLICIES = {
+  keeper_actions: 30,        // Change to 7, 14, 60, etc.
+  keeper_health: 90,         // Change to 30, 60, 180, etc.
+  keeper_rounds_incomplete: 30,
+};
+```
+
+**Then redeploy:**
+```bash
+git add scripts/cleanup-database.js
+git commit -m "Adjust retention policies"
+git push heroku-dev main
+```
+
+---
+
+## 📊 Monitor Cleanup Effectiveness
+
+### **Before/After Comparison:**
+
+```bash
+# Run cleanup
+heroku run node scripts/cleanup-database.js -a dubs-server-dev
+
+# Check size reduction
+heroku pg:info -a dubs-server-dev
+```
+
+### **Track Over Time:**
+
+```bash
+# See database size trend
+heroku pg:info -a dubs-server-dev | grep "Data Size"
+
+# Today: 7.93 MB / 1 GB
+# Next week: Should stay similar or grow slowly
+```
+
+### **Alert if Growing Fast:**
+
+```bash
+# If size > 100 MB (10%), investigate:
+heroku pg:psql -a dubs-server-dev -c "
+SELECT 
+  schemaname,
+  tablename,
+  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
+FROM pg_tables
+WHERE schemaname = 'public'
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+"
+```
+
+---
+
+## 💡 Pro Tips
+
+### **Tip 1: Set Up Alerts**
+
+Create a simple alert script:
+
+```bash
+#!/bin/bash
+# check-db-size.sh
+
+SIZE=$(heroku pg:info -a dubs-server-dev | grep "Data Size" | awk '{print $3}')
+LIMIT=500 # Alert if > 500 MB
+
+if (( $(echo "$SIZE > $LIMIT" | bc -l) )); then
+  echo "⚠️ Database size: ${SIZE}MB (exceeds ${LIMIT}MB limit)"
+  # Send alert email/SMS here
+fi
+```
+
+### **Tip 2: Export Before Cleanup**
+
+```bash
+# Backup old data before deleting
+heroku pg:backups:capture -a dubs-server-dev
+heroku pg:backups:download -a dubs-server-dev
+```
+
+### **Tip 3: Monitor Cleanup in Postico**
+
+**Create a "Cleanup Stats" view:**
+```sql
+CREATE VIEW cleanup_stats AS
+SELECT 
+  (SELECT COUNT(*) FROM keeper_actions WHERE timestamp < NOW() - INTERVAL '30 days') as actions_to_clean,
+  (SELECT COUNT(*) FROM keeper_health WHERE timestamp < NOW() - INTERVAL '90 days') as health_to_clean,
+  (SELECT COUNT(*) FROM keeper_rounds WHERE status NOT IN ('resolved','open') AND updated_at < NOW() - INTERVAL '30 days') as rounds_to_clean;
+```
+
+Then query it: `SELECT * FROM cleanup_stats;`
+
+---
+
+## 🎯 Summary
+
+**Your cleanup strategy:**
+
+✅ **Automated** - Runs daily at 3am via Heroku Scheduler  
+✅ **Smart** - Keeps audit data forever, cleans temporary logs  
+✅ **Free** - No additional cost  
+✅ **Safe** - Never deletes user verification data  
+✅ **Tested** - Working in production  
+
+**Current database size:** 7.93 MB / 1 GB (0.77%)  
+**Projected 1-year size:** <50 MB (<5%)  
+**Years until full:** 20+ years  
+
+**You don't need to worry about storage!** But the cleanup is good practice. ✅
+
+---
+
+## 📋 Setup Checklist
+
+- [ ] Add scheduler addon: `heroku addons:create scheduler:standard -a dubs-server-dev`
+- [ ] Open dashboard: `heroku addons:open scheduler -a dubs-server-dev`  
+- [ ] Add job: `node scripts/cleanup-database.js` at 3am daily
+- [ ] Test run: `heroku run node scripts/cleanup-database.js -a dubs-server-dev`
+- [ ] Verify in logs: `heroku logs --ps scheduler -a dubs-server-dev`
+
+**Done in 5 minutes!** ✅
+