Standardized WordPress migrations across a hosting fleet

Context

• Project type: WordPress migrations (both single-site and multisite installations) between hosting environments.
• Environment: WordPress, MySQL, Linux/SSH servers, rsync-based file transfer, WP-CLI.
• Constraint: an agency-operated hosting platform running many independent WordPress installations for institutional clients needed a repeatable way to move installations between servers without breaking configuration, misrouting URLs, or causing avoidable downtime during cutover.

Problem

Ad hoc, one-off migrations create risk: hard-coded database credentials and file paths don't survive a server move cleanly, mismatched domain references break the site post-move, and without a documented cutover sequence, DNS/SSL changes can be triggered before the destination is actually verified working.

Diagnosis

Reviewing how migrations were being handled across the fleet showed the failure points were concentrated in a few specific places: environment-specific bootstrap paths hard-coded per install, database credentials embedded directly in wp-config.php instead of externalized, and no standard checklist step for verifying URLs after the move. The fix was procedural as much as technical — a single documented, repeatable sequence that removes those failure points by construction rather than relying on the person doing the migration to remember every edge case.

Sourceold server

rsync (pull)

Destinationinitiates pull · creds external

Registry update

DNS / SSL cutover

Verify●ok

○gateno cutover until verify passes

Diagram of the migration runbook. Step 1: the source, the old server. Step 2: the destination initiates an rsync pull, with database credentials externalized to environment variables. Step 3: verify. Status ok. Step 4: DNS and SSL cutover. Step 5: registry update. Status gate: there is no cutover until verification passes.

Actions

• Standardized on a pull-based rsync transfer (destination always pulls from source, never pushes), with explicit exclusions for backup directories, cache directories, and theme render caches to avoid moving disposable data.
• Externalized database credentials in wp-config.php to environment variables instead of hard-coded values, so the same configuration file works unchanged across environments.
• Documented the exact bootstrap and .user.ini path edits required per installation, removing guesswork from that step.
• Used wp search-replace across all tables to correct domain references when a migration also involved a domain change.
• Sequenced the cutover explicitly: import database, verify the destination, only then hand off for DNS/SSL updates, followed by a full post-migration test pass.
• Added a final step to keep a central installation registry up to date so the fleet's environment inventory doesn't drift from reality.

Result

• Verified operational result: a documented, repeatable migration procedure that removed the main sources of manual error (hard-coded paths/credentials, undocumented cutover order) from WordPress server migrations on shared agency infrastructure.

Relevant capabilities

WordPress and WordPress multisite migrations, Linux/SSH server administration, rsync-based deployment, WP-CLI (including search-replace), externalized/environment-variable configuration management, DNS/SSL cutover coordination, and documentation of operational runbooks for repeatable execution by others.