IMPORTANT

These docs are updated for the beta version of Shipper 1.2 which includes the ability to migrate a subsite to a single site. More about subsite to single site migration and beta 1.2 can be downloaded here.

This guide is an in-depth look at the migration features of Shipper Pro and how to move a single website or multisite network to a new location or move a subsite to a single website. The Shipper Pro plugin provides two simple options for site migration.

  1. API Migration – One-click automated export/import through secure server-to-server communication.
  2. Packaged Migration – Package and download a website in a format for easily moving to a new server location.

Use the Index on the left to quickly locate usage guidance on specific features.

If you haven’t installed Shipper yet, then you should visit the Shipper Pro page where you can explore the plugin’s many features, download the free version, and where WPMU Dev members can install Shipper Pro directly to any connected site.

IMPORTANT

If you’re moving a site from somewhere else to WPMU DEV hosting, try the migration tool available in the Hosting tab of the Hub. If you need help migrating a site or network, contact our 24/7 Support.

5.1 API Migration

Link to chapter 1

The API Migration tool allows you to import or export from either the source or destination site:

  • Export – Send a single website, multisite network, or subsite to a new location. Unwanted files and database tables can be excluded.
  • Import – Receive a complete single website or multisite network from another location. Unlike the export function, files and databases tables cannot be excluded. Sites/networks must be moved in their entirety.

Export and Import for a complete website or network can be activated from both the sending and receiving side. File exclusions and subsite-to-single-site migrations are only available when exporting a site.

Preparing for Migration

A few things need to be in place before using the API Migration tool to ship your website.

To get started you need:

  • One Destination site
  • One Source site
  • Both sites connected to your Hub via WPMU DEV Dashboard
  • Shipper installed on both sites

Local installation notes:

  • Shipper will work with local installations, but if you’re using Local by Flywheel it needs to be on NGINX
  • You can’t trigger an import of the source site from your local installation
  • You can’t trigger an import from the destination site of your local installation

5.1.1 Export

Link to chapter 1

To move the content of your existing site to a new location, from the API Migration screen, select Export.

Shipper will fetch a list of your connected sites, but unless you have many, many sites connected to the Hub, the image below may appear on screen for only a split second.

If something prevents Shipper from fetching your sites, the error screen below will appear. Click Support to contact support, and our support superheroes will help resolve the issue.

Choose Destination

Click the dropdown arrow to reveal a a list of your connected sites. Select the site you wish to export to, then click the blue arrow to proceed.

If your created or connected a new site for this migration and it isn’t showing in the list, click the Refresh button to reload the list. If the site is still not present after refreshing, then it is likely that the site is not connected to the Hub. Click Add a new site to do that before proceeding.

Migration Filters

Depending on your goal, you may not want to migrate every file associated with a site. If you’re moving a network subsite to its own domain, for example, you may want to give the site a new theme as well, or you may want to reconfigure some or all of its installed plugins. By default, the export process includes the entire selected website, but you can use filters to exclude specific files.

If you wish to migrate your entire site, click Next to run the pre-flight check, which is discussed below in the Pre-flight section of this document. Otherwise, continue to the File Exclusion section for guidance on applying filters to an export.

File Exclusion

You can exclude specific files from being migrated using the “File Exclusion Filter” tool. Add the path to the folder or files or directories you don’t include in your migration. Only place one exclusion rule per line. Shipper uses pattern matching to create filters that exclude files based on your inputs.

Shortcuts buttons are present that, when clicked, will add the correct path for the Themes, Plugins, or Uploads folders to the exclusion list. If you wish to exclude inactive theme or plugin files but want to keep those which are active, see the applicable options available under the Advanced tab.

Database Exclusion

Select the Database tab to access a series of dropdown menus that allow you to selectively exclude tables. Uncheck the box next to All to exclude the entire database.

Advanced

Select the Advanced tab to access a list of options that allow you to exclude some seldom-used files maintained by WordPress. These include:

  • Exclude spam comments
  • Exclude post revisions
  • Exclude inactive themes
  • Exclude inactive plugins

Pre-Flight Check

