5. Shipper
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.
- API Migration – One-click automated export/import through secure server-to-server communication.
- Package 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 and WPMU DEV members can install it directly to any connected site.
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 Shipper Dashboard
Copy chapter anchor to clipboardThe Shipper Dashboard provides you with a quick overview of previous migrations, information about both available forms of migration (API & Package migration), as well as handy links to the most used settings screens.
5.2 Package Migration
Copy chapter anchor to clipboardThe 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:
- Package
- Settings
5.2.1 Package
Link to chapter 2When visiting the Package menu option for the first time, click Create Package to open the Shipper Package wizard modal.
From the Create Package modal, you can use the default name or create a custom package name in the Package Name field.
Once you have downloaded your migration package as seen in the Ready to Migrate step below, do not rename the file. That will cause the migration deployment to fail because the installer file will look for an archive with the name you set here.
In multisite installations, you will see an additional option in the Create Package modal where you can choose to package the entire multisite or just one subsite.
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.
- 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.
- 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.
- 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.
Migration Wizard
When uploading a package to a new site, the package wizard will guide you through the process.
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.
Requirements Check
The Shipper installer will run a check to ensure the new server meets the requirements to unpackage the site.
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 hostname
- 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.
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.
Update Data
By default, the site URL, site path, and site title included in the package will be used. You can customize them here.
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.2.2 Settings (Package)
Link to chapter 2Some of the Package Migration settings are slightly different for sites hosted by WPMU DEV compared to those hosted by 3rd-party providers. So let’s go over those differences first.
WPMU DEV Hosted
The Database and Archive settings are much simpler for WPMU DEV hosted sites.
- Database – You can optionally adjust the Query Limit for the package build here. A higher number here will speed up the build but will consume more memory. If in doubt, leave it at the default setting.
- Archive – Optionally adjust the number of files to be processed per archive chunk. A higher number here will speed up the build but may be a bit unstable on our lower hosting plans. If in doubt, leave it at the default setting.
3rd-Party Hosted
On 3rd-party hosted sites, the Database and Archive settings each have an additional option enabling you to select the most efficient one according to your hosting plan.
Database
Select either the MySQLDump or PHP Code option for the database build. We recommend the MySQLDump method where possible as that’s the more efficient method.
However, that option requires the PHP shell_exec function to work. If your host does not support that, you’ll see this message and may need to use the PHP Code option instead.
If you select the PHP Code option, you can adjust the Query Limit for the package build as seen above for WPMU DEV hosted sites.
Archive
Select either the Shell Zip or PHP ZipArchive option for the package archive. We recommend the Shell Zip method where possible as that’s the more efficient method.
However, that option requires the PHP shell_exec function to work. If your host does not support that, you’ll see this message and may need to use the PHP Code option instead.
If you select the PHP ZipArchive option, you can adjust the File Limit for the package build as seen above for WPMU DEV hosted sites.
All Hosts
Safe Mode
If your hosting plan offers only limited resources, you can enable the Safe Mode option to ensure Shipper never exceeds what is set for max_execution_time on your server. This should not be an issue with WPMU DEV hosted sites as max_execution_time is set to 300 for all hosting plans.
5.3 API Migration
Copy chapter anchor to clipboardThe 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, multisite network or subsite from another location. Unlike the export function, files and databases tables cannot be excluded. Sites/networks must be moved in their entirety.
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.3.1 Export Single Site to Single Site
Link to chapter 3To export the content of your existing single site to a new single site location, from the API Migration screen, select Export.
You’ll be prompted to enter your WPMU DEV password as a security measure before proceeding with the migration.
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 single site you wish to export to, then click the blue arrow to proceed.
If you 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.
If Shipper is not yet active on the destination site, no worries, the plugin will be auto-installed there for you and readied for the migration. You’ll see this screen for a few seconds while that is being done.
Migration Filters
By default, the export process includes the entire selected website, but depending on your goal, you may not want to migrate every file associated with a site. 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 want to include in your migration. Place only one exclusion rule per line.
Shortcut 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.
The exclusion filter uses pattern matching to exclude files based on your rules, and wildcards ( * ) can be used here as well. So the following examples would work just fine in this field:
- .zip – will exclude all files with the ZIP extension.
- /entire-folder/ – will exclude the folder with this specific name.
- /folder/file.zip – will exclude this specific file in this specific folder.
- /folder/*.txt – will exclude all files with the TXT extension at the end, but only in the directory named FOLDER.
- /folder/sub-folder/*.* – will exclude all files with any extension in the directory SUB-FOLDER which is a subdirectory of FOLDER, but other directories inside FOLDER/SUB-FOLDER would not be affected.
- */IgnoreDir/*.* – will exclude all files inside any directory called IGNOREDIR.
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
- 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.
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 modal.
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, or if the auto-install of Shipper on the destination site fails, 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.
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.3.2 Export Multisite to Multisite
Link to chapter 3When using Shipper to migrate a Multisite network, you are given the option to migrate the whole network or migrate only a Subsite to a Single site. This chapter of this usage guide deals with migrating the entire network. To migrate only a subsite, see the Export Subsite to Single Site or Import Subsite to Single Site chapters below.
Choosing Whole Network in the Migration Type modal will migrate your entire Multisite to the new location.
You will then be prompted to enter your WPMU DEV password as a security measure.
From this point on, the wizard steps are the same for Multisite as they are for exporting a single site, so see that section of this guide for guidance on the following:
The notification processes for successful and failed migrations are also identical as when exporting a single site, so please see the following sections for details on those if needed:
5.3.3 Export Subsite to Single Site
Link to chapter 3When using Shipper to migrate a Multisite network, you are given the option to migrate the whole network or migrate only a Subsite to a Single site. This chapter of this usage guide deals with migrating only a subsite. To migrate the entire network, see the Export Multisite to Multisite or Import Multisite to Multisite chapters.
If you’re wanting a speedy walk-through of how to migrate a subsite to a single site, you can check out our blogs. Particularly, how to Migrate a WordPress Multisite Subsite to a Single WordPress Site is a fantastic source of information.
When you select Subsite to Single Site in the Migration Type modal, a list of subsites will appear in the dropdown. Select a subsite to migrate and then click Next.
You will then be prompted to enter your WPMU DEV password as a security measure.
On the next screen, select the single site you wish to migrate this subsite to. Be careful here as all your connected sites still appear in this list, including any multisites you may have, and you wouldn’t want to overwrite a multisite in error.
From this point on, the wizard steps are the same for a subsite as they are for exporting a single site, so see that section of this guide for guidance on the following:
The notification processes for successful and failed migrations are also identical as when exporting a single site, so please see the following sections for details on those if needed:
5.3.4 Import Single Site to Single Site
Link to chapter 3To import the content of another single site to your site, from the API Migration screen, select Import.
Just as with the export process, you’ll be prompted to enter your WPMU DEV password as a security measure.
Choose Source
Click the dropdown arrow to reveal a list of your connected sites. Select the single site you wish to import, then click the blue arrow to proceed
As noted at the beginning of this document, you cannot import a local install. If that is what you need to migrate, you’ll need to run the process as an export instead. Also note that files and database tables cannot be excluded during import, but they can be excluded during export. See the Export Single Site to Single Site chapter for more info.
From this point on, the wizard steps are the same for importing a single site as they are for exporting a single site, so see that section of this guide for guidance on the following:
The notification processes for successful and failed migrations are also identical as when exporting a single site, so please see the following sections for details on those if needed:
5.3.5 Import Multisite to Multisite
Link to chapter 3When using Shipper to migrate a Multisite network, you are given the option to migrate the whole network or migrate only a Subsite to a Single site. This chapter of this usage guide deals with migrating the entire network. To migrate only a subsite, see the Export Subsite to Single Site or Import Subsite to Single Site chapters below.
To import the content of another multisite to your multisite, from the API Migration screen, select Import.
Just as with the export process, you’ll first be prompted to enter your WPMU DEV password as a security measure.
Choosing the source multisite is the same as when choosing the source site for importing a single site to another single site. So see that section above for details: Choose Source
From this point on, the wizard steps are the same for importing a multisite as they are for exporting a single site, so see that section of this guide for guidance on the following:
The notification processes for successful and failed migrations are also identical as when exporting a single site, so please see the following sections for details on those if needed:
5.3.6 Import Subsite to Single Site
Link to chapter 3When using Shipper to migrate a Multisite network, you are given the option to migrate the whole network or migrate only a Subsite to a Single site. This chapter of this usage guide deals with migrating only a subsite. To migrate the entire network, see the Export Multisite to Multisite or Import Multisite to Multisite chapters.
To import the content of a subsite in another multisite to your single site install, from the API Migration screen, select Import.
Just as with the export process, you’ll first be prompted to enter your WPMU DEV password as a security measure.
Choosing the source multisite is the same as when choosing the source site for importing a single site to another single site. So see that section above for details: Choose Source
Once selected, Shipper will recognize your selection as a multisite and will prompt you to select the subsite you wish to import into your single site.
From this point on, the wizard steps are the same for importing a subsite as they are for exporting a single site, so see that section of this guide for guidance on the following:
The notification processes for successful and failed migrations are also identical as when exporting a single site, so please see the following sections for details on those if needed:
5.4 Settings
Copy chapter anchor to clipboardThe settings module provides additional configuration options for Shipper and your default site migration options.
5.4.1 API
Link to chapter 4The API Migration section gives you a few extra options for managing how your migration should be handled by Shipper when using the API option.
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.4.2 Accessibility
Link to chapter 4Shipper 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.4.3 Data
Link to chapter 4This 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.
Rest will instantly revert all settings to their default states without touching your data.
5.4.4 Notifications
Link to chapter 4Shipper 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.
WPMU DEV members are authorized up to 10 free email accounts that can be configured in minutes to display the member’s domain in the email address. See our Email Hosting product page for details.
5.4.5 Pagination
Link to chapter 4Pagination lets you choose the number of entries per page for the pre-flight results, such as large files and files with large path listings. By default, Shipper displays 10 entries.
5.4.6 Permissions
Link to chapter 4Permissions
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.5 Tools
Copy chapter anchor to clipboardThe Tools section has two menu items:
- Logs
- System Information
5.5.1 Logs
Link to chapter 5This 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. If you also want to view which table was exported, you can add define( 'SHIPPER_DEBUG', true )
to your wp-config.php file.
Use the Download option to download your logs as a text file.
Logs will be automatically refreshed each time you initiate a new migration.
5.5.2 System Information
Link to chapter 5The system information provides critical information about your server setup. It will give you the most up to date information about your site.
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.6 Support
Copy chapter anchor to clipboardAfter 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.
