cloud-orchestrator/DEPLOYMENT.md

Deployment Checklist

Complete checklist for deploying the Server Recommendation System to Cloudflare Workers.

---

Pre-Deployment Checklist

Development Environment ✅

• Node.js 18+ installed
• Dependencies installed (npm install)
• TypeScript compilation passes (npm run typecheck)
• Code structure verified

Cloudflare Account

• Cloudflare account created/logged in
• Wrangler CLI authenticated (npx wrangler login)

---

Step-by-Step Deployment

Step 1: Create D1 Database (2 minutes)

# Create database
npx wrangler d1 create server-recommend-db

Expected Output:

✅ Successfully created DB 'server-recommend-db'!

[[d1_databases]]
binding = "DB"
database_name = "server-recommend-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Action Required:

• Copy the database_id value
• Open wrangler.toml
• Replace empty database_id = "" with your actual ID
• Save file

---

Step 2: Create KV Namespace (1 minute)

# Create KV namespace
npx wrangler kv:namespace create CACHE

Expected Output:

🌀 Creating namespace with title "server-recommend-CACHE"
✨ Success!
Add the following to your configuration file:

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

Action Required:

• Copy the id value
• Open wrangler.toml
• Replace empty id = "" with your actual ID
• Save file

Verify wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "server-recommend-db"
database_id = "YOUR_ACTUAL_DATABASE_ID"  # ← Should be filled

[[kv_namespaces]]
binding = "CACHE"
id = "YOUR_ACTUAL_KV_ID"  # ← Should be filled

---

Step 3: Initialize Database (2 minutes)

# Create tables and indexes
npx wrangler d1 execute server-recommend-db --file=schema.sql

Expected Output:

🌀 Mapping SQL input into an array of statements
🌀 Executing on server-recommend-db (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):
🚣 Executed 7 commands in X.XXXs

Checklist:

• Command executed successfully
• No errors in output
• Tables created (providers, servers, server_regions)
• Indexes created

Verify:

# Check tables
npx wrangler d1 execute server-recommend-db --command "SELECT name FROM sqlite_master WHERE type='table'"

---

Step 4: Seed Sample Data (1 minute)

# Insert sample server data
npx wrangler d1 execute server-recommend-db --file=seed.sql

Expected Output:

🌀 Mapping SQL input into an array of statements
🌀 Executing on server-recommend-db (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):
🚣 Executed XX commands in X.XXXs

Verify:

# Check row counts
npx wrangler d1 execute server-recommend-db --command "SELECT COUNT(*) as count FROM servers"

Expected: count = 13 (sample data includes 13 servers)

Checklist:

• Command executed successfully
• 4 providers inserted
• 13 servers inserted
• Regional data inserted

---

Step 5: Local Testing (2 minutes)

# Start development server
npm run dev

Expected Output:

⛅️ wrangler 4.60.0
-------------------
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787

In another terminal:

# Run test suite
./test.sh

Or manual tests:

# Health check
curl http://localhost:8787/api/health

# List servers
curl http://localhost:8787/api/servers | jq .

# Get recommendation
curl -X POST http://localhost:8787/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "cpu_cores": 2,
    "memory_gb": 4,
    "storage_gb": 80
  }' | jq .

Checklist:

• Health endpoint returns 200
• Servers endpoint returns data
• Recommend endpoint works
• AI generates recommendations
• Cache works (second request faster)
• No errors in console

---

Step 6: Deploy to Production (1 minute)

# Deploy to Cloudflare Workers
npm run deploy

Expected Output:

⛅️ wrangler 4.60.0
-------------------
Total Upload: XX.XX KiB / gzip: XX.XX KiB
Uploaded server-recommend (X.XX sec)
Published server-recommend (X.XX sec)
  https://server-recommend.YOUR_SUBDOMAIN.workers.dev
Current Deployment ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Action Required:

• Copy the deployed worker URL
• Save it for testing

Checklist:

• Deployment successful
• Worker URL obtained
• No deployment errors

---

Step 7: Production Testing (2 minutes)

Replace with your actual worker URL:

export WORKER_URL="https://server-recommend.YOUR_SUBDOMAIN.workers.dev"

Run tests:

# Test with your URL
./test.sh $WORKER_URL

# Or manual tests
curl $WORKER_URL/api/health

curl "$WORKER_URL/api/servers?minCpu=4"