The Pre-Flight check scans for issues that will prevent a successful migration and server differences. If any issues are found, a Pre-flight Issues screen will appear with dropdown screens that detail the issue(s) and the recommended solution.

Issues in yellow are warnings that may or may not cause export issues and can be ignored if you wish. Issues in red, on the other hand, are errors that will definitely prevent a successful export and must be addressed before Shipper will allow the export to proceed.

Note that the Continue button is disabled while errors exist.

The Continue button will become available once all errors are resolved. If you leave the site open while addressing warnings and errors, you can return to this screen and proceed by clicking Continue.

Pre-flight check includes:

  • Shipper version is compatible on sending and receiving site
  • File system writable (working, storage, log, and temp directories)
  • Password protection is disabled
  • AWS SDK loads successfully
  • ZIP support is available
  • Package size
  • File size is valid
  • Data is valid
  • Long filename validity
  • PHP v5.5 or newer is available
  • PHP version difference – sending and receiving website use same version of PHP
  • Server operating systems match
  • Server type compatibility
  • Max Execution Time is 120 or above
  • MySQL/MariaDB versions
  • DB charset acceptable differences
  • Multisite check (Shipper does not export multisite to single or single to multisite)
  • Multisite compatibility (Shipper does not convert from subdomain to subfolder or vice versa)

Destination Database Prefix

Database tables have a default prefix added to the beginning of the name. By default, the WordPress database table prefix is wp_ . This prefix is sometimes customized.

When migrating tables with Shipper, you can migrate tables with:

  • Source’s prefix – Migrate tables with the shipping sites prefix/li>
  • Existing destination prefix – Use the existing destination prefix
  • Custom – A new custom prefix

If you wish to create a Custom prefix, use the Choose custom database prefix field for customizing the prefix during migration.

We recommend including an underscore to the end of your prefix for finding and managing database tables example newprefix_.

Click Next, the Shipper export setup wizard will close, and you will be given the option to begin the migration.

NOTE

Shipper overwrites any existing files or database tables on your destination website. Make sure you have a backup.

Click Begin Migration, and your site will be cloned to the new location.

A progress bar will display with a time estimate.

Shipper uses our advanced API to make sure the process is as stable as possible. It can take a long time to complete. It’s worth the wait. You can close the tab, and Shipper will send you an email when it is done migrating. Note, If you are migrating from a local to live the email notification is not available.

Migration Complete

If your migration is successful, you will get the message, “Your website has been successfully migrated.” along with a link to visit the site.

Clicking the Refresh button will return you to the beginning of the API Migration module.

Migration failed

If your migration fails, you will receive a notification that, “Something went wrong with your migration.”

Clicking the Try Again button will allow you to rerun the migration.

Clicking the Check logs button will open your migration logs. More information about logs can be found under the Migration Logs section below.

Troubleshooting Tips

If your migration fails because you ignored a pre-flight check warning, you can try and resolve the warnings and rerun the migration.

Migrating between two different hosts often causes migrations to fail. We recommend contacting support before attempting to migrate between hosts.

Canceling a migration after it begins can break the destination site, although in most cases it can be fully recovered. Be sure you are ready to begin before initiating the process.

NOTE

Members with access to our 24/7 live support also get unlimited site migration support at no additional cost. If you are experiencing issues with Shipper, talk with our support team or try the package method for a more reliable migration experience.

5.1.2 Import

Link to chapter 1

The Import wizard process includes:

  • Choose source
  • Pre-flight check
  • Set your destination database prefix

Choose Source

Click the dropdown arrow to reveal a a list of your connected sites. Select the site you wish to import, then click the blue arrow to proceed. Files cannot be excluded during import, but they can be excluded during export. If you need to exclude files, conduct the process from the source site and use the export function.

Pre-flight checks

The Pre-Flight check scans for issues that could prevent a successful migration. If any issues are found, a Pre-flight Issues screen will appear with dropdown screens that detail the issue(s) and their recommended solution.

Issues in yellow are warnings that may or may not cause export issues and can be ignored if you wish. Issues in red, on the other hand, are errors that will definitely prevent a successful export and must be addressed before Shipper will allow the export to proceed.

