v3 to v4 Migration Script

Edit this on Github

EasyEngine provides a migration script if you want to migrate your existing sites running on v3 to v4. 

The migration script support migrating sites on the same server as well as a new remote server.

The migration script automatically installs EasyEngine v4 – either locally or remotely, if it is not already installed.

Limitations

  • v4 doesn’t support email hosting. So your v3 email won’t be migrated by the script.
  • You need to migrate your own custom NGINX configuration which are outside paths specified for custom configuration in EasyEngine v3. It’s hard to predict what may go in custom config so its better you do it yourself, if required.

Download Migration Script

Run following command to download the migration script on v3 server 

wget -O migrate.sh https://rt.cx/ee3to4 &&
chmod +x migrate.sh

Start a tmux/screen session

This is optional but highly recommended.

Migration script can take time. Especially migration to a remote server.

Please ensure that you run either start tmux or screen session on v3 server. This will ensure the script runs without any issues even if your Internet connection to your v3 server breaks.

Migrating Sites on the Same Server

This method will migrate your v3 sites to v4 on the same server. In this method, old sites of v3 will continue running on 80 and 443 ports while sites migrated to v4 will run on 8080 and 8443 ports.

Start the migration process when the load on the server is low. This will ensure that you will not run out of CPU/RAM while running both v3 and v4 sites simultaneously. 

Requirements

  • EasyEngine v3 must be installed on the server (implied)
  • Port 8080/8443 must be free
  • Enough disk space to hold both v3 and v4 sites

Steps

Run the following command which will run a check to ensure all requirements for migration are met and will give you a report on how the migration will proceed.

./migrate.sh --dry-run --all

After ensuring requirements of script are met, you can now migrate an individual site or migrate all sites at once.

./migrate.sh <site-name>
./migrate.sh --all

You can do a test migration of a single site with ./migrate.sh <site-name> first followed by rest of the sites using ./migrate.sh --all. 

The migration script tracks sites which are already migrated and only migrate sites that haven’t been previously migrated.

After all the sites will be migrated, the script will prompt you to verify if the sites are running as expected.

You can now check your sites on example.com:8080 for HTTP site or example.com:8443 for HTTPS site.

After you confirm that sites are running as expected, the script will stop the v3 stack and v4 will switch ports from 8080/8443 to 80/443.

WordPress MU Port Limitation

Since WordPress multisite requires to be run on port 80/443, you won’t be able to verify multisite on v4. This is limitation from WordPress itself https://mu.trac.wordpress.org/ticket/189 and https://core.trac.wordpress.org/ticket/12043.

Migrating Sites on Different Server

If your existing v3 server does not have enough space or for some reason you want to migrate your site on another server, you can also do it from script.

Start the migration process when the load on the server is low. This will ensure that sites running on v3 will continue to run smoothly and won’t slow down due to disk or network I/O.

Requirements

  • A fresh server on which v4 sites will be migrated. 
  • v3 server’s public key is added to v4 server’s root user SSH authorized_keys 
  • Port 80/443 should be free on the v4 server.
  • v4 server should have enough disk space for v3 sites.

Steps

Run the following command to check if requirements for migration are met. The script will give you a report on how the migration will proceed on remote host.

./migrate.sh --dry-run --remote-host=<v4-server-hostname-or-ip> --all

If you find all good, you can either migrate sites one by one or all at once.

./migrate.sh <site-name> --remote-host=<v4-server-hostname-or-ip>

Please replace <v4-server-hostname-or-ip> with IP address or hostname of the server. Hostname is NOT site-name. 

./migrate.sh --all --remote-host=2.2.2.2
./migrate.sh --all --remote-host=abc.example.com

You can do a test migration of a single site with ./migrate.sh <site-name> --remote-host=<new-server-ip> first followed by rest of the sites using ./migrate.sh --all --remote-host=<new-server-ip>. 

The migration script tracks sites which are already migrated and only migrate sites that haven’t been previously migrated.

After all the sites will be migrated, the script will display an entry that you will need to add in/etc/hosts of your local machine to test that the sites are working.

It’s recommended to open sites in incognito/private window to ensure that sites aren’t being served from browser cache. 

After ensuring that the sites are working, You can manually update the DNS entries of all sites and point them to new server.

Cleanup

Finally, if all goes well, you need delete v3 site’s data after migration manually. This is avoid accidental data loss.