Setting up WordPress for local development

Leave a reply

I recently transitioned my local LAMP development stack from Wampserver to Windows Subsystem for Linux (WSL). You can read about why and how I did it in this post.

One of my primary use cases for having a reliable local LAMP development stack is WordPress theme and plug-in development. In this post, I am going to go over the process I use to install WordPress locally, set up the installation, implement version control, and deploy to a hosted server/production environment.

Who is this for?

There’s a lot of information out there about setting up WordPress for local development. From my research, a lot of these guides are directed towards teams or agency models where there may be multiple developers working on a site. This guide is NOT for you.

This [opinionated] guide is geared towards single developer or personal WordPress websites. I use this process when I know that I will be the only one who is doing development on the website and deploying files from the local development area to the hosting environment or production server. And by doing development, I am referring to creating customized theme files or private plug-ins. In other words, this process works even when another person is creating content for or installing 3rd party plug-ins on the website, provided those plug-ins come from the official WordPress plug-in repository. So long as you are the only developer working on the underlying code, everything should be fine.

The goals

I use this process for the following reasons:

  • To add and test functionality without disturbing the production website
  • To deploy without using ftp to transfer files to the web server
  • To implement version control for themes and custom plug-ins

One item that bears mentioning here is that the purpose of using Git is for version control and deployment convenience. I am NOT using Git to back up the website. There are other tools and plug-ins that should be used if you’re looking to back up your website.

A personal preference

I chose to create this guide using as few, if any, third party dependencies as possible. I am aware that there are some helpful tools for installing and managing WordPress installations, such as WP-CLI, and using Git, such as git tools with a slick looking GUI, but I wanted to stick to the basics. The tools change, come, and go, and I didn’t want to have to change my process based on updates to third party tools if I could help it.

Version control notes

As I mentioned above, I am not using version control to create a site backup. Therefore, I do not need to commit the core files, 3rd party plugin-ins, or the site content. Since I am the only one working on the website, it won’t be necessary for another developer to mirror the WordPress core and plug-in versions. I’m of the opinion that the core files and plug-ins should always be kept at their latest versions, so I will manage these items using the version control systems built into WordPress rather than recreating them.

After doing my research, I prefer the idea of each theme and plug-in having its own repository. In my opinion, it makes the themes and plug-ins more portable. I can mix and match themes and plug-ins on different websites without having to maintain versions of each integrated theme and set of plug-ins. In addition, each theme and plug-in gets its own version number, which makes for better version control and change tracking.

Background sites

Before getting into the guide, I’d like to give a shout-out to these posts which provided background and helped me come up with this process:

Prerequisites and required knowledge

Using this guide effectively requires the following:

  • Web hosting account, VPS, or some other Linux-based web server to host the website
  • Terminal access to the web server, preferably through SSH
  • A Github account
  • Basic knowledge of the following:
    • Linux CLI commands
    • Creating and managing Git repositories
    • Github usage
    • WordPress installation, setup and usage

The guide

Step 1 – Install WordPress locally and on the web server

For installing WordPress locally, I recommend following the instructions provided by WordPress. Just start WSL on your PC, open a Linux shell, and follow the instructions.

Depending on your hosting environment or remote server environment, the WordPress installation may be handled differently. I recommend following whatever process your hosting provider recommends.

Keep in mind that you do not need to match up the WordPress database username, password, or database name. Since we are not committing the core files to version control, the WordPress installs on the server and local environment can have their own configuration.

Step 2 – Create Github repositories

Once the WordPress installations are up and running, it’s time to setup a Github repository for each custom theme and custom plug-in that you are developing for the website. To create a Github repository, you can use one of the following guides:

In my case, I already had an existing theme that I was using for my website. It’s a child theme based on the WordPress Twenty Twelve theme. I simply went into the directory for the theme, and followed the instructions above to create the repository.

If you’re creating a new theme or plug-in, use the step for new themes and plug-ins to create the repository, do your development, and commit your code to version control.

Step 3 – Clone the repository to the web/production server

Once the repository is setup, go to the WordPress themes or plug-ins directory and clone the git repository that has the corresponding theme or plug-in. The instructions are listed here on Github – Cloning a repository.

For example, in my case I was bringing across a theme. I went into the wp-content/themes directory, created the directory name for the theme and ran the git clone command to copy the theme files from the repository into the directory I created.

$ git clone <repository_name> <theme_directory>

Once I have the theme pulled across, I activate it in the new install, and the site is up and running. In my case, there are some settings within WordPress that I have to match up with the development site, but this is a one time setup. Once I cloned the settings from the existing site, I had the production site and development site running the same theme files. And if I want to remember the settings that need to be configured, I can add these to the repository ReadMe file.

The only thing different is the content. We’ll go over some strategies for pulling content across in a minute, but I don’t want to copy over all the content. That’s not the point of the local environment. I said it before, and I’ll say it again, the local environment is not a site back-up. It just needs enough content that I can do development work. I can either do this by importing some content from the existing site, or creating some faux content to play around with.

Step 4 – Import some content (optional)

In the case where the site already exists, or if you start adding content (pages or posts) to a new site, you may want to move some of the content to the local development environment. I simply use the Import/Export features within WordPress under the ‘Tools’ menu. It allows you to select the pages or posts that you would like to export, and then you import those into the new site.

It’s possible that there could be some links embedded in the content from the production site that are broken, particularly if it is pointing to content in the uploads directory. To address this issue, I like the mod_rewrite rule that Steve Grunwell shared in the article I mentioned above. You can read his post for more context, but here’s the code snippet that you can put into the .htaccess file in the local development directory:

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteCond %{REQUEST_FILENAME} !-d
  # Replace http://stevegrunwell.com with your # production site's domain name. 
  RewriteRule (.*) http://stevegrunwell.com/wp-content/uploads/$1
</IfModule>

Step 5 – Make some changes

Now we’re ready to make some changes. You can make changes to the theme or plugin functionality in the local development environment, test it, and when you’re satisfied with the changes, commit them and push to the main repository. Then go to the production site, perform a git fetch to sync with the origin, and a git pull to merge in the changes. The production site will now have the latest changes without having to copy the files manually. In addition, there is a log of changes made in the Github repository, and you can easily revert to a previous version if something goes haywire on the production site.

Adding version control to my WordPress custom theme and plug-in files was long overdue, and it’s a pretty painless process for a single developer website. For multi-developer environments, I’d recommend using something similar to the articles referenced above, particularly those that recommend using composer to control the WordPress core files and 3rd party plugins outside of the normal WordPress environment.

Leave a Reply

Your email address will not be published. Required fields are marked *