Database Prefix

Database tables have a default prefix added to the beginning of the name. By default, the WordPress database table prefix is wp_. This prefix is sometimes customized.

When migrating tables with Shipper, you can migrate tables with:

  • Source’s prefix – Migrate tables with the shipping sites prefix/li>
  • Existing destination prefix – Use the existing destination prefix
  • Custom – A new custom prefix

If you select to create a Custom prefix, use the “Choose custom database prefix” field for customizing the prefix during migration.

We recommend including an underscore to the end of your prefix for finding and managing database tables example newprefix_.

Click Next button, the Shipper export setup wizard will close, and you will be given the option to begin the migration.

5.1.3 Multisite Migration

Link to chapter 1

When using Shipper to migrate a Multisite network, you are given the option to:

  • Migrate the whole network
  • Migrate a Subsite to a Single site

Whole network

Choosing Whole Network will migrate your entire Multisite to the new location.

From this point on, the wizard steps are the same for Multisite as they are for the Export process, so see that section of this guide for guidance on the following:

  • Choose Destination
  • Migration Filters
  • Run Pre-flight Check
  • Customize Destination Database

Subsite to Single Site

You can use Shipper to extract a subsite from a Multisite network and migrate to a single site.

Choose Subsite

When you select subsite to single site, a list of subsites will appear in the dropdown. Select a site to migrate and then click Next.

Shipper will prepare your site for migration.

Choose Destination

You can export the subsite to any other single site connected to the Hub. Use the dropdown menu to select your Hub selected website.

Migration Filters

By default, the package includes your entire subsite. However, if you don’t want to migrate any specific files, folders, or database tables, you can use the filters to exclude them from your package.

If you wish to migrate your entire site without setting any Migration Filters, click next to run the pre-flight check.

File Exclusion

You can exclude specific files from being migrated using the “File Exclusion Filter” tool. Add the path to the folder or files or directories you don’t include in your migration. Only place one exclusion rule per line.

Themes, Plugins, and Upload exclusion shortcuts are available as links above the File Exclusions Filter field.

Clicking a shortcode will automatically add the file path to the next blank line.

Database Exclusion

Selecting the Database tab allows you to exclude tables by simply clicking a checkmark next to the Database table you would like to exclude.

Uncheck the box next to the All option to exclude the entire database.

Use the arrow next to each table to navigate to a specific table.

Advanced

The Advanced tab can be used to filter the additional content of your package. Options include:

  1. Exclude spam comments
  2. Exclude post revisions
  3. Exclude inactive themes
  4. Exclude inactive plugins

Click Next to run the pre-flight check.

Pre-Flight Check

The Pre-Flight check scans for issues that will prevent a successful migration and server differences. If any issues are found, a Pre-flight Issues screen will appear with dropdown screens that detail the issue(s) and the recommended solution.

Issues in yellow are warnings that may or may not cause export issues and can be ignored if you wish. Issues in red, on the other hand, are errors that will definitely prevent a successful export and must be addressed before Shipper will allow the export to proceed.

Destination Database Prefix

Database tables have a default prefix added to the beginning of the name. By default, the WordPress database table prefix is wp_ . This prefix is sometimes customized.

When migrating tables with Shipper, you can migrate tables with:

  • Source’s prefix – Migrate tables with the shipping sites prefix/li>
  • Existing destination prefix – Use the existing destination prefix
  • Custom – A new custom prefix

If you select to create a Custom prefix, use the “Choose custom database prefix” field for customizing the prefix during migration.

5.2 Package Migration

Link to chapter 2

The Package Migration module creates a zip file of your WordPress website, Multisite network, or subsite for manually moving to a new location.

The Package Migration option has two menu items:

  1. Package
  2. Settings

Package

When visiting the Package menu option for the first time, click Create Packageto open the Shipper Package wizard module.

From the Create Package module, you can use the default name or create a custom package name in the Package Name field.

Choose whether you want to restrict access to the installer file with a password. When enabled, you’ll be asked to enter your chosen password into the Installer Password field before beginning the packing process. Click Continue to advance to the next step.

