Migrately – A CLI Tool for Full Server to Server Cloning

17 min read

Important: migrating from Ubuntu 18.04 or 20.04

Migrately is currently designed for servers on our supported stacks: Ubuntu 22.04, 24.04 and 26.04. If your source server runs Ubuntu 18.04 or 20.04 (an unsupported stack), its Redis setup differs from the new server's. Sites that have Redis page caching or Redis object caching switched on will not have working caches after migration unless you follow the steps in "Migrating from an older server (18.04 / 20.04)" below.

Information

This tool moves everything on a server — every site's files, database, and configuration — to a new, empty destination server. Treat the destination as disposable: anything already there will be overwritten. Don't run this against a server that has data you want to keep.

Introduction

Migrately is our custom-built CLI tool that our own support team uses to move WordPress sites on our fully managed service from one server to a brand-new one. This is now available to everyone using GridPane.

What it does

Migrately copies the following from one server to another:

  • All WordPress files
  • The whole database instance
  • The web server config (including your custom configurations such as server-wide 7G rules, cache exclusions, etc)
  • The PHP config
  • The Redis config
  • SSL certificates

This guide will walk you through a standard move step by step. Like most of our articles, this is essentially an exercise in copy-and-paste — you’ll just need to swap in your own server address and a few file paths.

Before You Start

This is a CLI-based tool, so you will need to connect to your servers over SSH to follow this article. If this is your first time connecting to one of your servers, please see the following articles to get started:

Server Requirements

The destination server must be on a supported stack (Ubuntu 22.04, 24.04 or 26.04). If the source server is on Ubuntu 18.04 or 20.04, follow “Migrating from an older server” first.

You’ll need the following to begin using Migrately:

  • Two GridPane servers – your old one (the source) and a brand-new, empty one (the destination).
  • Both servers need to use the same server stack (both Nginx or both OpenLiteSpeed), and same database engine (both Percona, or both MariaDB) – you can check this in your GridPane dashboard if you’re unsure.
  • A rough idea of how much disk space your sites and database currently use, so you can confirm the new server has enough room.

If you’ve created a brand new server but it’s not running the right server stack and/or database engine, simply delete it and create a provision a new one.

DNS Changeover

A word on downtime: Migrately doesn’t pause your live sites while it copies files and databases – visitors can keep browsing, and orders can keep coming in on the old server right up until you’re ready to switch over.

For a clean cutover, stop any writes to the old site (put it in maintenance mode, or simply schedule the move for a quiet time) before the file and database steps, and only point your domain at the new server once everything below shows success.

Step 1: Create Your Settings File

Log in to your old (source) server over SSH and create a settings file that tells migrately where to send everything. Copy and paste the following command to create and open the file:

nano /root/migrately.conf

The example configurations below will rehome your whole server, which means all sites transferred from your old production server to your new production server. If you continue down this section (Option 2), you’ll also find settings for moving a production server to a staging server (where we will set the WP_ENVIRONMENT_TYPE to staging and add the X-Robots-Tag HTTP header to set your sites to no-index).

Option 1: Clone Production to Production

Copy and paste the following lines into your migrately.conf, then replace the two placeholder lines (marked below) with your own new server’s address:

sites: all
server-ssh-login: root@YOUR-NEW-SERVER-IP
dest-path: /var/www
db-user: root
db-backup-dir: /root/migrately-db
restore-mode: direct
  • Ensure the formatting (each parameter on its own line) matches the above.
  • Replace YOUR-NEW-SERVER-IP with your new server’s IP address (for example [email protected]).
  • Leave the other lines as they are — these are sensible defaults for a standard move.

Save and close the file (in nano, that’s Ctrl+O followed by Enter, then Ctrl+X).

Option 2: Clone Production Server to Staging Server (de-indexed)

The following configuration will set:

  1. define('WP_ENVIRONMENT_TYPE', 'staging'); in your wp-config.php files.
  2. X-Robots-Tag: noindex, nofollow, nosnippet, noimageindex HTTP header.

These will be set on every site on the destination server, making your destination server fully configured to act as a staging/development environment.

Copy and paste the following, replacing the highlighted IP address with your destination server IP address:

sites: all
server-ssh-login: root@198.99.101.99
dest-path: /var/www
db-user: root
db-backup-dir: /root/migrately-db
restore-mode: direct
environment_type: staging

