Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
194 lines (141 loc) · 4.77 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

194 lines (141 loc) · 4.77 KB

Deployment Guide

This guide explains how to set up GitHub Actions CI/CD for automatic deployment to Cloudflare Workers and Pages.

Repository Setup

Your repository is now private at: https://github.com/ciscoittech/binary-math-system

GitHub Secrets Configuration

To enable automatic deployment, you must add the following secrets to your GitHub repository:

1. Access Repository Settings

2. Required Secrets

Secret Name Description Where to Get
CLOUDFLARE_API_TOKEN API token for Cloudflare Cloudflare Dashboard
CLOUDFLARE_ACCOUNT_ID Your Cloudflare Account ID Cloudflare Dashboard
TURSO_URL Turso database connection URL Turso Dashboard
TURSO_AUTH_TOKEN Turso authentication token Turso Dashboard
OPENROUTER_API_KEY OpenRouter API key (if using AI features) OpenRouter

3. Security Best Practices

⚠️ IMPORTANT: The wrangler.toml file currently contains exposed secrets. You should:

  1. Rotate credentials immediately:

    # Regenerate all tokens in their respective dashboards

  2. Update wrangler.toml to use environment variables:

    [env.production]
routes = [
  { pattern = "api.binarymath.dev", custom_domain = true }
]

[[kv_namespaces]]
binding = "KV"
id = "binary-kv"

  3. Add to .gitignore:

    .env
.env.local
.env.*.local
wrangler.toml.local

CI/CD Pipeline

The workflow file .github/workflows/deploy.yml runs on:

  • Push to main: Full test and deploy
  • Pull requests: Tests only (no deployment)

Pipeline Stages

  1. Test Stage

    • Tests both binary-math-api and binary-math-web
    • Builds both components
    • Runs on all PRs and pushes

  2. Deploy API Stage (main branch only)

    • Builds the Cloudflare Workers API
    • Deploys to production environment
    • Uses npm run build then wrangler deploy --env production

  3. Deploy Web Stage (main branch only)

    • Builds the React/Vite frontend
    • Deploys to Cloudflare Pages
    • Uses wrangler pages deploy

Local Development

Prerequisites

npm install -g wrangler
npm install -g @cloudflare/wrangler

Install Dependencies

# API
cd binary-math-api
npm install

# Web
cd binary-math-web
npm install

Run Tests Locally

# API tests
cd binary-math-api
npm test

# Web tests
cd binary-math-web
npm test

Deploy Locally (Testing)

cd binary-math-api
wrangler deploy --env production

Monitoring Deployments

View Workflow Runs

Troubleshooting

Build Failures

  1. Check the GitHub Actions logs
  2. Verify all dependencies are installed: npm ci
  3. Ensure Node.js version matches (20.x)

Deployment Failures

  1. Verify Cloudflare secrets are set correctly
  2. Check that Cloudflare account is active
  3. Verify custom domain is configured in Cloudflare

Test Failures

  1. Run tests locally: npm test
  2. Check test output for specific failures
  3. Update code and push to retry

Deployment Endpoints

After successful deployment:

Workflow File Reference

The workflow is defined in .github/workflows/deploy.yml and includes:

  • Test Matrix: Tests run in parallel for API and Web
  • Cache: Dependencies are cached for faster builds
  • Conditional Deployment: Only deploys on main branch pushes
  • Status Reporting: Shows deployment status after completion

For Agent-Based Deployments

When using Claude agents to make updates:

  1. Agents commit changes to feature branches
  2. Agents create pull requests (tests run automatically)
  3. Review and merge to main (deployment triggered)
  4. Deployment completes automatically via GitHub Actions

Agent Workflow Integration

# Agent creates branch
git checkout -b agent/feature-name

# Agent makes changes
# Agent commits
git commit -m "feat: description"

# Agent pushes
git push origin agent/feature-name

# Agent creates PR
gh pr create --title "Feature: description"

# PR passes tests automatically
# After merge to main
# GitHub Actions automatically deploys

Support

For issues with:

Last Updated: 2025-10-15