By default, the package includes your entire website. However, if you don’t want to migrate any specific files, folders, or database tables, you can use the Filter Exclusion Field to exclude them from the package. Learn more about filter exclusion rules under Migration Filters in the Export section.

Click Build Package to run your pre-flight check and automatically begin building your site archive.

Keep this modal open during the build process. This may take anywhere from a few seconds to a couple of minutes, depending on the size of your site.

Ready to Migrate

Once your package is finished you will be given instructions for downloading and migrating your site.

  1. Download package archive and installer – The first step is to download both the archive ZIP file and the installer.php file. You’ll need both of these to complete the migration. Click the provided icons to download both files.
  2. Upload both files to your destination server – The next step is to upload both the package archive and installer files to the root directory of your destination server. We recommend uploading them via SFTP using an FTP client such as FileZilla. You’ll need an FTP account to connect to your destination server, and if you are not sure how to create an FTP account, please contact your hosting support.
  3. Visit installer.php on your destination server and follow the instructions – Once you’ve uploaded both the archive and installer files to your new server, visit the installer.php in your browser. To do this, open up your web browser and type in your new website domain along with /installer.php. i.e., https://example.com/installer.php. Follow the instructions on the installer wizard to complete the migration.

Additional Details about the package size can be accessed by using the arrow to spin open more information about the package, including:

  • Package Name
  • Date the package was created
  • Size of the package
  • File exclusions (if any)
  • Database Exclusions (if any)
  • Advanced Exclusions (if any)
  • If the package is password protected

You can also Delete the file or jump to the logs by clicking the View Logs button.

Use the New Package button if you would like to rebuild the package before migrating the site.

Settings

Storage Directory

The storage directory settings allow you to configure your package storage location as per your need.

By default, Shipper creates a default directory to keep your package. You can change the storage directory by replacing the path in the location field.

Exclude from package build

Recommended: This setting excludes the storage directory, and all of its content and sub-folders from package builds.

Database

The database settings allow you to customize the database build process of your packages.

Choose the query limit to build SQL scripts. It is recommended you use a lower query limit on a shared or budget host. A higher limit size will speed up the build time, but it will use more memory.

Archive

The archive setting allows you to customize the buffer size for the build process of your packages.
Buffer size is the size of each chunk of the archive in multi-threaded mode. A larger value will result in a faster build but is less stable on some shared or budget host providers.

After making changes be sure and click Save Changes.

Multisite

Shipper allows you to package your entire Multisite network or just a subsite for migration to a single site install.

Whole Network

Choosing the Whole Network works the same as a single site package.

Subsite Only

When choosing subsite only, you will be required to select the specific subsite to package. Once you’ve selected the subsite you would like to use, the rest of the settings are the same as a single site package.

5.3 Migration Wizard

Link to chapter 3

When loading a package to a new site, the package wizard will guide you through the process.

  1. Installer Password – If a password was added when building the package you will be required to enter the password to move forward. The package password is listed under the Additional Details section when the site was packaged. Click next to proceed.
  2. Requirements Check – The Shipper installer will run a check to ensure the new server meets the requirements to unpackage the site.
  3. Database Connection – It is recommended that you create a new database when migrating your site. Click the Test Connection & Deploy button to proceed to connect to create a new database. If you choose to connect to an existing database you will need to enter the following information:
  • Database host name
  • Port
  • Database name
  • Database username
  • Database password
  • Database prefix

Where these details are located will vary from host-to-host. Contact your hosting provider if you need assistance finding information about your database connection.

  1. Deploy Website – A progress bar will appear while the site files are unpackaged and the database is installed. You will need to keep the browser window open while this process completes. This can take some time depending on size.
  2. Update Data – By default, the site URL, site path, and site title included in the package will be used. You can customize them here.
  3. Finish & Cleanup – Use the Admin Login button to check your site. If the migration looks successful, use the Run Cleanup button to remove the installer files. It is highly recommended that you remove installer files as soon as the migration is complete and verified because they contain sensitive information.

5.4 Tools

Link to chapter 4

Logs

