{"slug":"operations/05_DEPLOYMENT_ENVIRONMENT","title":"IntegrateWise Deployment & Environment Guide","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/05_DEPLOYMENT_ENVIRONMENT.mdx","bytes":23426,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## CI/CD, Release Management, and Infrastructure\n\n**Version:** 1.0  \n**Classification:** Internal Engineering  \n**Last Updated:** January 2026\n\n---\n\n# Table of Contents\n\n1. [Environment Overview](#1-environment-overview)\n2. [CI/CD Pipeline](#2-cicd-pipeline)\n3. [Deployment Process](#3-deployment-process)\n4. [Release Checklist](#4-release-checklist)\n5. [Feature Flags](#5-feature-flags)\n6. [Rollback Procedures](#6-rollback-procedures)\n7. [Versioning Policy](#7-versioning-policy)\n8. [Database Migrations](#8-database-migrations)\n9. [Secret Management](#9-secret-management)\n\n---\n\n# 1. Environment Overview\n\n## 1.1 Environment Summary\n\n| Environment     | Purpose                | URL                          | Branch      |\n| --------------- | ---------------------- | ---------------------------- | ----------- |\n| **Development** | Local development      | localhost:3000               | feature/\\*  |\n| **Preview**     | PR previews            | \\*.preview.integratewise.com | PR branches |\n| **Staging**     | Pre-production testing | staging.integratewise.com    | staging     |\n| **Production**  | Live customers         | app.integratewise.com        | main        |\n\n## 1.2 Environment Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                      ENVIRONMENT ARCHITECTURE                                │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     DEVELOPMENT            STAGING                PRODUCTION\n     ───────────            ───────                ──────────\n\n     ┌───────────┐         ┌───────────┐         ┌───────────┐\n     │  Local    │         │ Cloudflare│         │ Cloudflare│\n     │  Dev      │         │  Workers  │         │  Workers  │\n     │  Server   │         │ (Staging) │         │ (Prod)    │\n     └─────┬─────┘         └─────┬─────┘         └─────┬─────┘\n           │                     │                     │\n           ▼                     ▼                     ▼\n     ┌───────────┐         ┌───────────┐         ┌───────────┐\n     │  Local    │         │ Supabase  │         │ Supabase  │\n     │  Supabase │         │  Staging  │         │   Prod    │\n     │  (Docker) │         │ (Project) │         │ (Project) │\n     └───────────┘         └───────────┘         └───────────┘\n           │                     │                     │\n           ▼                     ▼                     ▼\n     ┌───────────┐         ┌───────────┐         ┌───────────┐\n     │  Seed     │         │  Staging  │         │  Live     │\n     │  Data     │         │  Data     │         │  Data     │\n     └───────────┘         └───────────┘         └───────────┘\n```\n\n## 1.3 Environment Configuration\n\n| Config            | Development | Staging  | Production |\n| ----------------- | ----------- | -------- | ---------- |\n| **Debug mode**    | Enabled     | Enabled  | Disabled   |\n| **Logging level** | Debug       | Info     | Warn       |\n| **Rate limits**   | Disabled    | Reduced  | Full       |\n| **External APIs** | Sandbox     | Sandbox  | Live       |\n| **Email sending** | Console     | Mailtrap | Production |\n| **AI providers**  | Mock/Live   | Live     | Live       |\n\n## 1.4 Environment Variables\n\n```bash\n# Base configuration\nNODE_ENV=production|staging|development\nAPP_URL=https://app.integratewise.com\nAPI_URL=https://api.integratewise.com\n\n# Database\nSUPABASE_URL=https://xxx.supabase.co\nSUPABASE_ANON_KEY=eyJ...\nSUPABASE_SERVICE_KEY=eyJ...\nDATABASE_URL=postgresql://...\n\n# Cloudflare\nCF_ACCOUNT_ID=xxx\nCF_API_TOKEN=xxx\n\n# External Services\nOPENAI_API_KEY=sk-...\nANTHROPIC_API_KEY=sk-ant-...\n\n# Feature Flags\nENABLE_AI_FEATURES=true\nENABLE_BETA_FEATURES=false\n```\n\n---\n\n# 2. CI/CD Pipeline\n\n## 2.1 Pipeline Overview\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         CI/CD PIPELINE                                       │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     COMMIT              BUILD                TEST                DEPLOY\n     ──────              ─────                ────                ──────\n\n     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐\n     │  Push   │───────▶│  Lint   │───────▶│  Unit   │───────▶│ Preview │\n     │  to PR  │        │  Check  │        │  Tests  │        │  Deploy │\n     └─────────┘        └─────────┘        └─────────┘        └─────────┘\n          │                  │                  │                  │\n          │                  ▼                  ▼                  │\n          │             ┌─────────┐        ┌─────────┐            │\n          │             │  Type   │        │  E2E    │            │\n          │             │  Check  │        │  Tests  │            │\n          │             └─────────┘        └─────────┘            │\n          │                  │                  │                  │\n          └──────────────────┴──────────────────┴──────────────────┘\n\n     MERGE TO MAIN                           RELEASE\n     ─────────────                           ───────\n\n     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐\n     │  Merge  │───────▶│  Build  │───────▶│ Staging │───────▶│  Prod   │\n     │  to     │        │  Prod   │        │ Deploy  │        │ Deploy  │\n     │  main   │        │  Bundle │        │  + Test │        │         │\n     └─────────┘        └─────────┘        └─────────┘        └─────────┘\n```\n\n## 2.2 GitHub Actions Workflow\n\n```yaml\n# .github/workflows/ci.yml\nname: CI/CD Pipeline\n\non:\n  push:\n    branches: [main, staging]\n  pull_request:\n    branches: [main]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: pnpm/action-setup@v2\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n          cache: \"pnpm\"\n      - run: pnpm install --frozen-lockfile\n      - run: pnpm lint\n      - run: pnpm typecheck\n\n  test:\n    runs-on: ubuntu-latest\n    needs: lint\n    steps:\n      - uses: actions/checkout@v4\n      - uses: pnpm/action-setup@v2\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n          cache: \"pnpm\"\n      - run: pnpm install --frozen-lockfile\n      - run: pnpm test:unit\n      - run: pnpm test:integration\n      - uses: codecov/codecov-action@v3\n\n  deploy-preview:\n    if: github.event_name == 'pull_request'\n    runs-on: ubuntu-latest\n    needs: test\n    steps:\n      - uses: actions/checkout@v4\n      - uses: cloudflare/wrangler-action@v3\n        with:\n          command: deploy --env preview\n          apiToken: ${{ secrets.CF_API_TOKEN }}\n\n  deploy-staging:\n    if: github.ref == 'refs/heads/main'\n    runs-on: ubuntu-latest\n    needs: test\n    steps:\n      - uses: actions/checkout@v4\n      - uses: cloudflare/wrangler-action@v3\n        with:\n          command: deploy --env staging\n          apiToken: ${{ secrets.CF_API_TOKEN }}\n      - name: Run smoke tests\n        run: pnpm test:smoke --env=staging\n\n  deploy-production:\n    if: github.ref == 'refs/heads/main'\n    runs-on: ubuntu-latest\n    needs: deploy-staging\n    environment: production\n    steps:\n      - uses: actions/checkout@v4\n      - uses: cloudflare/wrangler-action@v3\n        with:\n          command: deploy --env production\n          apiToken: ${{ secrets.CF_API_TOKEN }}\n      - name: Run smoke tests\n        run: pnpm test:smoke --env=production\n```\n\n## 2.3 Pipeline Gates\n\n| Gate                       | Required | Blocking     |\n| -------------------------- | -------- | ------------ |\n| **Lint pass**              | Yes      | Yes          |\n| **Type check pass**        | Yes      | Yes          |\n| **Unit tests pass**        | Yes      | Yes          |\n| **Integration tests pass** | Yes      | Yes          |\n| **E2E tests pass**         | Yes      | Yes          |\n| **Code coverage > 80%**    | Yes      | No (warning) |\n| **Security scan clean**    | Yes      | Yes          |\n| **PR approval**            | Yes      | Yes          |\n\n---\n\n# 3. Deployment Process\n\n## 3.1 Standard Deployment\n\n```bash\n# 1. Merge PR to main (triggers auto-deploy to staging)\n\n# 2. Verify staging deployment\npnpm test:smoke --env=staging\n\n# 3. Production deployment (auto-triggered after staging success)\n# Manual approval required in GitHub Actions\n\n# 4. Verify production deployment\npnpm test:smoke --env=production\n\n# 5. Monitor for 30 minutes post-deploy\n```\n\n## 3.2 Deployment Commands\n\n```bash\n# Preview deployment (from PR)\nwrangler deploy --env preview\n\n# Staging deployment\nwrangler deploy --env staging\n\n# Production deployment\nwrangler deploy --env production\n\n# Rollback to previous version\nwrangler rollback --env production\n```\n\n## 3.3 Zero-Downtime Deployment\n\nCloudflare Workers provides zero-downtime deployments:\n\n1. New version is uploaded\n2. Health check validates new version\n3. Traffic gradually shifts to new version\n4. Old version is deprecated after success\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                      ZERO-DOWNTIME DEPLOYMENT                                │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     Time ─────────────────────────────────────────────────────────────────▶\n\n     Traffic to v1.0: ████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░\n     Traffic to v1.1: ░░░░░░░░░░░░░░░░░░░░████████████████████████████████████\n\n                      │                   │\n                      Deploy v1.1         Cutover complete\n                      Health check OK     v1.0 deprecated\n```\n\n---\n\n# 4. Release Checklist\n\n## 4.1 Pre-Release Checklist\n\n```markdown\n## Pre-Release Checklist\n\n### Code Quality\n\n- [ ] All tests passing\n- [ ] No lint errors\n- [ ] Code review approved\n- [ ] Security scan clean\n- [ ] Performance benchmarks acceptable\n\n### Documentation\n\n- [ ] CHANGELOG updated\n- [ ] API docs updated (if applicable)\n- [ ] User docs updated (if applicable)\n- [ ] Internal runbook updated (if applicable)\n\n### Database\n\n- [ ] Migration scripts reviewed\n- [ ] Migration tested in staging\n- [ ] Rollback migration prepared\n- [ ] Backup verified\n\n### Feature Flags\n\n- [ ] New features behind flags\n- [ ] Flag configuration verified\n\n### Communication\n\n- [ ] Status page prepared (if maintenance)\n- [ ] Customer notification drafted (if breaking)\n- [ ] Internal team notified\n```\n\n## 4.2 Release Checklist\n\n```markdown\n## Release Checklist\n\n### Staging Deployment\n\n- [ ] Deploy to staging\n- [ ] Run smoke tests\n- [ ] Manual QA pass\n- [ ] Performance verified\n\n### Production Deployment\n\n- [ ] Obtain deployment approval\n- [ ] Deploy to production\n- [ ] Run smoke tests\n- [ ] Monitor error rates (15 min)\n- [ ] Monitor latency (15 min)\n\n### Post-Release\n\n- [ ] Verify all health checks green\n- [ ] Check critical user flows\n- [ ] Monitor for 30 minutes\n- [ ] Update status page (if applicable)\n- [ ] Close release ticket\n```\n\n## 4.3 Emergency Release\n\nFor critical fixes:\n\n1. Create hotfix branch from main\n2. Apply fix with minimal changes\n3. Get expedited review\n4. Deploy directly to production (skip staging)\n5. Backfill staging after production is stable\n\n---\n\n# 5. Feature Flags\n\n## 5.1 Feature Flag System\n\nWe use environment-based feature flags:\n\n```typescript\n// lib/flags.ts\n  // Gradual rollout flags\n  ENABLE_AI_SUGGESTIONS: env.ENABLE_AI_SUGGESTIONS === \"true\",\n  ENABLE_BULK_OPERATIONS: env.ENABLE_BULK_OPERATIONS === \"true\",\n\n  // Beta flags\n  ENABLE_BETA_DASHBOARD: env.ENABLE_BETA_DASHBOARD === \"true\",\n  ENABLE_ADVANCED_AUTOMATIONS: env.ENABLE_ADVANCED_AUTOMATIONS === \"true\",\n\n  // Kill switches\n  ENABLE_EXTERNAL_INTEGRATIONS: env.ENABLE_EXTERNAL_INTEGRATIONS !== \"false\",\n  ENABLE_DOCUMENT_GENERATION: env.ENABLE_DOCUMENT_GENERATION !== \"false\",\n};\n\n// Usage\nif (flags.ENABLE_AI_SUGGESTIONS) {\n  await generateSuggestions(account);\n}\n```\n\n## 5.2 Flag Types\n\n| Type            | Purpose             | Default | Example                 |\n| --------------- | ------------------- | ------- | ----------------------- |\n| **Release**     | New feature rollout | Off     | `ENABLE_NEW_DASHBOARD`  |\n| **Experiment**  | A/B testing         | Off     | `EXPERIMENT_PRICING_V2` |\n| **Ops**         | Operational control | On      | `ENABLE_WEBHOOKS`       |\n| **Kill switch** | Emergency disable   | On      | `ENABLE_AI_PROVIDERS`   |\n\n## 5.3 Flag Lifecycle\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                      FEATURE FLAG LIFECYCLE                                  │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n     CREATE              ROLLOUT               CLEANUP\n     ──────              ───────               ───────\n\n     ┌─────────┐        ┌─────────┐        ┌─────────┐        ┌─────────┐\n     │  Add    │───────▶│  Enable │───────▶│  100%   │───────▶│  Remove │\n     │  Flag   │        │  for    │        │  Rollout│        │  Flag   │\n     │  (off)  │        │  Beta   │        │         │        │  Code   │\n     └─────────┘        └─────────┘        └─────────┘        └─────────┘\n          │                  │                  │                  │\n          │              Staging           Production         After 30\n          │              then Prod         verified           days stable\n          ▼                  │                  │                  │\n     Development         1-5% users         All users         Cleanup PR\n```\n\n---\n\n# 6. Rollback Procedures\n\n## 6.1 Application Rollback\n\n```bash\n# Cloudflare Workers rollback (instant)\nwrangler rollback --env production\n\n# Or deploy specific version\nwrangler deploy --env production --version 2024-01-01-abc123\n```\n\n## 6.2 Database Rollback\n\n```bash\n# 1. Identify the migration to rollback\npnpm prisma migrate status\n\n# 2. Rollback migration (if rollback exists)\npnpm prisma migrate resolve --rolled-back \"20260107_add_feature\"\n\n# 3. Apply rollback SQL\npsql $DATABASE_URL -f migrations/rollback/20260107_add_feature.sql\n\n# 4. Update migration state\npnpm prisma migrate resolve --applied \"20260106_previous\"\n```\n\n## 6.3 Rollback Decision Matrix\n\n| Scenario                          | Action                   | Time to Recover |\n| --------------------------------- | ------------------------ | --------------- |\n| **App bug, no data impact**       | Rollback app             | < 5 minutes     |\n| **Migration issue, no data loss** | Rollback migration + app | < 30 minutes    |\n| **Data corruption**               | Restore from backup      | < 4 hours       |\n| **Third-party outage**            | Disable integration      | < 5 minutes     |\n\n## 6.4 Rollback Runbook\n\n````markdown\n## Rollback Runbook\n\n### Step 1: Assess Impact\n\n- [ ] Identify affected users/features\n- [ ] Determine root cause (app vs data)\n- [ ] Decide rollback strategy\n\n### Step 2: Communicate\n\n- [ ] Update status page\n- [ ] Notify internal team\n- [ ] Prepare customer communication (if needed)\n\n### Step 3: Execute Rollback\n\n- [ ] For app issues:\n  ```bash\n  wrangler rollback --env production\n  ```\n````\n\n- [ ] For database issues:\n  ```bash\n  psql $DATABASE_URL -f migrations/rollback/xxx.sql\n  ```\n\n### Step 4: Verify\n\n- [ ] Run smoke tests\n- [ ] Check error rates\n- [ ] Verify critical flows\n- [ ] Monitor for 15 minutes\n\n### Step 5: Post-Rollback\n\n- [ ] Update status page (resolved)\n- [ ] Create incident report\n- [ ] Schedule post-mortem\n\n```\n\n---\n\n# 7. Versioning Policy\n\n## 7.1 Semantic Versioning\n\nWe follow SemVer (MAJOR.MINOR.PATCH):\n\n| Change Type | Version Bump | Example |\n|-------------|--------------|---------|\n| **Breaking API change** | Major | 1.0.0 → 2.0.0 |\n| **New feature** | Minor | 1.0.0 → 1.1.0 |\n| **Bug fix** | Patch | 1.0.0 → 1.0.1 |\n\n## 7.2 API Versioning\n\n```\n\nhttps://api.integratewise.com/v1/accounts\n^^\nVersion prefix\n\n````\n\n**Version policy:**\n- Major versions in URL path (`/v1/`, `/v2/`)\n- Breaking changes require new major version\n- Old versions supported for 12 months after deprecation\n\n## 7.3 Version Headers\n\n```http\n# Response headers\nX-API-Version: 2026-01-01\nX-App-Version: 1.5.2\nX-Request-ID: req_abc123\n````\n\n## 7.4 Changelog\n\n```markdown\n# Changelog\n\n## [1.5.0] - 2026-01-07\n\n### Added\n\n- Bulk account operations\n- Advanced health score components\n- Webhook signature verification\n\n### Changed\n\n- Improved sync performance (2x faster)\n- Updated dashboard design\n\n### Fixed\n\n- Fixed timezone handling in date filters\n- Fixed pagination for large result sets\n\n### Deprecated\n\n- `/v1/metrics` endpoint (use `/v1/health` instead)\n```\n\n---\n\n# 8. Database Migrations\n\n## 8.1 Migration Workflow\n\n```bash\n# 1. Create migration\npnpm prisma migrate dev --name add_feature\n\n# 2. Review generated SQL\ncat prisma/migrations/20260107_add_feature/migration.sql\n\n# 3. Test migration locally\npnpm db:reset\npnpm db:seed\n\n# 4. Create rollback script\n# migrations/rollback/20260107_add_feature.sql\n\n# 5. Deploy to staging (auto via CI)\n# 6. Verify in staging\n# 7. Deploy to production (auto via CI)\n```\n\n## 8.2 Migration Best Practices\n\n| Do                               | Don't                              |\n| -------------------------------- | ---------------------------------- |\n| ✅ Add columns as nullable first | ❌ Add NOT NULL without default    |\n| ✅ Use transactions              | ❌ Mix schema + data changes       |\n| ✅ Create rollback script        | ❌ Deploy without testing          |\n| ✅ Run in low-traffic window     | ❌ Drop columns immediately        |\n| ✅ Backfill data separately      | ❌ Lock tables for long operations |\n\n## 8.3 Zero-Downtime Migration Pattern\n\n```sql\n-- Step 1: Add nullable column\nALTER TABLE accounts ADD COLUMN new_field TEXT;\n\n-- Step 2: Backfill data (in batches)\nUPDATE accounts SET new_field = 'default' WHERE new_field IS NULL LIMIT 1000;\n\n-- Step 3: Add NOT NULL constraint (after backfill complete)\nALTER TABLE accounts ALTER COLUMN new_field SET NOT NULL;\n\n-- Step 4: Add index (concurrently)\nCREATE INDEX CONCURRENTLY idx_accounts_new_field ON accounts(new_field);\n```\n\n---\n\n# 9. Secret Management\n\n## 9.1 Secret Storage\n\n| Secret Type              | Storage                    | Access       |\n| ------------------------ | -------------------------- | ------------ |\n| **API keys**             | Cloudflare Workers Secrets | Runtime only |\n| **Database credentials** | Cloudflare Workers Secrets | Runtime only |\n| **OAuth tokens**         | Database (encrypted)       | Application  |\n| **Webhook secrets**      | Database (encrypted)       | Application  |\n\n## 9.2 Adding Secrets\n\n```bash\n# Add secret to Cloudflare Workers\nwrangler secret put SECRET_NAME --env production\n\n# Bulk add from .env\ncat .env.production | while IFS='=' read key value; do\n  echo \"$value\" | wrangler secret put \"$key\" --env production\ndone\n```\n\n## 9.3 Secret Rotation\n\n| Secret                   | Rotation Frequency | Process              |\n| ------------------------ | ------------------ | -------------------- |\n| **API keys**             | 90 days            | Automated            |\n| **Database password**    | 180 days           | Manual (coordinated) |\n| **OAuth client secret**  | Annually           | Manual (coordinated) |\n| **Webhook signing keys** | On demand          | Customer-initiated   |\n\n## 9.4 Secret Rotation Runbook\n\n````markdown\n## Secret Rotation Runbook\n\n### Database Password Rotation\n\n1. Generate new password\n   ```bash\n   openssl rand -base64 32\n   ```\n````\n\n2. Update in Supabase console\n\n3. Update Cloudflare secret\n\n   ```bash\n   echo \"new_password\" | wrangler secret put DATABASE_PASSWORD --env production\n   ```\n\n4. Verify connection\n\n   ```bash\n   pnpm test:smoke --env=production\n   ```\n\n5. Update local .env files (do not commit)\n\n```\n\n---\n\n**IntegrateWise Deployment & Environment Guide**\n*Version 1.0 — January 2026*\n\nFor questions: engineering@integratewise.com\n```\n"}