DevOps
A Production Website Migration Runbook
A staged migration method covering inventory, URL mapping, data integrity, DNS, redirects, observability, rollback, and search continuity.
Author: Fahad Bin Shakir · Published: · Updated: · 13 min read
Introduction
A website migration can change hosting, framework, domain, information architecture, database, or several of these at once. The visible launch may take minutes, but the safe migration begins with an inventory and ends only after users, search crawlers, integrations, and operators are all using the new path.
The runbook should separate reversible preparation from the final cutover. It should also name the conditions that trigger rollback, because the launch window is the worst time to negotiate what failure means.
Inventory the current production surface
Crawl the public site and combine that result with sitemaps, analytics, Search Console, server logs, database records, and stakeholder knowledge. Record canonical URLs, redirects, status codes, metadata, structured data, forms, APIs, downloads, feeds, media, scheduled jobs, DNS records, certificates, and external integrations.
Search for legacy hosts, staging URLs, sample content, old CMS paths, and orphaned pages. Do not rely on navigation alone; search engines and external links may still reach resources that the current interface no longer exposes. Classify each URL as retain, redirect, remove with 410, allow 404, or keep out of the index.
Create a one-to-one URL decision map
Map an old URL to the closest genuine new equivalent and use a permanent redirect. Do not redirect every removed page to the homepage because that confuses visitors and often behaves like a soft 404. Pure demo, test, or withdrawn content with no replacement can return 410; unknown resources should return 404.
Preserve useful query behavior only when the target understands it, avoid redirect chains, and define slash, case, protocol, and host normalization. Test the map against the actual old URL set, including encoded paths and common variants.
Rehearse data and application changes
Take a sanitized production copy through the full migration procedure. Compare record counts, key business totals, media checksums, relationships, character encoding, timestamps, permissions, and rendered samples. Rehearsal should produce a repeatable script and an estimated duration, not a collection of manual notes.
Plan the final data delta. A content freeze is simple for a quiet site; busy systems may need change capture, dual writes, or a brief read-only window. Decide how submissions, orders, comments, or editorial work created during cutover will be preserved.
Lower DNS risk before cutover
Reduce DNS TTLs in advance, allowing the previous TTL to expire before the launch window. Inventory A, AAAA, CNAME, MX, TXT, CAA, verification, and service records. A web migration should not accidentally remove email authentication or another subdomain's service.
Provision certificates and test the new origin through a controlled hostname or local host mapping. Confirm canonical headers, redirects, APIs, and asset URLs without making the staging origin indexable. Keep the old environment operational until rollback is no longer needed.
Run a controlled cutover
Announce the change window, pause conflicting jobs or writes, take the final backup, apply the delta, deploy the reviewed release, switch traffic, and run smoke tests from outside the hosting network. Verify representative pages, authentication, forms, APIs, downloads, robots, sitemap, analytics consent, error responses, and security headers.
Watch error rate, latency, origin saturation, logs, queues, and external service failures. Keep a timestamped decision log. If a rollback threshold is crossed, restore traffic using the rehearsed path and reconcile any writes received by the new system before reopening.
Protect search and retire legacy systems safely
Submit the new sitemap, inspect critical URLs, and monitor indexing, crawl errors, canonical selection, and traffic by old landing page. Preserve redirects long enough for users and crawlers to update. Search Console temporary removals can hide urgent stale results, but they do not replace a correct 301, 404, or 410 at the source.
Before decommissioning, archive required evidence, revoke credentials, remove DNS, disable scheduled jobs, and confirm that no redirects, assets, mail, backups, or integrations still depend on the old host. Destruction should follow the organization's retention and approval process, not the excitement of launch day.
Deployment checklist
- Combine crawl, logs, analytics, search, database, and stakeholder inventories.
- Assign every old URL a retain, 301, 410, or 404 decision.
- Rehearse data transformation and verify integrity with measurable checks.
- Lower DNS TTLs early and preserve non-web records.
- Pre-provision TLS and test the new origin without indexing staging.
- Define cutover steps, owners, rollback thresholds, and write reconciliation.
- Monitor search and runtime signals after launch.
- Retire the old environment only after dependencies and retention are resolved.