This shows Shipper’s latest logs and can be used to debug any issues you are having. Logs list the date and time of each migration action.

Use the Download option to download your logs as a text file.

NOTE

Logs will be automatically refreshed each time you initiate a new migration.

Note:

System Information

The system information provides critical information about your server setup. It will give you the most up to date information about your stack.

Use the dropdown to switch between:

  • PHP
  • MySQL
  • Server
  • WordPress

PHP

  • max_execution _time
  • open_basedir
  • upload_max_filesize
  • post_max_filesize
  • memory_limit
  • zip_archive
  • version
  • version_major
  • has_suhosin
  • aws_support

MySQL

  • max_allowed_packet
  • version
  • charset
  • collate
  • Server

    • type
    • os
    • working_directory
    • working_directory_writable
    • working_directory_visible
    • working_directory_accessible
    • temp_directory
    • temp_directory_writable
    • temp_directory_visible
    • temp_directory_accessible
    • storage_directory
    • storage_directory_writable
    • storage_directory_visible
    • storage_directory_accessible
    • log_directory
    • log_directory_writable
    • log_directory_visible
    • log_directory_accessible
    • access_protected

    WordPress

    • WP_CONTENT_DIR
    • WP_PLUGIN_DIR
    • MULTISITE
    • SUBDOMAIN_INSTALL
    • version
    • shipper_version
    • UPLOADS

5.5 Settings

Link to chapter 5

The settings module provides additional configuration options for Shipper and your default site migration options.

5.5.1 API

Link to chapter 5

Working Directory

Shipper temporarily stores progress information and other temporary files generated while migration in a working directory.

By default, we use the temp directory as the working directory. However, because of some restrictions implied by a few hosts, the migration tends to fail. In such cases, you can try enabling the use uploads directory as working directory option, and Shipper will create a working directory in your uploads folder.

Advanced Options

  • Do not replace domain name in email – By default, Shipper replaces all the instances of your source domain with the destination domain. However, if you use an email on your site linked with your source domain and don’t want the email to be changed, then keep this option enabled.
  • Do not migrate wp-config file – Enable this option if you don’t want to migrate the wp-config file from your source site to the destination site.
  • Click save changes after making any changes to the API Migration settings.

5.5.2 Accessibility

Link to chapter 5

Shipper offers a High Contrast Mode to increase the visibility and accessibility of the elements and components of the plugin to meet WCAG AAA requirements.

High Contrast Mode

To enable high contrast mode, toggle Enable high contrast mode and click the Save Changes button.

5.5.3 Data

Link to chapter 5

This gives you control over how Shipper data is managed and stored when uninstalling your plugin.

Uninstallation

Choose whether to keep or remove transient data. Select the Keep option to save and Remove to delete the data.

Reset Settings

Need to start fresh? Use the Rest button to roll back to the default Shipper settings.

Remember to click save changes after adjusting Shipper data settings.

NOTE

Rest will instantly revert all settings to their default states without touching your data.

5.5.4 Notifications

Link to chapter 5

Shipper sends email notifications when a migration completes or fails.

You can turn off these notifications by toggling the “Send an email when migration completes” option off.

Email Notifications

By default, only the site admin will receive notifications. Use the Add Recipient button to send notifications to additional users.

You can also choose only to send emails when a migration fails by using the checkbox next to “Only emails when migration fails.”

Remember to click save changes after adjusting Shipper notification settings.

5.5.6 Permissions

Link to chapter 5

Permissions

By default, only the user who authenticated the WPMU DEV Dashboard can access Shipper. The permissions settings allow you to Enable other users to access Shipper.

To add new users, click the Add User button. In the search user field, type your username, add click the Add button.

To delete a user, click the trashcan icon.

Remember to click save changes after adjusting Shipper permissions settings.

5.6 Support

Link to chapter 6

After reading this guide, if you still have questions regarding Shipper, don’t hesitate to start a live chat with our support Superheroes or submit a support ticket using the Support tab of your WPMU Dev Dashboard.

Navigate to WPMU DEV DASHBOARD > SUPPORT > NEW TICKET to submit a support ticket.