Multisite Deployment Best Practices
When deploying a multisite using the Copy Environment tool, a search and replace is performed to ensure main and subsite URLs are updated appropriately. In this article we discuss the best practices when copying a multisite network to ensure all URLs are updated correctly.
NOTE
This article refers to copying/deploying a multisite network using the WP Engine Copy Environment tool.
Best Practices
When the database is included in the Copy Environment process, a search and replace is run automatically to update URLs for the main site (the first site in the network) and any subsites to ensure they load correctly. It’s important to ensure your domain is configured correctly in both the WP Engine User Portal and the WordPress settings prior to initiating the deployment. To review the multisite domain configuration steps, see our guide.
- When using custom domains, it’s recommended to use the non-www version of URLs. For example,
domain.comand notwww.domain.com. This applies to both the main site and any subsites.
- When the main site is using a custom domain, this custom domain should be set as primary in the User Portal. Additionally, the WP Engine subdomain for the main site (EX:
install.wpengine.com) should be redirected to that custom primary domain within the User Portal. Learn more about the primary domain and domain redirects in this guide.
- Finally, we recommend mapping custom subsite domains only using the native domain mapping settings (preferred) or the domain mapping plugin (legacy). If you are using some alternate domain mapping solution then it’s possible your URLs will not be updated as expected when using the Copy Environment function. In this case, URL updates may need to be performed manually on the target environment to avoid redirects or broken URLs.
Search and Replace
The Copy Environment tool will automatically replace both the main and subsite domains on the target multisite network. Learn more about the search and replace process here. The domain that will load on the target environment will vary slightly based on your specific multisite configuration.
A search and replace will look for the source environment’s main site domain and replace it with the target environment’s main site domain. The main site domain can either be the WP Engine default domain (example.wpengine.com), or it can be a custom domain (somedomain.com). For best results, we recommend using the non-www version (domain.com) as the main site domain, and not the www version (www.domain.com).
- EX 1:
sourcedomain.comtodestinationdomain.com - EX 2:
source.wpengine.comtodestination.wpengine.com - EX 3:
domain.comtodestination.wpengine.com - EX 4:
source.wpengine.comtodestinationdomain.com
Subsite URLs will be searched and replaced in the same way: the domain is updated from source to target, and the subsite name is retained to maintain the subdomain or subdirectory formatting.
- EX 1:
site1.source.wpengine.comtosite1.destination.wpengine.com - EX 2:
source.wpengine.com/site1todestination.wpengine.com/site1
If the subsites are using custom domains, the URL will be reformatted to include that custom domain. This main site domain will be updated as normal. Both subdirectory and subdomain subsites will have their custom domains rewritten as subdomains.
- EX 1:
sourcedomain.comtosourcedomain-com.destination.wpengine.com - EX 2:
sourcedomain.comtosourcedomain-com.destinationdomain.com
Special Considerations
The amount of time the copy process will take depends on the size of the website: Larger websites will take longer to copy than smaller websites. We recommend performing a copy during a low traffic period and if you have an eCommerce website, it may be wise to also enable maintenance mode first.
There are certain situations where you may choose to include, exclude, or partially include the database in your deployment. When copying the database partially, you can choose to include or exclude specific tables. These considerations are detailed below.
If a database table exists on both the source and destination environments and is included in the copy, the table will be overwritten. We always recommend assessing which data is needed prior to copying an environment, and especially when deploying to a Production environment.
Domain Mapping Plugin (Legacy)
When using the legacy domain mapping plugin for custom subsite domains, our system will not copy the wp_domain_mapping and wp_domain_mapping_logins tables. These tables contain the information necessary to load the subsites over their assigned custom domains.
By excluding these tables automatically, only the unmapped subsite URLs will exist instead. These unmapped URLs will be searched and replaced as normal based on the examples above.
If you decide to run a partial database copy, these tables need to be included or excluded specifically based on the desired outcome.
WooCommerce
All eCommerce websites include important “live” data (such as new orders) that you do not want to be overwritten. We advise particular caution when copying to Production environments for this reason.
The database can be excluded entirely, which would only replace the file system. Or, the database can be partially copied, which could include content such as posts, but with WooCommerce tables excluded.
The WooCommerce tables we recommend excluding can be found here.
Copy a Subsite to Another Site
Copying a subsite from one environment to another, such as separating a subsite into its own single-site environment, is not possible using the Copy Environment tool. This should be done using native WordPress import/export tool, or a third party tool instead.
- Login to the dashboard of the subsite you wish to migrate
- Select Tools
- Click Export
- Select All Content
- Click Download Export File
- Login to the dashboard of the target site
- If you are migrating to another multisite, create a new subsite first
- Select Tools
- Click Import
- Select WordPress
- Click Choose File
- Select the file exported in Step 5
- Click Upload File and Import
These steps will migrate all posts, pages and media used within them however this does not migrate any themes or plugins. These will need to either be added again manually or by copying the plugin/theme directories over using SFTP or SSH Gateway.
NEXT STEP: Development Workflow Best Practices