Save and close the file (in nano, that’s Ctrl+O followed by Enter, then Ctrl+X).

When running your migration, Finalize (menu 10) uses curl --resolve to hit the destination’s IP directly, since DNS still points at the source. This confirms the destination itself is serving the header. More details on this can be found in Step 3.

Important

These settings instruct crawlers to respect the header but can't enforce it. They are not access control and don't block traffic. The easiest way to keep it private is to use a local hosts file redirect when working on development sites.

Step 2: Connect the Two Servers

Log in to your old (source) server over SSH and start the tool with the following command:

migrately

This opens a numbered menu. The first two options set up a secure connection between your two servers:

  1. Type 1 and press Enter — this creates a special SSH key just for this migration.
  2. Type 2 and press Enter — this prints that key to your screen.

Copy your newly created key.

Next, log in to your new (destination) server and edit the authorized_keys file with the following command:

nano /root/.ssh/authorized_keys

Paste your key into this file – you will see a few keys already there and you can add it at the bottom. Now save the file with CTRL+O followed by Enter, and close the file with CTRL+X.

That’s it! Your two servers can now talk to each other securely.

Step 3: Run the Migration 

Because this process can take a while, run it inside a screen session so it keeps running even if your internet connection drops.

Copy and paste the following command on your origin server to get started:

screen -S migrate

Here’s a quick rundown on how and why to use a screen, and how to watch the tool’s progress:

  • screen -S migrate keeps the job running if your connection drops.
  • Detach with Ctrl-A then D, and reattach with screen -r migrate.
  • Stop it any time with Ctrl-C. Re-running the same command picks up where it left off.

Option 1: Manual Run

Start Migrately with the following command:

migrately -c /root/migrately.conf

You’ll see the same numbered menu as before. This time, work through options 3-10 in this exact order, pressing Enter after each one to return to the menu:

Type this What it does
3 Runs Redis migration
4 Creates your sites on the new server
5 Creates any additional/alias domains
6 Copies all your site files
7 Copies your entire database
8 Moves your web server settings and SSL certificates
9 Moves your PHP settings
10 Finishes up and switches everything on

Option 2: Run 3→10 and then 14 to Exit

The following command will run options 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10, one by one, and then 14 to exit:

printf '3\n\n4\n\n5\n\n6\n\n7\n\n8\n\n9\n\n10\n\n14\n' | migrately -c /root/migrately.conf

(Typing 14 at any point exits the tool.)

You can open the Migrately back up again once this is complete by entering:

migrately

If you get disconnected

If your screen session gets disconnected partway through, don’t worry — just log back in and reattach with:

screen -r migrate

Migrately keeps working in the background even while you’re disconnected.

Step 4: Check Everything Came Across

Once step 10 finishes, it’s worth double-checking your data landed correctly. Back at the menu, type:

11

This compares posts, users, plugins, and themes between your old and new server and tells you if anything doesn’t match.

Once you’re happy everything looks right, you can safely point your domain’s DNS to the new server.

Optional: Matching Your Backup Settings

If your old server had scheduled backups set up, you can copy those settings across too — but you must do this last, only once you trust the migration has completed the previous steps successfully.

  • Type 12 to match your local backup schedule
  • Type 13 to match your remote (cloud) backup storage and schedule

Both of these are safe to run more than once — if a setting already matches, nothing changes.

If a Site Gets Skipped

If any single site couldn’t be moved (for example, it didn’t finish building in time at step 4), Migrately won’t stop the whole migration – it will skip just that one site, tell you clearly which site and which step, and keep going with everything else.

At the very end, you’ll see a summary listing anything that needs attention, along with what to do about it (usually: go back to option 4 to build the missing site, then re-run the step it was skipped at for just that site).

Don’t point your domain at the new server until every site in that summary has been resolved.

Step 5: Wrapping Up

You can exit the Migrately CLI tool by entering:

14

When migrately finishes, it returns an exit status that tells you how the run went. Below is a breakdown of all possible outcomes:

Status What happened What you'll see / what it means
0 The run reached option 14 (exit). The input stream completed. It does not guarantee every site verified successfully.
1 Input ran out before option 14. A message lists which options did complete.
1 Option 12 or 13 was selected, but a site's backup configuration couldn't be matched or was put on hold by a committed handoff. The output includes a section called SITES WITH INCOMPLETE SELECTED WORK IN THIS RUN, listing each site, the stage, the reason, and the fix. The site itself may still be fully migrated.
1 A step failed. Check the output for the failing step.
1 The run finished but skipped some sites (not on the destination, or a per-site transfer failed). The output includes a section called SITES SKIPPED OR FAILED IN THIS RUN, listing each site and the step where it was skipped.
1 The script was started on a server that is itself a claimed destination. Run it from the source server instead.
1 or 255 SSH failure. See the note below.
2 Auth normalisation couldn't confirm a rollback. Verify the auth state manually.
73 The destination refuses the run because it is claimed by a different source. Another source already owns this destination.
74 The destination refuses the run because its own migrately session is running. Wait for that session to finish.
75 The destination refuses the run because of a committed handoff freeze, or another migrately already holds this source's lock. Wait for the freeze or the other run to clear.
130 You pressed Ctrl-C. The run was cancelled manually.

Notes on SSH failures

  • A connection failure mid-run returns 1 or 255, depending on which call hit it.
  • Building a site restarts the destination’s sshd, so the next option may briefly fail with “Connection refused.”
  • Either way, migrately tries to recover its workers and release its claim on the destination. Check /var/log/migrately-cleanup.log to see whether both succeeded.
  • The fix is usually to re-run the same stream. Sites that were already built are detected as present.

Tip

Run unattended jobs inside screen or tmux. The exit-status behavior is the same either way, but a dropped terminal won't kill the job.

Migrating From an Older Server (18.04 / 20.04)

In short: switch Redis caching off, run Migrately without option 3, make two wp-config.php edits on the new server, then switch caching back on.

Step A. Before you migrate (source server, in the GridPane app)

  1. For every site you’re migrating, switch Redis page caching to FastCGI (or off). FastCGI keeps your sites cached during the move and doesn’t use Redis.
  2. For every site, switch Redis object caching off. If the site uses Object Cache Pro, switch that off too.
  3. Check that Object Cache Pro is really off. On the source server, this should print nothing:
ls /var/www/*/object-cache-pro-configs.php 2>/dev/null

If it lists a site, switch Object Cache Pro off for that site in the app again before continuing.

Step B. Delete the object-cache.php file

After disabling Redis caching, you can make sure this file is deleted for each website on your origin server with the following command:

for f in /var/www/*/htdocs/wp-content/object-cache.php; do { [ -e "$f" ] || [ -L "$f" ]; } || continue; rm -fv "$f"; done

This will loop through each site and remove this specific file.

If you see any errors listed after step 14, you can also run this command on the destination server before turning any Redis page or object caching back on.

Step C. Run Migrately, but skip option 3

  • Manual run: start at option 4 and work through to 10. Do not run option 3 (Redis migration).
  • Single-command run: use the same command as the normal guide, but leave out the 3 so the sequence runs 4 → 10, then 14.

On an older server, option 3 would copy its old Redis settings onto the new server. The new server doesn’t need them.

Step D. After migrating (destination server, as root)

Run this once. It updates every migrated site’s wp-config.php for the new server’s Redis setup. It is safe to run more than once, and it doesn’t change sites that are already set up for the new server.

