Create a Migration Runbook Template

What is a Migration Runbook?

A migration runbook is a detailed, step-by-step document that guides the migration process from start to finish. It ensures consistency, reduces human error, and provides a reference during high-pressure migration windows. Every migration should have its own runbook, customized from a standard template.

Runbook Template Structure

Section 1: Migration Overview

Migration Name: [Project/Service Name] Migration
Date Planned: YYYY-MM-DD HH:MM (timezone)
Estimated Duration: X hours
Migration Lead: [Name]
Team Members: [Names and roles]

Source: [Server/Provider details]
Destination: [Server/Provider details]

Rollback Deadline: [Time by which we must rollback if issues arise]

Section 2: Pre-Migration Checklist

[ ] Full backup of source server completed and verified
[ ] Destination server provisioned and accessible
[ ] Software stack installed and configured on destination
[ ] DNS TTL lowered to 300s (done 24h+ before migration)
[ ] All team members notified of maintenance window
[ ] Customers notified (if applicable)
[ ] Monitoring alerts temporarily adjusted
[ ] Rollback procedure documented and tested
[ ] Emergency contacts listed

Section 3: Asset Inventory

Websites:
- example.com (PHP 8.3, MySQL, Laravel)
- api.example.com (Node.js 20, PostgreSQL)

Databases:
- myapp_production (MySQL, ~5GB)
- api_db (PostgreSQL, ~2GB)

Email Accounts:
- user1@example.com (3GB mailbox)
- user2@example.com (1GB mailbox)

Cron Jobs:
- */5 * * * * /path/to/job1.sh
- 0 2 * * * /path/to/backup.sh

SSL Certificates:
- example.com (Let us Encrypt, auto-renew)
- api.example.com (Let us Encrypt, auto-renew)

DNS Records:
- A: example.com -> 1.2.3.4
- A: api.example.com -> 1.2.3.4
- MX: example.com -> mail.example.com
- TXT: SPF, DKIM, DMARC records

Section 4: Step-by-Step Procedure

Step 1: [HH:MM] Initial Data Sync
Command: rsync -avz root@source:/var/www/ /var/www/
Expected duration: 30 minutes
Verification: ls -la /var/www/ (check file counts)
Status: [ ] Complete

Step 2: [HH:MM] Database Migration
Command: ssh root@source "mysqldump ..." | mysql
Expected duration: 15 minutes
Verification: Check table counts match source
Status: [ ] Complete

Step 3: [HH:MM] Enable Maintenance Mode
Command: ssh root@source "touch /var/www/.maintenance"
Expected duration: 1 minute
Status: [ ] Complete

Step 4: [HH:MM] Final Data Sync
Command: rsync -avz --delete root@source:/var/www/ /var/www/
Expected duration: 2 minutes
Status: [ ] Complete

Step 5: [HH:MM] Final Database Sync
Command: ssh root@source "mysqldump ..." | mysql
Expected duration: 5 minutes
Status: [ ] Complete

Step 6: [HH:MM] Update DNS
Action: Change A record to new IP
Expected propagation: 5-10 minutes (TTL is 300s)
Status: [ ] Complete

Step 7: [HH:MM] Verification
[ ] Website loads correctly (HTTP + HTTPS)
[ ] Database queries return expected results
[ ] Email sending works
[ ] All application features functional
[ ] SSL certificates valid
[ ] Monitoring shows healthy status
Status: [ ] Complete

Section 5: Rollback Procedure

If issues are detected before DNS cutover:
1. Stop - do not change DNS
2. Investigate the issue on destination
3. Fix and re-verify, or abort

If issues after DNS cutover:
1. Revert DNS A record to source IP (propagates in 5min with 300s TTL)
2. Remove maintenance mode on source: rm /var/www/.maintenance
3. Source server resumes serving traffic
4. Investigate and plan retry

Rollback commands:
# Revert DNS via Cloudflare API or dashboard
# Remove maintenance: ssh root@source "rm /var/www/.maintenance"

Section 6: Post-Migration

[ ] All verification checks passed
[ ] Monitoring alerts re-enabled and showing green
[ ] Automated backups configured on new server
[ ] DNS TTL restored to normal (3600s)
[ ] Source server kept running for 72h fallback period
[ ] Team debriefed on any issues encountered
[ ] Runbook updated with lessons learned
[ ] Source server decommissioned after confirmation period

Tips for Effective Runbooks

• Include exact commands, not just descriptions
• Add expected output or verification steps after each command
• Include timestamps and time estimates for each step
• Have a designated note-taker during the migration
• Practice the migration on staging before production
• Keep the runbook accessible offline (printed copy or separate device)