Local WordPress development update

Update: See my more recent post about LocalWP

There’s myriad options for local WordPress development environments. Some are quite simple to set-up, usually connected to a paid hosting service that funds the local dev project. Some automatically install WordPress while others require manual installation into the web root htdocs plus database initialization.

For Linux users like myself the options are primarily: direct installation/configuration of the web services, Docker-based containers, Vagrant-based virtual servers, or the XAMPP prepackaged services bundle.

In this article I’ll cover multi-environment and SSL configurations since those are especially challenging yet useful for developers running WooCommerce store sandboxes. The example commands are based on XAMPP and Apache web server on Linux but can be translated over to any configurable solution and among operating systems as well.

I’ll refer to PhpMyAdmin a few times here as the primary database interface. Most development environments come with this prebuilt, or you can manually install and configure it or use the command-line as desired.

Creating multiple sandbox environments

Enable virtual hosts and SSL inside the httpd.conf file by removing comments for the inclusion of files httpd-ssl.conf and httpd-vhosts.conf. Refer to the development environment documentation for the locations of these configuration files.

Define your website containers within the httpd-vhosts.conf file, for example:

<VirtualHost *:443>
DocumentRoot "/opt/lampp/htdocs/sites/sandbox1"
ServerName sandbox1.local.dev
SSLEngine on
SSLCertificateFile "/opt/lampp/etc/ssl.crt/.local.dev.crt"
SSLCertificateKeyFile "/opt/lampp/etc/ssl.key/.local.dev.key"
</VirtualHost>

If you haven’t already, install WordPress core into the location specified in DocumentRoot above and create a new database for this environment using PhpMyAdmin. You’ll connect the environment to it when you visit the URL later.

If you haven’t already, set-up your database root password:

sudo /opt/lampp/bin/mysqladmin password PASSWORD

If you haven’t already, set-up file permissions so your web server can modify the website files such as with Media Library, plugin installations and updates:

sudo chown -R daemon.daemon /opt/lampp/htdocs;
sudo chmod -R 775 /opt/lampp/htdocs;

Setting-up a trusted self-signed wildcard SSL certificate

Create a local Certificate Authority chain with a new self-signed certificate. Download and install the open-source tool mkcert by FiloSottile. After downloading the release binary file run the following to install it:

chmod +x mkcert;
sudo mv mkcert /usr/local/bin/;
sudo mkcert -install;

For multi-environment support create a wildcard certificate following the format *.local.dev noting that wildcards only work using this specific X.Y.Z format where X is the wildcard (*).

sudo mkcert *.local.dev

Copy the certificate and key files into your web server’s folder and change the virtual host entries (see example above) to connect to the certificate and key files you’ve just created to the web server.

Restart your web browsers so they load the new certificate chain.

Restart your web server after completing changes to its configuration files:

sudo /opt/lampp/lampp restartapache

Ensure your database server is running:

sudo /opt/lampp/lampp startmysql

Now you should be ready to visit your website at https://sandbox1.local.dev and follow the set-up wizard to connect it to your database.

Migrating an environment

Once you have a sample WordPress environment up and running properly with SSL the next step is to load your websites in. It’s easiest to use a migration plugin such as All-In-One WP Migration Pro. There’s lots of useful tools out there, mostly commercial and not free. I’ll just recommend that one for the automated approach.

Non-automated; let’s say you prefer to manually restore backup files say from the free Updrafts Plus plugin, or you already have a copy of the site locally. You need to update the URLs (migrate) for your new environment. The WordPress database contains countless instances of the absolute URL and there’s tons of serialized fields where you cannot blindly string replace.

The open-source tool I recommend for manual migrations is Search-Replace-DB by interconnect/it. This tool has a web interface but I strongly prefer using its command-line interface.

Downloaded copy of this tool and change directory to it. Don’t be afraid of errors and warnings here since you can manually fix-up the few records that fail.

php srdb.cli.php -h localhost -n DBNAME -u root -p PASSWORD -P 3306 -s "https://WEBSITE.COM" -r "https://sandbox1.local.dev" -w wp_options

We’ve begun with all tables except wp_options and will run it on wp_options separately. This is because wp_options may contain problematic data resulting in errors which you can isolate this way.

php srdb.cli.php -h localhost -n DBNAME -u root -p PASSWORD -P 3306 -s "https://WEBSITE.COM" -r "https://sandbox1.local.dev" -t wp_options

When done be sure to run a database wide search for your previous URL and manually update any records that were missed for one reason or another. Within PhpMyAdmin select your database, click Search, enter your old URL and select “the exact phrase as substring” to search all tables. Edit any rows accordingly being careful of serialized data fields that need you to re-count the characters and update the counter immediately preceding the string.

All done!