for f in /var/www/*/wp-config.php; do
# Object cache: point at the new object-cache Redis socket
sed -i 's|/var/run/redis/redis-server.sock|/var/run/redis-object/redis-object.sock|g' "$f"
# Nginx Helper: add the username/password lines the new page-cache Redis needs
# (GridPane fills in the real values when you switch Redis page caching on)
if grep -q "RT_WP_NGINX_HELPER_REDIS_PREFIX" "$f" && ! grep -q "RT_WP_NGINX_HELPER_REDIS_USERNAME" "$f"; then
sed -i "/RT_WP_NGINX_HELPER_REDIS_PREFIX/a //define('RT_WP_NGINX_HELPER_REDIS_PASSWORD', '');" "$f"
sed -i "/RT_WP_NGINX_HELPER_REDIS_PREFIX/a //define('RT_WP_NGINX_HELPER_REDIS_USERNAME', '');" "$f"
fi
done

Then, in the GridPane app on the new server, switch caching back on for each site: Redis page caching, and Redis object caching or Object Cache Pro. Switching them on sets each site’s Redis username, password and database for the new server.

Custom Nginx overrides: if you had a custom Redis cache file on the old server (/etc/nginx/common/_custom/<site>-wp-redis.conf), it was copied across as it was and still contains the old Redis settings. Review it, or remove it, before you switch Redis page caching on.

Step E. Check it worked (destination server)

Object cache: should show “Status: Connected”:

gp wp {site} redis status

E.g:

gp wp example.com redis status

Page cache: the second request should show “x-grid-srcache-fetch: HIT””

curl -sI https://{site}/ | grep -i x-grid-srcache-fetch
curl -sI https://{site}/ | grep -i x-grid-srcache-fetch

Run these before you point DNS at the new server. Until then, use a local hosts file entry, or replace the curl commands with:

 curl -sI --resolve {site}:443:{new-server-ip} https://{site}/.

Already Migrated from 18.04 / 20.04 with Redis Caching On?

If you already migrated from an 18.04 / 20.04 server with Redis caching switched on, nothing is lost. Your sites still point at the old single Redis, which doesn’t run on the new server. These steps switch caching off, repair wp-config.php, then switch caching back on so GridPane rebuilds each site’s Redis settings for the new server.

1. Check Redis is running (destination server, as root)

systemctl is-active redis-object redis-page

Both lines should say active. If either doesn’t, stop here and contact support.

2. Switch caching off (GridPane app, new server)

For each affected site:

  • Switch page caching from Redis to FastCGI (or off).
  • Switch Redis object caching off. If the site uses Object Cache Pro, switch that off too.

This step must come first. A site that is already set to Redis page caching doesn’t get its Nginx files rebuilt if Redis is switched on again.

3. Delete the object-cache.php file

After disabling Redis caching, you can make sure this file is deleted for each website on your origin server with the following command:

for f in /var/www/*/htdocs/wp-content/object-cache.php; do { [ -e "$f" ] || [ -L "$f" ]; } || continue; rm -fv "$f"; done

This will loop through each site and remove this specific file.

4. Repair wp-config.php (destination server, as root)

Run the following (the same command as in Step C above):

for f in /var/www/*/wp-config.php; do
# Object cache: point at the new object-cache Redis socket
sed -i 's|/var/run/redis/redis-server.sock|/var/run/redis-object/redis-object.sock|g' "$f"
# Nginx Helper: add the username/password lines the new page-cache Redis needs
# (GridPane fills in the real values when you switch Redis page caching on)
if grep -q "RT_WP_NGINX_HELPER_REDIS_PREFIX" "$f" && ! grep -q "RT_WP_NGINX_HELPER_REDIS_USERNAME" "$f"; then
sed -i "/RT_WP_NGINX_HELPER_REDIS_PREFIX/a //define('RT_WP_NGINX_HELPER_REDIS_PASSWORD', '');" "$f"
sed -i "/RT_WP_NGINX_HELPER_REDIS_PREFIX/a //define('RT_WP_NGINX_HELPER_REDIS_USERNAME', '');" "$f"
fi
done

It points each site’s object cache at the new server’s Redis and adds the page-cache username and password lines.

Custom Nginx overrides: review or remove any /etc/nginx/common/_custom/{site}-wp-redis.conf copied from the old server before the next step.

5. Switch caching back on (GridPane app, new server)

For each site, switch page caching to Redis, and switch on Redis object caching or Object Cache Pro (whichever the site used before). This rebuilds each site’s Nginx cache files and Redis login for the new server.

6. Check it worked (destination server)

No Nginx cache file should still point at the old Redis — should print nothing:

grep -lE 'redis2?_pass redis;' /etc/nginx/common/*.conf /etc/nginx/common/_custom/*.conf 2>/dev/null

Object cache: should show “Status: Connected”:

gp wp {site} redis status

Page cache: the second request should show “x-grid-srcache-fetch: HIT”:

curl -sI https://{site}/ | grep -i x-grid-srcache-fetch
curl -sI https://{site}/ | grep -i x-grid-srcache-fetch

If the first command lists any files, or a site still doesn’t connect or cache, contact support with the site name.

Troubleshooting

If you run into a message you don’t recognize, or a step fails partway through, your session log will have the full details — check the terminal output, or if you used script to record your session, review that log file. You can always safely re-run any step; migrately is designed to pick up where it left off.