Content management systems such as WordPress normally need to be run on a web server to function. They use scripting languages or services that can’t just be handled locally in your browser like a HTML file. But when you don’t have access to a server during development, or don’t want to be altering a site that’s live, you can set up a local environment to replicate everything you need. It’ll only be accessible from your computer, and you can perfect your code without having to worry about hosting costs or whether someone can see your work-in-progress.

 

 

Simple vs. Flexible

There are a few solutions available that bundle a WordPress installation into a piece of software that you can install on your machine. They’re relatively quick to get started with, but often restrict you to a single copy of the CMS that’s emulated by the software. The files you’re editing are usually stored somewhere in the installation directory, which can be a little awkward if you like to use an organised folder structure for your projects over multiple hard drives.

The alternative is to use a piece of software that just runs the languages and services you need, and create your own folder structure that you’re more comfortable with. I tend to use XAMPP – a popular tool that lets me create a web server environment that I have full control over.

Taking a more hands-on approach can be a little daunting at first, but will ultimately give you more flexibility with your development. This guide runs through the steps for creating a local WordPress installation with the following benefits:

  • Develop more than one site on the same local machine
  • Use your own locations and folder structures for your site files
  • Custom development URLs you can use locally (e.g.: dev.yoursite.com)
  • Navigate to the site in your browser, as you would a live site
  • FTP or Sync your local WordPress files more easily with a web server

This guide is Windows only for now, I’m afraid. XAMPP is available for Linux and Mac, and I’m hoping to come back and update this guide in the future.

 

Choosing your local domain

You can pick the URLs you’ll be using to access your local development sites. Setting up some local URLs to use (for example: dev.petegale.com) makes life easier when you want to access your site, and lets you work with multiple development sites on the same local machine more easily.

To do this, you need to edit your hosts file in Windows. You’ll find it in the following folder (assuming C: is the drive you’ve installed Windows to):

C:\Windows\System32\drivers\etc\

Open the “hosts” file in notepad, or any other text editor. There should already be an example in the hosts file showing you what to do. The IP 127.0.0.1 is your “localhost” – the address a computer uses to refer to itself. You’ll want to add something like this:

127.0.0.1 dev.yoursite.com

You’re basically telling your machine that when you type dev.yoursite.com into your browser, you want to look at files on your computer instead of a server somewhere on the Internet. You can create multiple entries with different domains, pointing each one at 127.0.0.1. We’ll be defining exactly which files each domain points at, but for now just add the domains you need.

Having problems?

  • To see the hosts file, you may need to disable the “Hide protected operating system files” option in Control Panel > Folder Options
  • Some security software will change your hosts file to Read Only. You’ll need to disable this to save your changes, but change it back to Read Only once you’re done if that’s what your security software is expecting.
  • Security software may also add URLs to your hosts file as localhost entries, to essentially “block” these links. If you have software doing that, it’s probably best to put your development URLs above this list to avoid them being lost if new entries are added.

 

The WordPress folder

Download the latest version of WordPress, and unzip the contents to your preferred location. This can be wherever you like, but choose carefully, as you’ll need to point to this location during the next few steps and it’ll be more complicated to change it later. The WordPress folder is going to behave just like it would in the root directory of your web server, so eventually you can just copy these files and their directories when you move to a live web host.

There is only one exception: the wp-config.php file. This will contain the details of your database, and the user account for accessing it. When you come to make the site live, you might find that the live details for the database or user name end up different from the local ones you create in the next few steps. It’s a good idea to keep a separate copy of wp-config.php for your live and development sites.

If you’re planning on creating multiple development sites for working locally, choose distinct locations for each – don’t nest one site inside the folder structure of another, as this will cause problems later.

 

XAMPP

Now you need your local machine to behave like a web server. Download and install XAMPP – a free tool that runs languages and services normally associated with a web server. Once installed, you can start defining the local site locations for the domains in your hosts file.

What does it do?

A website made up of individual HTML files can be opened locally without a tool like XAMPP, as it’s the browser that does all the work to interpret your HTML, CSS or JavaScript as a fully functional web page. Content management systems like WordPress use PHP template files to generate content dynamically, without needing an individual file for each page of your site. It’s this dynamic generation of the content – and accessing the MySQL database where the content is stored – that a web server normally handles.

Load the XAMPP software. You’ll see a list of services, each with a set of buttons. Click the Config button for Apache, and select the httpd-xampp.conf file. This where you can configure the locations XAMPP will recognise.

 

Click the Config button for Apache, and select "Apache (httpd-xampp.conf)"

Click the Config button for Apache, and select “Apache (httpd-xampp.conf)”

 

Look for the <IfModule alias_module> opening tag. This section lists the locations in your local environment along with their permissions. You’ll need to list your local site locations here, so copy the following code below the last <Directory> entry (replacing the example file path with the correct path to your WordPress folder):

<Directory "C:\Projects\WordPress">
AllowOverride All
Order allow,deny
Allow from all
Require all granted
</Directory>

For each local site you want to create, include another entry like the one above, using the correct path.

