/ WordPress

Running a local WP instance exported from WPEngine

While WPE is a fantastic host for managed WordPress sites, with helpful environment options... there will probably come a day when it's easier to work with a local instance of your site. Maybe you'd like to make some tweaks to a theme, or you need to run a CLI tool that WPE doesn't allow. There are a couple small quirks in the WPE environment to contend with, but process of configuring a local copy of a WPEngine is mostly painless.

Download a copy of your site's WP files

Under the 'Backup Points' section of your WPE dashboard, there should be a set of daily checkpoints, each of which contains all the non-database assets needed to run your site. Select the most recent backup and choose "Download Zip." It will take a few minutes to prepare the download if your site contains a large amount of images, but not as long as you might fear. I prefer to download the entire backup, with /uploads and /plugins to ensure you fully simulate the remote site locally. The backup point includes all the WP core files, too—it's a complete install.

Screen-Shot-2019-03-12-at-5.05.56-PM

Uncompress the backup package and point your local WP server (Valet, Trellis, VVV) at the new site directory.

Create a local copy of the remote site's MySQL database

Now that you have the WordPress files in a local dir, it's time to snag the database used by the live site, too. The WPE backup point does include a copy of the db under wp-content/mysql.sql but I find it's easier to use phpMyAdmin, to get a little more control over how the export is formatted. Inside the WPE admin panel, there's a link directly to the WPE phpMyAdmin. Under the 'Export' tab in phpMyAdmin, you'll see the option to download a direct copy of the live db. Choose the 'custom' option so you can pick just the main db. You want the one that starts with 'wp_', not 'snapshot_'... the snapshot one is a WPE system file.

Screen-Shot-2019-03-12-at-5.29.02-PM

Most likely the default custom export settings will be ok, but you should pick a Compression option, to speed the download and import process. On the local side, fire up your local phpMyAdmin and import the downloaded file. If it's a big db and you're running MAMP, there's a good chance the db will exceed MAMP's mystifyingly small upload limits. In the free edition of MAMP you can easily update your php ini files, and in the paid version of MAMP you will need to use the 'template' interface. Also worth noting it's simple to import a MySQL db through the command line.

Modify the local WP config to remove WPE system settings

Here's the tricky part: removing any remaining WPE artifacts that might interfere with viewing the local site. WPE adds a lot of their own variables inside wp-config.php that you can easily live without. It's critical that you delete two settings in particular: WP_SITEURL and WP_HOME. These variables will cause your browser to redirect to the live URL, not your local site. Change your 'Database Configuration' within wp-config, too. DB_NAME, DB_USER, DB_PASSWORD are hopefully self-explanitory, but the WPE config for DB_HOST and DB_HOST_SLAVE may be subtly different from your local setup. There are also seven WPE plugins that are no longer necessary on a local site:

wp-content/mu-plugins/mu-plugin.php
wp-content/mu-plugins/wpengine-common/
wp-content/mu-plugins/slt-force-strong-passwords.php
wp-content/mu-plugins/force-strong-passwords/
wp-content/mu-plugins/stop-long-comments.php
wp-content/advanced-cache.php
wp-content/object-cache.php

Finally, you will want to edit the db file directly in phpMyAdmin to update the two db values that tell WordPress how to build URLs to your site. siteurl and home both live under wp_options in the database. Once you've modified wp-config.php it should be possible to access your site locally and log into the WP admin area. From here, I like to use the simple and effective Search Regex plugin to update links inside posts use the wp cli's built-in find and replace. So much easier than a WP admin plugin! Remember that your live install was https and the local install might not be, so you will need to include the full url in your queries.

Once you have your local setup running, you might want to add a Git integration to your WPE install, or create a CI pipeline to deploy to WPE for you.

Photo: Ingo Shulz

James White

James White

Two-time recipient of official citations from the NYPD for creative bicycle-riding.