curl -X POST $WORKER_URL/api/recommend \
  -H "Content-Type: application/json" \
  -d @test-request.json | jq .

Checklist:

• Health check works
• Server listing works
• Recommendations work
• Response times acceptable
• No 500 errors

---

Step 8: Monitor Deployment (Ongoing)

# View real-time logs
npx wrangler tail

Cloudflare Dashboard:

1. Go to https://dash.cloudflare.com/
2. Navigate to Workers & Pages
3. Click on server-recommend
4. View metrics:
   • Request rate
   • Success rate
   • Errors
   • Invocation duration

---

Post-Deployment Verification

Functional Tests

• ✅ Health endpoint: GET /api/health
• ✅ Server list: GET /api/servers
• ✅ Server filtering: GET /api/servers?minCpu=4&minMemory=8
• ✅ Recommendations: POST /api/recommend
• ✅ Cache working (second request faster)
• ✅ CORS headers present
• ✅ Error handling works

Performance Tests

• Cold start: < 100ms
• Cached response: < 100ms
• AI response: 2-5s (first request)
• Database query: < 50ms

Security Tests

• Input validation working
• SQL injection protected
• Error messages safe
• CORS properly configured

---

Troubleshooting

Issue: "Database not found"

Solution:

1. Verify database_id in wrangler.toml
2. List databases: npx wrangler d1 list
3. Re-create if needed: npx wrangler d1 create server-recommend-db

Issue: "KV namespace not found"

Solution:

1. Verify id in wrangler.toml
2. List namespaces: npx wrangler kv:namespace list
3. Re-create if needed: npx wrangler kv:namespace create CACHE

Issue: "No servers found"

Solution:

1. Verify seed data: npx wrangler d1 execute server-recommend-db --command "SELECT COUNT(*) FROM servers"
2. Re-seed if needed: npx wrangler d1 execute server-recommend-db --file=seed.sql

Issue: "Workers AI error"

Solution:

1. Workers AI is automatic, no configuration needed
2. Check quota in Cloudflare dashboard
3. Verify model name: @cf/meta/llama-3.1-8b-instruct

Issue: "Deployment fails"

Solution:

1. Check wrangler.toml syntax
2. Verify all IDs filled
3. Run npm run typecheck
4. Check authentication: npx wrangler whoami

---

Rollback Procedure

If deployment has issues:

# Rollback to previous deployment
npx wrangler rollback

# Or deploy specific version
npx wrangler rollback --deployment-id <DEPLOYMENT_ID>

---

Success Criteria

Deployment is successful when:

✅ All 3 API endpoints return 200 status
✅ AI recommendations generated correctly
✅ Cache hit rate > 0% after multiple requests
✅ No 500 errors in logs
✅ Response times within targets
✅ Database queries working
✅ Sample data accessible

---

Next Steps After Deployment

Immediate

1. Test all endpoints thoroughly
2. Monitor logs for errors
3. Verify cache working
4. Document worker URL

Short Term (1 week)

1. Add production server data
2. Monitor usage and performance
3. Set up alerts for errors
4. Adjust cache TTL if needed

Long Term (1 month)

1. Implement rate limiting
2. Add authentication
3. Set up custom domain
4. Enhance AI prompts
5. Add analytics
6. Create admin interface

---

Resource Limits Checklist

Free Tier (Daily Limits)

• Workers: < 100,000 requests/day
• Workers AI: < 10,000 neurons/day
• D1: < 5M reads/day, < 100K writes/day
• KV: < 100,000 reads/day, < 1,000 writes/day

Monitoring Alerts

Set up alerts for:

• Request rate > 80% of limit
• Error rate > 1%
• Response time > 5s (95th percentile)
• AI quota > 80% usage

---

Support Resources

• Cloudflare Workers Docs: https://developers.cloudflare.com/workers/
• Workers AI Docs: https://developers.cloudflare.com/workers-ai/
• D1 Docs: https://developers.cloudflare.com/d1/
• Community Discord: https://discord.gg/cloudflaredev
• Status Page: https://www.cloudflarestatus.com/

---

Deployment Complete! 🎉

When all checkboxes are marked:

• ✅ Worker deployed successfully
• ✅ All endpoints tested
• ✅ Monitoring in place
• ✅ No errors detected

Your Server Recommendation System is now LIVE!

Worker URL: https://server-recommend.YOUR_SUBDOMAIN.workers.dev

Share this URL with users to start receiving recommendations!