Configure
Learn how to configure your WordPress Multisite.
This section is intended for customers who have had a WordPress Multisite upstream created for them by a Pantheon employee. If you do not have a WordPress Multisite upstream, refer to the introduction page of this guide. After you create a new site on the Multisite upstream and visit the Dev environment's site URL, you should be redirected to the WordPress web-based installer.
Adjust placeholders in code snippets as needed throughout this guide. This includes placeholders such as <site> and <env> in Terminus commands, in addition to placeholders in brackets <> in larger code blocks.
Installing WordPress Multisite
Choose the best option below to install WordPress multisite based on your site setup and preferences.
Complete the steps below after spinning up a new WPMS site from the correct Custom Upstream in your workspace.
Navigate to the WordPress Admin dashboard, select Tools, and then select Network Setup.
Select either the Sub-domains or Sub-directories option.
Enter the Network Title and Network Admin Email, and then click Install.
Finalize the installation by following steps provided from the GUI or by following the next steps.
Navigate to Code in the Dev tab of your Site Dashboard.
Click Connect with SFTP.
Click Open SFTP client.
If you run into issues, please refer to Pantheon's SFTP documentation.
Open the
codefolder in your SFTP client, and download your site'swp-config.phpfile.Locate the
/* That's all, stop editing! Happy Pressing. */line, and add the following code above this line to enable the WPMS configuration.wp-config.phpdefine( 'WP_ALLOW_MULTISITE', true ); define( 'MULTISITE', true ); define( 'SUBDOMAIN_INSTALL', false ); // Set this to TRUE for Subdomains // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); define( 'PATH_CURRENT_SITE', '/' ); define( 'SITE_ID_CURRENT_SITE', 1 ); define( 'BLOG_ID_CURRENT_SITE', 1 ); /* That's all, stop editing! Happy Pressing. */
Make sure Terminus is installed and authenticated before you complete the steps below.
Set the site's connection mode to SFTP:
terminus connection:set <site>.dev sftpUse Terminus to execute the
wp core multisite-installcommand. You can refer to the WordPress documentation for more information.Information:NoteThe default behavior for this command is to create a WordPress Multisite with the subdirectory configuration. To create your network with the subdomain configuration, add the
--subdomainsflag.terminus wp <site>.<env> -- core multisite-install --title=<site-title> --admin_user=<username> --admin_email=<email>After you successfully install a new WordPress Multisite, a message displays that is similar to the following:
terminus wp sitenetworks.dev -- core multisite-install --title="WordPress Multisite" --admin_user=aghost --admin_email=[email protected] Admin password: abcdefgnotarealpassword Created single site database tables. Set up multisite database tables. Added multisite constants to 'wp-config.php'. Success: Network installed. Don't forget to set up rewrite rules (and a .htaccess file, if using Apache).The
wp core multisite-installcommand that you ran modified thewp-config.phpfile. The modification sets theDOMAIN_CURRENT_SITEconstant that assigns a specific URL to your WordPress Multisite which must be updated to work on Pantheon.Navigate to Code in the Dev tab of your Site Dashboard.
Click Connect with SFTP.
Click Open SFTP client.
If you run into issues, please refer to Pantheon's SFTP documentation.
Open the
codefolder in your SFTP client, and download your site'swp-config.phpfile.Locate the configuration added by WP-CLI, and modify the line that sets
DOMAIN_CURRENT_SITEto a hardcoded URL. We have provided a constant inwp-config-pantheon.php,PANTHEON_HOSTNAMEthat defaults to a dynamic URL for web requests ($_SERVER['HTTP_HOST'], when available), while providing a fallback for non-web requests (notably workflows like search and replace) that do not have a$_SERVER['HTTP_HOST']value.wp-config.phpdefine( 'WP_ALLOW_MULTISITE', true ); define( 'MULTISITE', true ); define( 'SUBDOMAIN_INSTALL', false ); // Set this to TRUE for Subdomain installs. // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); define( 'PATH_CURRENT_SITE', '/' ); define( 'SITE_ID_CURRENT_SITE', 1 ); define( 'BLOG_ID_CURRENT_SITE', 1 );Refer to the
wp-config.phpdocumentation if you have an environment specific configuration.Save your changes and upload the
wp-config.phpfile to Pantheon's Dev environment.
A warning may appear in the WordPress dashboard that you need to update your .htaccess file. Since Pantheon used Nginx and your site is already pre-configured for Multisite use by your Account Manager, you can ignore this warning.
The Bedrock-based WordPress (Composer Managed) upstream uses Config::define() and config/application.php instead of traditional define() statements in wp-config.php. You will not be able to use WP-CLI via Terminus to enable multisite as documented above in a standard multisite configuration. This section provides guidance on how to set up a WordPress Multisite using the WordPress (Composer Managed) upstream.
Set the site's connection mode to Git:
terminus connection:set <site>.dev gitOpen the
config/application.phpfile in your site's codebase and add the following line anywhere above theConfig::apply();line:Config::define( 'WP_ALLOW_MULTISITE', true );Visit your development site's WordPress admin and navigate to Tools > Network Setup.
Choose Sub-domains or Sub-directories (depending on your needs), fill in the Network Title and Admin Email, and click Install.
You will be given instructions to update your
config/application.phpfile. Below where you added theWP_ALLOW_MULTISITEline, copy and paste the code provided. TheSUBDOMAIN_INSTALLvalue will betrueorfalsedepending on the option you chose in the previous step. For example, if you chose subdirectories, yourconfig/application.phpfile should look like this:Config::define( 'MULTISITE', true ); Config::define( 'SUBDOMAIN_INSTALL', false ); // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. Config::define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); Config::define( 'PATH_CURRENT_SITE', '/' ); Config::define( 'SITE_ID_CURRENT_SITE', 1 ); Config::define( 'BLOG_ID_CURRENT_SITE', 1 );Save your changes and commit them to your Git repository. WordPress will prompt you to log back in after you push the changes.
Log into your site. When you log back into your WordPress admin dashboard, you will see a new My Sites menu item in the top left corner. This is where you can manage your network of sites. You now have a WordPress subdirectory multisite network set up on a WordPress (Composer Managed)-based upstream.
Currently, the built-in dashboard WordPress Multisite Search and Replace does not support Composer-based WordPress multisites. To perform a search and replace on a WordPress (Composer Managed) multisite, you will need to use WP-CLI via Terminus manually. For more information, see our WordPress Multisite Search and Replace guide.
Develop the Multisite
Congratulations on setting up your first WordPress Multisite. When you log in to the WordPress Dashboard, you'll see a My Sites menu item in the toolbar:
You will have one site and you can create another if needed. If you chose to use WordPress Multisite with subdirectories, you'll be able to access the site right away. If you chose to use subdomains, you'll need to map a custom hostname to the environment before you can access the new environment.
Mapping Custom Hostnames
Map Custom Hostnames (subdomain configurations only)
Upon installation and configuration the main site will load properly (e.g., dev-<example>.pantheonsite.io). However, additional network sites created will fail to load because pantheonsite.io doesn't support sub-sub-domains (e.g., <new-sub-site>.dev-<example>.pantheonsite.io). WordPress Multisites using a subdomain configuration require custom domains to be mapped to each network site in order to load properly.
Access the domain's DNS settings wherever they are managed.
Create a wildcard CNAME
*.dev.example.comthat maps to the Dev environment's platform domain,dev-<example>.pantheonsite.io. Doing so ensures all hostnames mapped to the environment will load without additional DNS records.Map domains to the Pantheon Dev environment using Terminus. For example:
# add dev.example.com for the network's main site terminus domain:add <site>.dev dev.example.com # add subsite.example.com for a subsite on the network terminus domain:add <site>.dev subsite.example.comUpdate the conditional
DOMAIN_CURRENT_SITEdefinition in yourwp-config.phpfile to accommodate the site's new domains.
After these steps are complete, both sites on the WordPress Multisite should load with their new URLs.
Explore the WordPress Network Dashboard to become familiar with the variety of additional settings. You can review the options that are available for each site you create, manage users across WordPress Multisite, and learn about the network settings. After you explore the WordPress Network Dashboard, learn how to use the WordPress Multisite with the Pantheon Workflow.
Troubleshooting
"Undefined index: HTTP_HOST" PHP Warnings
If you see notices in your PHP logs similar to PHP Warning: Undefined index: HTTP_HOST, this is likely because there is some code in your configuration that is using $_SERVER['HTTP_HOST'] without checking if it is set. This is a common issue with WP-CLI, as it does not have the same environment variables set as a web request. Instead of relying on $_SERVER['HTTP_HOST'], you can use the PANTHEON_HOSTNAME constant, which is set by Pantheon in wp-config-pantheon.php and is available in all environments.
define( 'DOMAIN_CURRENT_SITE', PANTHEON_HOSTNAME );