MigrateWP MigrateWP

Home/Docs/Getting started

Getting started

Four short steps: download the script, alias it, describe your sites, and give it SSH access.

1. Download the latest release

Releases are published on GitHub:

github.com/Tartan-Web-Design/migrateWP/releases

Unpack it somewhere sensible — anywhere you are happy to keep a script and its config file. Then open Terminal and cd into that folder.

$ cd ~/mwp
$ ls
LICENSE  README.md  migratewp.conf  migratewp.sh

2. Create the mwp alias

MigrateWP is easier to live with behind a short alias. Add one to your shell profile, using the real path to the script:

$ echo 'alias mwp="bash /Users/username/yourfolder/migratewp.sh"' >> ~/.zshrc

Then restart your terminal session so the alias is picked up:

$ exec zsh

On an older Mac? If your shell is Bash rather than Zsh, append the alias to ~/.bash_profile instead and run exec bash.

From here on, mwp stands in for bash migratewp.sh. Everything below assumes the alias is in place.

3. Describe your sites in migratewp.conf

MigrateWP reads its settings from migratewp.conf, which sits next to the script. Each site is one case block. A two-site config looks like this:

#! /bin/bash

logUserName="yourNameHere"

case $site in

    site1name)
        sshUser="username@8.8.8.8"

        remoteURL="example.com"
        remotePath="/var/www/vhosts/example.com/httpdocs/wp-content/"
        localURL="example.local"
        localPath="/Users/Scott/Local Sites/example/app/public/wp-content/"

    ;;

    site2name)
        sshUser="sshUser@8.8.8.8"

        remoteURL="site2.org"
        remotePath="/var/www/vhosts/site2.org/httpdocs/wp-content/"
        localURL="site2.local"
        localPath="/Users/Scott/Local Sites/site2/app/public/wp-content/"

    ;;

  *)
      usage
      exit
    ;;

  esac

In short:

  • Put your own name in logUserName. It is used to label the migrations that come from your machine in the changelog.
  • Replace site1name with the name you want to type on the command line for that site.
  • Set sshUser to a user with permissions over the folder holding the WordPress installation.
  • Fill in the wp-content paths and site URLs for both ends.

Every option is covered in detail on the Configuration page.

Keep the fallback. Leave the *) block at the end of the case statement in place. It is what prints the usage message when you mistype a site name, instead of MigrateWP running against empty paths.

4. Set up SSH access

MigrateWP reaches the remote server several times during a migration, so it is worth adding your key to the SSH account rather than typing a password at each step.

Copy your public key:

$ cat ~/.ssh/id_rsa.pub

Then add it to the server. On Plesk:

  1. Install the SSH Keys Manager Plesk extension.
  2. Paste the public key into the Plesk SSH keys page for the site, at Subscriptions → sitename → SSH Keys.
  3. Set Access to the server over SSH to /bin/sh, at Subscriptions → sitename → Connection Info → Manage access.

The SSH user for a Plesk site is the system user for that webspace, which you will find under Subscriptions → sitename → Connection Info.

No separate SSH subdomain needed. On Plesk at least, the SSH credentials are the same as those for the main domain.

5. Run your first migration

Start your Local site so the local database is running, then push:

$ mwp push mysite

MigrateWP will run its pre-flight checks, back up the remote files and database, sync wp-content, move the database across and run the search and replace on the site URL. If a check fails it stops before changing anything.

To confirm what happened, ask for the site's history:

$ mwp report mysite

And if the migration turned out to be a mistake:

$ mwp rollback mysite
← Requirements Configuration →