​

Environment Deployment Workflows

​

Standard Three-Tier Workflow

Development → Staging → Production

​

Workflow Overview

​

How KnoxCall Makes This Easy

// Code changes needed
const API_URL = process.env.NODE_ENV === 'prod'
  ? 'https://api.prod.com'
  : 'https://api.dev.com';

// No code changes - just header
const headers = {
  "x-knoxcall-key": API_KEY,
  "x-knoxcall-route": "my-api",
  "x-knoxcall-environment": "staging"  // Change only this
};

​

Deployment Process

​

Step 1: Develop in Development

• Environment: development
• Target URL: http://localhost:3000
• Secrets: Dev API keys
• Clients: Your laptop IP
• Rate limits: Unlimited

curl -X POST "https://a1b2c3d4.DunderMifflin.knoxcall.com/api/users" \
  -H "x-knoxcall-key: tk_dev_..." \
  -H "x-knoxcall-route: user-api" \
  -H "x-knoxcall-environment: development" \
  -d '{"name": "Test User"}'

• Make changes to local backend
• Test immediately
• No deployment needed

​

Step 2: Promote to Staging

• Environment: staging
• Target URL: https://staging-api.yourcompany.com
• Secrets: Staging API keys
• Clients: Staging server IPs, QA team IPs
• Rate limits: Moderate (1000/min)

# Deploy your backend to staging server
git push staging main
# Or: deploy via CI/CD

curl -X POST "https://a1b2c3d4.DunderMifflin.knoxcall.com/api/users" \
  -H "x-knoxcall-key: tk_staging_..." \
  -H "x-knoxcall-route: user-api" \
  -H "x-knoxcall-environment: staging" \
  -d '{"name": "Test User"}'

• All unit tests pass
• Integration tests pass
• Manual QA completed
• Performance acceptable
• Security scan passed
• No critical bugs
• Stakeholder approval

​

Step 3: Deploy to Production

• Environment: production (base environment)
• Target URL: https://api.yourcompany.com
• Secrets: Production API keys
• Clients: Production server IPs only
• Rate limits: Strict (100/min)

# Deploy to production
git push production main
# Or: deploy via CI/CD with approval gate

curl -X POST "https://a1b2c3d4.DunderMifflin.knoxcall.com/api/users" \
  -H "x-knoxcall-key: tk_prod_..." \
  -H "x-knoxcall-route: user-api" \
  -d '{"name": "Real User"}'

• Monitor error rates in KnoxCall dashboard
• Check response times
• Watch for spike in 5xx errors
• Verify no increase in failed requests
• Monitor user reports/support tickets

​

Environment-Specific Configuration

​

Different Rate Limits Per Environment

Rate limit: 10,000 requests/minute (or unlimited)
Purpose: Allow rapid iteration

Rate limit: 1,000 requests/minute
Purpose: Test rate limiting behavior, allow load testing

Rate limit: 100 requests/minute per client
Purpose: Protect backend from abuse

1. Edit route
2. Go to Environment Overrides tab
3. Set different rate_limit_requests and rate_limit_window per environment

​

Different Secrets Per Environment

{
  "inject_headers": {
    "Authorization": "Bearer {{secret:stripe_dev_key}}"
  }
}

{
  "inject_headers": {
    "Authorization": "Bearer {{secret:stripe_staging_key}}"
  }
}

{
  "inject_headers": {
    "Authorization": "Bearer {{secret:stripe_prod_key}}"
  }
}

​

Different Monitoring Thresholds

• Alert if error rate > 20%
• Alert if P95 latency > 5 seconds
• Send to Slack #staging-alerts channel

• Alert if error rate > 5%
• Alert if P95 latency > 1 second
• Send to PagerDuty for on-call rotation
• Send to Slack #production-alerts channel

1. Navigate to Alerts
2. Create alert rules with environment filters
3. Set different thresholds per environment
4. Configure notification channels

​

Rollback Strategy

​

Quick Rollback via Environment Override

1. Edit route → Environment Overrides
2. Add override for “production” environment
3. Set target URL to old backend:
   Copy

   https://api-v1.yourcompany.com (old version)
   
4. Save

1. Edit route → Environment Overrides
2. Override production target URL:
   Copy

   https://staging-api.yourcompany.com
   
3. Save

​

Full Rollback Workflow

1. Identify issue in production
     ↓
2. Immediately rollback route to old backend URL
     ↓
