Skip to content

DEPLOYMENT_CHECKLIST.md

Latest commit

 

History

History
329 lines (245 loc) · 9.37 KB

DEPLOYMENT_CHECKLIST.md

File metadata and controls

329 lines (245 loc) · 9.37 KB

ZanyCuts SEO Desk - Deployment Checklist

Pre-Deployment Verification

1. Environment Variables

  • All required variables set in .env (local) or Cloud Run config (production)
  • GOOGLE_CLIENT_ID is valid
  • GOOGLE_CLIENT_SECRET is valid
  • GOOGLE_REFRESH_TOKEN is valid and not revoked
  • GSC_PROPERTY_URL matches Search Console property exactly
  • GBP_LOCATION_NAME uses correct format: accounts/{id}/locations/{id}
  • GA4_MEASUREMENT_ID is correct (format: G-XXXXXXXXXX)
  • GA4_API_SECRET is valid
  • (Optional) Google Ads variables if using keyword features

2. OAuth Setup

  • OAuth consent screen configured in Google Cloud Console
  • Required scopes enabled:
    • https://www.googleapis.com/auth/webmasters.readonly
    • https://www.googleapis.com/auth/business.manage
  • Refresh token obtained through OAuth flow
  • Test account has access to all required Google properties

3. API Access

  • Search Console API enabled in Google Cloud Project
  • Google My Business API enabled
  • PageSpeed Insights API enabled
  • Google Analytics Data API enabled
  • (Optional) Google Ads API enabled

4. Local Testing

Run these commands to verify all endpoints work locally:

# Start server
npm run dev

# 1. Health Check
curl http://localhost:3000/health
# Expected: {"status":"healthy","version":"1.0.0",...}

# 2. Search Console Queries
curl http://localhost:3000/get_gsc_queries
# Expected: Array of queries with localIntent flags

# 3. Page Copy Generation
curl -X POST http://localhost:3000/compose_page_copy \
  -H "Content-Type: application/json" \
  -d '{"query":"kids haircuts newnan ga","targetUrl":"https://zanycuts.com/test"}'
# Expected: Complete SEO copy object with all fields

# 4. Fetch Reviews
curl http://localhost:3000/fetch_reviews?limit=3
# Expected: Array of reviews with suggested replies

# 5. PageSpeed Check
curl -X POST http://localhost:3000/check_pagespeed \
  -H "Content-Type: application/json" \
  -d '{"url":"https://zanycuts.com","strategy":"mobile"}'
# Expected: Metrics object with LCP, CLS, INP

# 6. GA4 Event (Test Event)
curl -X POST http://localhost:3000/send_ga4_event \
  -H "Content-Type: application/json" \
  -d '{"eventName":"test_event","params":{"test":"true"}}'
# Expected: {"success":true,"clientId":"gen_..."}

# 7. GBP Post (DRAFT - Don't publish to production)
curl -X POST http://localhost:3000/write_gbp_post \
  -H "Content-Type: application/json" \
  -d '{"message":"Test post from SEO Desk - please ignore this test post."}'
# Expected: {"success":true,"postName":"...","publishTime":"..."}
# NOTE: Delete this test post from GBP manually after testing

# 8. (Optional) Keyword Ideas
curl -X POST http://localhost:3000/get_keyword_ideas \
  -H "Content-Type: application/json" \
  -d '{"seedKeywords":["kids haircuts"],"locations":["Newnan, GA"]}'
# Expected: Array of keyword ideas with volume and CPC

5. GA4 Verification

  • Go to GA4 > Admin > Data Streams > Measurement Protocol API secrets
  • Verify API secret matches GA4_API_SECRET
  • Send a test event using /send_ga4_event
  • Check GA4 DebugView within 5-10 minutes
  • Confirm event appears with correct parameters

6. Code Quality

  • Run npm run lint - No errors
  • Run npm run format - All files formatted
  • Run npm run build - TypeScript compiles successfully
  • No console.log statements in production code (only console.info, console.warn, console.error)
  • No hardcoded secrets in code
  • All files under 300 lines (cursor rules compliance)

Cloud Run Deployment

1. Build and Deploy

# Authenticate
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# Deploy (first time)
gcloud run deploy zanycutsdesk \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi \
  --cpu 1 \
  --timeout 60 \
  --set-env-vars NODE_ENV=production

# Get service URL
gcloud run services describe zanycutsdesk \
  --region us-central1 \
  --format 'value(status.url)'

2. Set Environment Variables

gcloud run services update zanycutsdesk \
  --region us-central1 \
  --update-env-vars \
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com,\
    GOOGLE_CLIENT_SECRET=your-client-secret,\
    GOOGLE_REFRESH_TOKEN=1//your-refresh-token,\
    GSC_PROPERTY_URL=sc-domain:zanycuts.com,\
    GBP_LOCATION_NAME=accounts/123456789/locations/987654321,\
    GA4_MEASUREMENT_ID=G-XXXXXXXXXX,\
    GA4_API_SECRET=your-api-secret

3. Test Production Deployment

Replace YOUR_CLOUD_RUN_URL with your actual Cloud Run service URL:

