planning-zero-downtime-migration

name	planning-zero-downtime-migration
description	Generates a custom zero-downtime migration plan tailored to the user's specific server setup, integrations, and traffic patterns. Covers shadow deployment, traffic mirroring, gradual cutover, and rollback procedures. Activate when benchmarking is complete and the user is ready to plan the production migration, cutover, or deployment.

Planning Zero-Downtime Migration

You are generating a custom migration plan specific to THIS user's infrastructure. This is not a generic template — every recommendation must be based on what you discovered in Phases 1-6.

---

1. Gather Migration-Specific Info

Before generating the plan, ask the user:

"I need a few more details to build your custom migration plan:

1. DNS Management: Where are your DNS records managed? (Cloudflare, Route53, DigitalOcean DNS, other)

2. Current Reverse Proxy: Are you running Nginx, Caddy, Traefik, or nothing in front of n8n?

3. Maintenance Window: Is there a low-traffic period? (e.g., 2-5 AM local time)

4. Acceptable Risk Level: How cautious do you want to be?

   • Conservative: 2-week shadow period, 3-day gradual cutover
   • Moderate: 1-week shadow, 1-day cutover
   • Aggressive: 3-day shadow, immediate cutover (not recommended)

5. Rollback Requirement: How quickly must you be able to roll back?

   • Instant (< 1 minute): requires keeping n8n warm
   • Fast (< 10 minutes): n8n container stopped but ready
   • Standard (< 1 hour): n8n container archived"

---

2. Generate the Custom Plan

Based on all collected data, generate workspace/docs/migration-plan.md.

The plan MUST include these sections:

Section 1: Pre-Migration Checklist

## Pre-Migration Checklist

- [ ] All [n] tests pass (pytest exit code 0)
- [ ] All [n] parity tests confirm output matches n8n
- [ ] Benchmark shows acceptable performance
- [ ] Test credentials verified for all [n] integrations
- [ ] Database backup taken: `pg_dump -h [host] -U [user] [db] > backup_[date].sql`
- [ ] Current nginx config backed up: `cp /etc/nginx/... /backup/...`
- [ ] n8n workflow export saved locally (redundant backup)
- [ ] Rollback procedure reviewed and tested in staging
- [ ] [User name] has signed off on migration (document in this file)

Section 2: Infrastructure Setup

Generate Docker Compose and Nginx configs specific to the user's setup.

Docker Compose must include:

• The new app service (with resource limits)
• Health checks for every service
• Proper startup order via depends_on
• Environment file references
• Named volumes

Nginx config must include:

• Existing n8n routing (UNCHANGED)
• New staging routes on a separate path prefix
• Mirror block (commented out, ready to enable)
• Aggressive timeouts on the mirror backend

Adapt to what the user currently has:

• If they use Caddy: generate Caddyfile instead (but warn about mirror limitations)
• If they use Traefik: generate Traefik labels
• If they have no proxy: generate a new Nginx config from scratch

Section 3: Shadow Deployment

## Phase 1: Shadow Deployment

Duration: [based on user's risk preference]

1. Deploy new app alongside n8n:
   `docker compose up -d app`

2. Verify health:
   `curl http://localhost:3000/health`

3. Switch production credentials:
   - Update workspace/config/.env with production values
   - Set DRY_RUN=false
   - Restart: `docker compose restart app`

4. Enable traffic mirroring:
   - Uncomment mirror block in nginx.conf
   - `nginx -t && nginx -s reload`

5. Monitor for [duration]:
   - Watch app logs: `docker compose logs -f app`
   - Check mirror responses match n8n
   - Run parity verification daily

Section 4: Gradual Cutover

## Phase 2: Gradual Cutover

Day 1: Route [10]% of traffic to new app
  - Use nginx split_clients or weighted upstream
  - Monitor error rates for 24 hours

Day 2: Route [50]% of traffic
  - Monitor for 24 hours
  - Compare response times

Day 3: Route [100]% of traffic
  - n8n still running as fallback
  - Monitor for 48 hours

Section 5: Webhook Switchover

This is integration-specific. For each integration in the registry:

Telegram Bot:

### Telegram Webhook Switch
1. Set new webhook URL:
   `curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -d "url=https://[domain]/webhook/telegram"`
2. Verify: `curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"`
3. Old n8n webhook automatically stops receiving updates

Generic Webhooks:

### [Service Name] Webhook Switch
1. Update webhook URL in [service] dashboard from:
   `https://[domain]/webhook/[n8n-path]`
   to:
   `https://[domain]/webhook/[new-path]`

Section 6: Rollback Procedure

## Rollback Procedure

### Instant Rollback (< 1 minute)
1. Revert nginx config: `cp /backup/nginx.conf /etc/nginx/... && nginx -s reload`
2. All traffic returns to n8n immediately
3. Re-set Telegram webhook to n8n URL if changed

### Database Rollback (if needed)
1. Stop new app: `docker compose stop app`
2. Restore database: `psql -h [host] -U [user] [db] < backup_[date].sql`
3. Restart n8n: `docker compose restart n8n`

### Full Rollback
1. Execute instant rollback steps
2. Execute database rollback steps
3. Verify n8n health: `curl https://[domain]/healthz`
4. Verify all workflows active: check n8n UI

Section 7: Post-Migration Cleanup

## Post-Migration Cleanup (after [7/14/30] days with no issues)

- [ ] Stop n8n container: `docker compose stop n8n`
- [ ] Archive n8n data volume
- [ ] Remove n8n service from docker-compose.yml
- [ ] Remove mirror/split_clients blocks from nginx.conf
- [ ] Update DNS if applicable
- [ ] Delete old webhook registrations from external services
- [ ] Celebrate 🎉

---

3. Present the Plan

Show the complete plan to the user. Ask them to review every section.

"Here is your custom migration plan based on everything we have discovered, analyzed, translated, tested, and benchmarked. Please review carefully.

This plan is saved at workspace/docs/migration-plan.md.

I will not execute any of this automatically. When you are ready to proceed with each phase, we will do it together step by step.

Any changes you would like to make?"