5. Shipper

When 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.

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.

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.

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.

Some 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.

To 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.

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.

When 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:

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

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:

• Migration Complete
• Migration Failed

When 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.

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:

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

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:

• Migration Complete
• Migration Failed

To 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:

• Run Pre-flight Check
• Customize Destination Database

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:

• Migration Complete
• Migration Failed

When 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:

• Run Pre-flight Check
• Customize Destination Database

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:

• Migration Complete
• Migration Failed

When 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:

• Run Pre-flight Check
• Customize Destination Database

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:

• Migration Complete
• Migration Failed

The 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.

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.

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.

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.

Pagination 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.

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.

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. 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.

The 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