3. Investigate issue in staging
     ↓
4. Fix bug and test in development
     ↓
5. Validate fix in staging
     ↓
6. Redeploy to production
     ↓
7. Update route back to new backend URL

​

Advanced Deployment Patterns

​

Feature Branch Environments

1. Create environment: feature-payment-v2
2. Configure route override:
   • Target URL: https://payment-v2-api.yourcompany.com
   • Secrets: payment_v2_api_key
3. Test feature branch in isolation
4. After merge: Delete feature-payment-v2 environment

• Test big changes safely
• Don’t interfere with staging
• Easy cleanup after merge

​

Canary Deployments

Environment: production-canary
Target: https://api-v2.yourcompany.com (new version)
Clients: Internal testing IPs only

Environment: production-beta
Target: https://api-v2.yourcompany.com
Clients: Beta tester IPs

Environment: production (base)
Target: https://api-v2.yourcompany.com
Clients: All production IPs

​

Blue-Green Deployments

Environment: production
Target: https://api-blue.yourcompany.com (v1.5)

Environment: production-green
Target: https://api-green.yourcompany.com (v1.6)

​

Regional Environments

production-us-east
production-us-west
production-eu-west
production-asia-pacific

• Data sovereignty compliance
• Reduced latency (users hit closest region)
• Region-specific deployments
• Isolated failures (one region down doesn’t affect others)

​

Monitoring Across Environments

​

Compare Metrics Dashboard

1. Navigate to Analytics
2. Group by “Environment”
3. Compare metrics across environments
4. Spot differences between staging and production

​

Environment Health Dashboard

✅ Development: Healthy (expected errors during dev)
⚠️  Staging: Warning - High error rate (needs investigation)
🔴 Production: Critical - Service degraded (page on-call)

​

Troubleshooting Deployment Issues

​

Changes Not Showing in Staging

1. Backend not deployed yet
2. Wrong environment header in request
3. Caching (client-side or CDN)
4. Environment override not configured

# 1. Verify backend deployment
ssh staging-server
ps aux | grep myapp
curl localhost:3000/health

# 2. Test with correct header
curl https://a1b2c3d4.DunderMifflin.knoxcall.com/api/users \
  -H "x-knoxcall-environment: staging" \
  -H "x-knoxcall-key: tk_..." \
  -H "x-knoxcall-route: my-api"

# 3. Check KnoxCall logs
# Go to Logs → Filter by environment: staging
# Verify request hit staging backend

# 4. Verify environment override
# Routes → Your Route → Environment Overrides → Staging
# Check target URL is correct

​

Different Behavior Between Environments

1. Different secrets (dev keys vs prod keys)
2. Different backend code versions
3. Different environment variables
4. Different database state
5. Different rate limits causing throttling

• Compare route configurations (base vs overrides)
• Verify secrets are environment-specific
• Check backend versions match
• Compare environment variables
• Review rate limit settings
• Check database schema versions

​

Pre-Deployment Checklist

​

Pre-Deployment

• All tests passing in staging
• Stakeholder approval received
• Rollback plan documented
• Team notified in Slack
• Monitoring dashboard ready
• On-call engineer identified
• Database migrations tested (if any)
• Feature flags configured (if applicable)

​

During Deployment

• Deploy backend to production
• Verify health endpoint responds
• Test critical user flows manually
• Monitor error rates in real-time
• Check latency metrics
• Review first 100 production requests

​

Post-Deployment

• Monitor for 30 minutes
• Review error logs (should be stable)
• Check analytics (traffic patterns normal)
• Verify zero increase in support tickets
• Update team status: “Deployment successful”
• Update documentation (if needed)
• Mark deployment as stable in tracking system

​

Best Practices Summary

• Always test in development first
• Require QA approval for staging → production
• Set production as default environment
• Use different API keys per environment
• Monitor each environment separately
• Document rollback procedures
• Keep staging close to production config
• Run load tests in staging

• Deploy directly to production without staging
• Use production API keys in development
• Skip the staging environment (“it’s just a small change”)
• Forget to monitor after deployment
• Make manual changes directly in production
• Test in production (use staging!)

​

Next Steps

​

Related Concepts

• Base Route: Default production configuration
• Environment Override: Environment-specific settings (NULL = inherit)
• Default Environment: Used when no header specified
• Environment Clients: IP whitelist per environment
• Rollback: Point route to previous backend version