These permissions assume that you’re just going to be working locally with your own files, without needing to worry about external security concerns. If this isn’t the case, you may need to research Apache in more detail, to better understand how it’s configured.

We need to add an entry to one more file, but it’s not accessed through the Config button in XAMPP. Navigate to the following file (depending on where you have XAMPP installed) and open it in Notepad or another text editor:

…/xampp/apache/conf/extra/httpd-vhosts.conf

This is your virtual hosts file, where you can match up your file locations with the URLs you created in your localhosts file.

Your file will probably only contain comments for now (indicated with a #), so you’re going to paste your code underneath those comments at the end. Start by adding this line:

NameVirtualHost *

Because you’re creating virtual hosts that can operate independently, you need to make sure that XAMPP configuration is still accessible by giving it an entry here. Copy the following underneath the NameVirtualHost line, updating the DocumentRoot path to wherever your copy of XAMPP is installed:

<VirtualHost *>
DocumentRoot "C:\...\xampp\htdocs"
ServerName localhost
</VirtualHost>

This ensures that your XAMPP settings (which you’ll need in the next step) are still accessible by going to localhost or localhost/xampp in your web browser.

Next, include this snippet of code for each of your local sites. Change both the DocumentRoot and the Directory to match the location of your files.

<VirtualHost *>
DocumentRoot "C:\..\..\Wordpress"
ServerName dev.petegale.com
<Directory "C:\..\..\Wordpress">
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

That’s it for editing files. Your folders will function as local site structures now, but to use a CMS like WordPress you need one more thing to get up and running – a database. XAMPP will allow you to create and run one on your machine.

 

Creating a MySQL database

Now that XAMPP is installed, you can create your database. Go to the XAMPP configuration page by typing “localhost” or “localhost/xampp” into your browser, and click on phpMyAdmin in the right sidebar.

 

Click on "phpMyAdmin" in the sidebar.

Click on “phpMyAdmin” in the sidebar.

 

At the top of the page, click the Databases tab to see a list of all the databases for your XAMPP installation. There will be some listed here, but those are just default databases installed with XAMPP. Don’t do anything with those.

 

Click the Databases tab at the top of the phpMyAdmin page.

Click the Databases tab at the top of the phpMyAdmin page.

 

Near the top of the Databases page is a form to create a new database. Enter a name for the database here, leave the dropdown field on “Collation”, and click Create.

 

Enter a database name and click "Create"

Enter a database name and click “Create”

 

Normally, on a live server, you’d want to create a user with a password and assign it to the database. As you’re only working locally, that’s not necessary. Now your database has been created, you can go back to the wp-config.php file and finalise your WordPress installation. Find the following section and update it with your database name:

// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define('DB_NAME', 'database_name_goes_here');

Because we’re not creating a user account, you can change the username and password values to use the root account:

/** MySQL database username */
define('DB_USER', 'root');

/** MySQL database password */
define('DB_PASSWORD', '');

When you come to make your WordPress site live, and you create a database with your web host, you’ll want to create a user with a secure password and include these details here. This is one reason why you’ll need a separate wp-config.php file for your local development environment.

There’s nothing to stop you creating a user if you like, however, and if you’re confident that your database name and username will be the same when you move to a live web host, you can avoid having two distinct wp-config.php files by using the same details here.

 

Using your local sites

To visit any of your sites once you’re ready, including the XAMPP configuration page, you will need to start the Apache and MySQL services on your XAMPP control panel. Click the Start button next to the Apache and MySQL services, and wait for the name to turn green in your XAMPP window.

 

Click the Start button next to the Apache and MySQL services in XAMPP

Click the Start button next to the Apache and MySQL services in XAMPP

 

These are the only two services we need for WordPress. Once both are active, you should be able to visit your local sites by visiting their URLs in your browser.

And that’s it!

Changes you make to files in your WordPress installation directory should be effective immediately after a refresh. Your preferred code editor can point to the folder structures you set up, and you’ll be able to edit your files directly.

 

Troubleshooting

Though a little tricky to get going, it should be quite straightforward to

  • Check XAMPP services are running correctly. If the names for Apache or MySQL aren’t highlighted green, something’s not right – consult the dialogue box to diagnose the problem.
  • If you’re syncing your local files with a live location, be careful not to accidentally override your wp-config.php file with the wrong database details.
  • Similarly, a live .htaccess file might contain entries not suitable for a local installation (such as IP / access restriction, etc). It may be an idea to keep two copies of this file as well – one for your local site, and one for your live site.
  • If WordPress gives you a page telling you it’s having trouble accessing the database, root access may not be possible for some reason. Try creating a user account in phpMyAdmin with a password, and give it full privileges for the database you created. Update the wp-config.php file with the username and password. If this doesn’t work, double check the database name is correct, and try creating the database again.

 

This is by no means an exhaustive guide – if it was, it’d be even longer than it is already! I’ve tried to cover the basic steps, but if you run into any other problems or have any feedback about this guide, please get in touch or comment below!