> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Deployment Workflows
> Learn proven workflows for deploying changes from dev to staging to production safely using KnoxCall environments.
# Environment Deployment Workflows
Learn proven workflows for safely deploying changes from development to production using KnoxCall environments.
## Standard Three-Tier Workflow
```text theme={"dark"}
Development → Staging → Production
```
This is the most common deployment pattern used by successful teams.
### Workflow Overview
| Environment | Purpose | Stability | Users |
| --------------- | ------------------------------------ | ----------- | --------------------- |
| **Development** | Feature development, experimentation | Unstable | Developers |
| **Staging** | Pre-production testing, QA | Stable | QA team, stakeholders |
| **Production** | Live customer-facing system | Very stable | End users |
## How KnoxCall Makes This Easy
With KnoxCall, you don't need to change code or redeploy your client applications to switch environments.
**Traditional approach:**
```javascript theme={"dark"}
// Code changes needed
const API_URL = process.env.NODE_ENV === 'prod'
? 'https://api.prod.com'
: 'https://api.dev.com';
```
**With KnoxCall:**
```javascript theme={"dark"}
// No code changes - just header
const headers = {
"x-knoxcall-key": API_KEY,
"x-knoxcall-route": "my-api",
"x-knoxcall-environment": "staging" // Change only this
};
```
Same code, different backend via header!
## Deployment Process
### Step 1: Develop in Development
**What:** Make code changes and test locally
**KnoxCall setup:**
* Environment: `development`
* Target URL: `http://localhost:3000`
* Secrets: Dev API keys
* Clients: Your laptop IP
* Rate limits: Unlimited
**Test your changes:**
```bash theme={"dark"}
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"}'
```
Routes to: `http://localhost:3000/api/users`
**Iterate quickly:**
* Make changes to local backend
* Test immediately
* No deployment needed
### Step 2: Promote to Staging
**What:** Deploy backend to staging server, run full QA
**KnoxCall setup:**
* 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 backend:**
```bash theme={"dark"}
# Deploy your backend to staging server
git push staging main
# Or: deploy via CI/CD
```
**Test with staging environment:**
```bash theme={"dark"}
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"}'
```
Routes to: `https://staging-api.yourcompany.com/api/users`
**Staging checklist:**
* [ ] 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
**What:** Deploy to live environment after thorough testing
**KnoxCall setup:**
* 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 backend:**
```bash theme={"dark"}
# Deploy to production
git push production main
# Or: deploy via CI/CD with approval gate
```
**Production requests** (no environment header needed):
```bash theme={"dark"}
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"}'
```
Routes to: `https://api.yourcompany.com/api/users` (default/base environment)
**Post-deployment monitoring:**
* [ ] 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
**Development:** Relaxed for testing
```text theme={"dark"}
Rate limit: 10,000 requests/minute (or unlimited)
Purpose: Allow rapid iteration
```
**Staging:** Moderate limits
```text theme={"dark"}
Rate limit: 1,000 requests/minute
Purpose: Test rate limiting behavior, allow load testing
```
**Production:** Strict protection
```text theme={"dark"}
Rate limit: 100 requests/minute per client
Purpose: Protect backend from abuse
```
**Configure in KnoxCall:**
1. Edit route
2. Go to **Environment** tab
3. Set different `rate_limit_requests` and `rate_limit_window_sec` per environment
### Different Secrets Per Environment
Use environment-specific secrets for security:
**Development route override:**
```json theme={"dark"}
{
"inject_headers": {
"Authorization": "Bearer {{secret:stripe_dev_key}}"
}
}
```
**Staging route override:**
```json theme={"dark"}
{
"inject_headers": {
"Authorization": "Bearer {{secret:stripe_staging_key}}"
}
}
```
**Production (base route):**
```json theme={"dark"}
{
"inject_headers": {
"Authorization": "Bearer {{secret:stripe_prod_key}}"
}
}
```
Now each environment uses its own Stripe key automatically!
### Different Monitoring Thresholds
**Development:** No alerts (expect errors during development)
**Staging:** Warning-level alerts
* Alert if error rate > 20%
* Alert if P95 latency > 5 seconds
* Send to Slack `#staging-alerts` channel
**Production:** Critical alerts
* Alert if error rate > 5%
* Alert if P95 latency > 1 second
* Send to PagerDuty for on-call rotation
* Send to Slack `#production-alerts` channel
**Configure in KnoxCall:**
1. Navigate to **Alerts**
2. Create alert rules with environment filters
3. Set different thresholds per environment
4. Configure notification channels
## Rollback Strategy
If production deployment fails, you can roll back instantly without code changes.
### Quick Rollback via Environment Override
**Scenario:** New backend version (v2) has critical bug
**Option 1: Point production to old backend**
1. Edit route → **Environment** tab
2. Add override for "production" environment
3. Set target URL to old backend:
```
https://api-v1.yourcompany.com (old version)
```
4. Save
Traffic instantly goes to old backend. No code changes needed!
**Option 2: Switch production to use staging**
Temporarily point production traffic to staging backend:
1. Edit route → **Environment** tab
2. Override production target URL:
```
https://staging-api.yourcompany.com
```
3. Save
This buys time to fix the bug while serving from last known good version.
### Full Rollback Workflow
```text theme={"dark"}
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
For large features, create temporary environments:
**Example: New payment system**
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
**Benefits:**
* Test big changes safely
* Don't interfere with staging
* Easy cleanup after merge
### Canary Deployments
Gradually roll out to production:
**Phase 1: Internal testing (5% of traffic)**
```text theme={"dark"}
Environment: production-canary
Target: https://api-v2.yourcompany.com (new version)
Clients: Internal testing IPs only
```
**Phase 2: Beta users (20% of traffic)**
```text theme={"dark"}
Environment: production-beta
Target: https://api-v2.yourcompany.com
Clients: Beta tester IPs
```
**Phase 3: Full rollout (100% of traffic)**
```text theme={"dark"}
Environment: production (base)
Target: https://api-v2.yourcompany.com
Clients: All production IPs
```
### Blue-Green Deployments
Run two identical production environments:
**Blue (current production):**
```text theme={"dark"}
Environment: production
Target: https://api-blue.yourcompany.com (v1.5)
```
**Green (new version):**
```text theme={"dark"}
Environment: production-green
Target: https://api-green.yourcompany.com (v1.6)
```
**Switch traffic:** Update base route to point to green
**Instant rollback:** Switch back to blue if issues
### Regional Environments
For global applications, route by region:
```text theme={"dark"}
production-us-east
production-us-west
production-eu-west
production-asia-pacific
```
Client application determines region and sets environment header accordingly.
**Benefits:**
* 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
Create a dashboard showing all environments side-by-side:
| Metric | Development | Staging | Production |
| ------------------ | -------------- | ------- | ---------- |
| **Request volume** | 50/min | 500/min | 5,000/min |
| **Error rate** | 15% (expected) | 2% | 0.5% |
| **P95 latency** | 2s | 500ms | 200ms |
| **Success rate** | 85% | 98% | 99.5% |
**In KnoxCall:**
1. Navigate to **Analytics**
2. Group by "Environment"
3. Compare metrics across environments
4. Spot differences between staging and production
### Environment Health Dashboard
Monitor the overall health of each environment:
```text theme={"dark"}
✅ 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
**Symptoms:** Made changes, but staging still shows old behavior
**Possible causes:**
1. Backend not deployed yet
2. Wrong environment header in request
3. Caching (client-side or CDN)
4. Environment override not configured
**Debug steps:**
```bash theme={"dark"}
# 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 tab → select Staging
# Check target URL is correct
```
### Different Behavior Between Environments
**Symptoms:** Works in staging, fails in production
**Possible causes:**
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
**Debug checklist:**
* [ ] 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
Before each production deployment, complete this 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
✅ **Do:**
* 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
❌ **Don't:**
* 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
Now that you understand deployment workflows:
Set up environment-specific alerts
Manage secrets per environment
Configure limits per environment
Track configuration changes
## Related Concepts
* **Base Route**: Default production configuration
* **Environment Override**: Environment-specific settings (NULL = inherit)
* **Default Environment**: Used when no header specified
* **Per-environment clients**: IP whitelist per environment
* **Rollback**: Point route to previous backend version
***
* **Level**: intermediate
* **Time**: 15 minutes
`environments`, `deployment`, `workflows`, `devops`, `staging`