CLOUD_RUN_URL="https://zanycutsdesk-xxxxx-uc.a.run.app"

# Health check
curl $CLOUD_RUN_URL/health

# Test Search Console
curl $CLOUD_RUN_URL/get_gsc_queries

# Test copy generation
curl -X POST $CLOUD_RUN_URL/compose_page_copy \
  -H "Content-Type: application/json" \
  -d '{"query":"kids haircuts newnan ga","targetUrl":"https://zanycuts.com/test"}'

4. OpenAI Apps SDK Registration

  • Go to ChatGPT Settings > Apps (or your OpenAI Apps interface)
  • Click "Create new app"
  • Name: ZanyCuts SEO Desk
  • Base URL: Your Cloud Run URL (e.g., https://zanycutsdesk-xxxxx-uc.a.run.app)
  • Authentication: None (OAuth handled server-side)
  • Import tool definitions from src/client/app.ts (TOOLS array)
  • Test each tool in ChatGPT interface:
    • get_gsc_queries
    • compose_page_copy
    • fetch_reviews
    • reply_to_review
    • write_gbp_post
    • check_pagespeed
    • send_ga4_event
    • (Optional) get_keyword_ideas
    • (Optional) add_negative_keywords

5. Monitor Logs

# Stream logs
gcloud run services logs tail zanycutsdesk --region us-central1

# Check for errors
gcloud run services logs read zanycutsdesk \
  --region us-central1 \
  --filter 'severity>=ERROR' \
  --limit 50

Post-Deployment

1. Staff Training

  • Show staff how to access the tool in ChatGPT
  • Walk through Flow 1: Content and GBP Post
  • Walk through Flow 2: Reviews and Reputation
  • Walk through Flow 3: Speed and Health
  • Explain when to use each flow
  • Show how to edit generated copy before publishing
  • Emphasize: Always review GBP posts before publishing

2. Monitoring

  • Set up Cloud Logging alerts for errors
  • Monitor API usage quotas (Search Console, GBP, PageSpeed)
  • Check GA4 for incoming events
  • Review GBP posts for quality
  • Collect staff feedback after 1 week

3. Optimization

  • Review most-used features
  • Optimize slow endpoints (if any)
  • Add caching for frequently accessed data (if needed)
  • Update content templates based on staff feedback

Rollback Plan

If issues occur in production:

# List recent revisions
gcloud run revisions list --service zanycutsdesk --region us-central1

# Rollback to previous revision
gcloud run services update-traffic zanycutsdesk \
  --region us-central1 \
  --to-revisions REVISION_NAME=100

Common Issues and Solutions

Issue: OAuth Refresh Failed

Symptoms: OAUTH_REFRESH_FAILED errors in logs

Solutions:

  1. Verify refresh token hasn't been revoked in Google Account settings
  2. Check Client ID and Client Secret are correct
  3. Re-run OAuth flow to get new refresh token
  4. Update GOOGLE_REFRESH_TOKEN in Cloud Run config

Issue: GSC Unauthorized

Symptoms: GSC_UNAUTHORIZED or 403 errors

Solutions:

  1. Verify OAuth account has Search Console access
  2. Check GSC_PROPERTY_URL exactly matches property in Search Console
  3. Ensure OAuth scope includes webmasters.readonly

Issue: GBP Location Not Found

Symptoms: GBP_LOCATION_NOT_FOUND or 404 errors

Solutions:

  1. Verify GBP_LOCATION_NAME format: accounts/{account_id}/locations/{location_id}
  2. Use GBP API to list locations and confirm IDs
  3. Ensure OAuth account has management access

Issue: GA4 Events Not Appearing

Symptoms: Events sent successfully but not in GA4

Solutions:

  1. Wait 5-10 minutes (events can be delayed)
  2. Check DebugView instead of Realtime reports
  3. Verify GA4_MEASUREMENT_ID and GA4_API_SECRET
  4. Use /send_ga4_event with debug: true for validation

Issue: PageSpeed Timeout

Symptoms: PAGESPEED_TIMEOUT errors

Solutions:

  1. Retry with same URL (may be temporary)
  2. Try desktop strategy instead of mobile
  3. Check if URL is accessible publicly

Security Review

  • No secrets in code or Git history
  • .env file in .gitignore
  • Cloud Run environment variables encrypted at rest
  • OAuth refresh token rotated periodically (every 6 months)
  • API quotas set appropriately to prevent abuse
  • Service only accessible via HTTPS
  • No PII logged in application logs
  • Review access limited to authorized staff

Compliance Checklist

  • Family-friendly tone in all generated content
  • UTM parameters consistent across all GBP links
  • "Newnan, GA" included in all required SEO fields
  • Internal links present in all generated copy
  • Review replies sound human and not templated
  • No automated changes to Google Ads budgets (as designed)
  • GA4 events include no PII

Deployment Date: _____________

Deployed By: _____________

Cloud Run URL: _____________

ChatGPT App Name: ZanyCuts SEO Desk

Status: ☐ Testing | ☐ Production | ☐ Rollback Required