Using Vagrant to Set up a WordPress Test Environment

Setting up a local environment for WordPress is a common need for developers. Since everything runs on your computer, loading times are significantly lower and you can safely test things before you try them out in a live production environment.

Local WordPress installations aren’t just for coders, though. As a user, local environments let you try out themes and plugins much more quickly, create as many installations as you need, and play around with WordPress without fear of wreaking havoc on your live website.

Many people use XAMPP or MAMP instead of the somewhat newer Vagrant. These are great choices but Vagrant is a lot more flexible and just as easy.

In this guide I’ll give you easy to follow, instructions on how to set up Vagrant you can copy and paste. We’ll go from zero to a fully functioning WordPress installation, so let’s dig in!

The 2 Minute Method

Getting Vagrant running on your computer is super easy. First, download VirtualBox and install it, then grab Vagrant. Create a directory to store your website files in, and using Terminal or Command Prompt, paste the following (thanks to Jeffrey Way):

Umm… I don’t know how to say this, but you’re done!

If you go to http://192.168.33.21 in your browser you should see the Apache success message. You can now download WordPress into the html directory within the directory you created for your websites and get started.

It really is that simple! There is a lot more we can do, but I thought I’d show you what all the theory boils down to first.

How Vagrant Works

Vagrant uses a virtual machine to create a server environment for you. This essentially means that a whole operating system is installed and run for you. This is why the first time you run vagrant up it may take 15-20 minutes to complete. On subsequent runs it only takes a couple of seconds since the operating system is installed, it just needs to be booted up.

To get things done, Vagrant needs a Vagrantfile and an optional install.sh file. The Vagrantfile contains information Vagrant needs in order to install the box: The IP address you want to use to reach the web server, which specific box you want to use, the location of that box, and so on.

The optional install file contains information about what you would like to install once the box has been created. This could be things like a MySQL server, perhaps some Apache modifications like error reporting, and so on.

Think of it like this: The Vagrantfile is like the installer for OSX or Windows. It allows you to add some parameters, which the install process uses. The install.sh file automates tasks you would do once you’ve installed your operating system, like installing Dropbox, Evernote, Photoshop, etc.

Why Use Vagrant?

You might be thinking that this is all well and good, but MAMP is already up and running on my computer, why should I use Vagrant? I personally favor Vagrant because of its flexibility and portability.

Vagrant is flexible because you can control every aspect of it. While MAMP, XAMPP and similar products are superb, they only offer limited functionality and customization. In addition, your MAMP/XAMPP environment will never really be similar to your production environment. Since Vagrant uses virtual machines you can download boxes which mimic popular web hosts completely, thus resulting in a near identical local and production environment.

Portability is important when working in teams, or if you work from multiple locations. The Vagrantfile and install file are all you need for a complete server configuration. These files usually clock in under 1KB each and they can be checked in to your version control system as well. Now your whole team can use the same testing environment, regardless of the operating system you are running.

Configuring Vagrant

The command I showed you at the beginning of this article does the following:

• Downloads a pre-made Vagrant file
• Downloads a pre-made install file
• Boots up your virtual machine

Let’s do all these steps manually so we can modify them and learn what’s going on. Create an empty directory anywhere on your computer and using Terminal or Command Prompt, navigate to the folder. Create an empty file named Vagrantfile and open it in your favorite editor, pasting in the following code:

As you can see we’re passing some information to Vagrant about how we want our virtual machine to be set up. The box we’re using is called “precise64” and can be downloaded from the URL pasted below. You can find tons of specific boxes at Vagrantbox.es, but this one is just fine for general use.

Next comes the IP address you want to use to access your web server. I’ll show you how to use something like “website.local” instead of an IP a bit later. The following line references the install file, followed by the definition of the synced folder. This is the folder within the virtual machine, which will be synced to your normal file system.

The install.sh file can get a bit more complex depending on what you need to install. I use the following code, explanation ensues:

First we update apt-get, a package manager – this is just some housekeeping. We then set the MySQL server username and password to root. We then install a bunch of things like cURL, PHP5, Apache, Git and others. The rewrite module of apache is then enabled and error reporting is set. The server is then restarted and composer is installed.

Both my Vagrantfile and my install file are a slightly modified version of Jeffrey Way’s. If you don’t understand everything in the install file don’t worry too much, just reap the rewards.

The final step is to type vagrant up into the terminal or command prompt and wait for Vagrant to do its thing. This will take a while on the first run, so grab a cup of coffee.

Configuring Websites

At this stage you could go into the HTML directory and create a website, install WordPress and so on. However, we don’t really want to run one virtual machine for every website we’re working on. Also, how about referring to our site with something other than 192.168.99.99? By configuring a few things we can get all this done easily.

Type vagrant ssh into Terminal or Command Prompt to access the virtual machine. Type cd /etc/apache2/sites-available to access the directory which stores the current sites. We can use this directory to add virtual hosts. Here’s how: Let’s create a configuration file, which will contain some options for our virtual host. Use touch blog.conf to create a new configuration file. Then, type sudo vi blog.conf to edit the file using vi. To enter “Edit Mode” press I and paste the following code into the file:

Press ESC and type :wq and hit “Enter.” This command saves the file and exists. The ServerName in the code defines how we want to refer to this location. Instead of typing 192.168.99.99/blog we’ll use blog.local – much nicer!

The DocumentRoot directive sets the root directory for this website. We’ll have to create this directory so head on over to the synced directory by typing cd /var/www/blog. Use mkdir blog to get the job done. Note that since this directory is synced with your file system you could go to the directory you created on your computer and create the blog directory from there as well.

You now have a configuration file, but the site needs to be activated – type sudo a2ensite blog. Finally, restart the server to load the changes: sudo service apache2 restart. Your site is now active, but there’s one last thing you need to do: edit your hosts file to make sure your computer looks for blog.local in the correct place.

For OSX and Linux users, the hosts file is at /etc/hosts. Use your Terminal to edit it: sudo vi /etc/hosts. On Windows computers, the hosts file can be found at C:\Windows\System32\Drivers\etc\hosts. Use a text editor to edit it. In both cases you’ll need to add a single line:

The IP needs to be the one you defined in the Vagrantfile, the website name needs to be the server name you defined in the configuration file. Once you save this file (use :wq in the terminal), you should be able to access your new website using http://blog.local.

Rinse and repeat this process to create as many virtual hosts as you need to work on multiple websites using the same virtual machine.

The 5 Minute WordPress Install

You can install WordPress a couple of ways. Let’s take a look at two of them.

The more familiar method is to go to WordPress.org, download WordPress and extract all the files into the new blogs directory. Since WordPress extracts into its own wordpress directory, you’ll most likely need to go into that folder and move all the files and folders one level up, directly into the blog directory.

Once you’ve done this you can go to http://blog.local and complete the install using the regular ol’ Famous 5 Minute Install method. Once additional thing you’ll need to do before you complete the process is create a database. You can do this from the Terminal. Make sure you are SSH-d into your server. Once there, type mysql -uroot -p to access the MySQL server, using root as the password when prompted. Once in, type CREATE DATABASE blog;, press “Enter” and type exit to exit the MySQL console. You now have everything you need to install WordPress.

Install WordPress With WP-CLI

In my previous article Setting Up WordPress Like A Pro, I covered a command line tool called WP-CLI, which can help with a variety of WordPress tasks, such as installation. So let’s install WP-CLI on our new local server and use it to grab WordPress. You can find installation instructions online, but here’s a quick recap.

Make sure you are SSH-d into your server and use cURL to download the WP-CLI file:

Now, change the permissions on it to make sure you can use it, then place it into your path so you can run it globally. Use the following two commands to get this done:

You should be able to type wp --info anywhere in the terminal and get some information about WP-CLI. Let’s download all the WordPress files much faster than we did before.

Head into the folder for your website: cd /var/www/blog and simply use wp core download. This will automatically grab all WordPress files and extract them properly, no need to move them afterward. You can now proceed to install your website using the GUI tool by going to http://blog.local or you can continue with WP-CLI. Here are the set of commands you could use:

All done, you should see WordPress installed and ready to go. WP-CLI has a great many useful commands, which can do anything from move a site to install themes and plugins en-masse. It’s one of my favorite WordPress tools.

WordPress Upload Issues

If you use the same configuration as me you may find that you have a hard time uploading images from within WordPress. It took me a while to figure this one out but it can be resolved easily by making sure Apache is run by the Vagrant user/group. Let’s edit the relevant file using sudo vi /etc/apache2/apache2.conf:

We’re searching for the user and group directives. You can start scrolling down until you get there, the values should be ${APACHE_RUN_USER} and ${APACHE_RUN_GROUP}, respectively. You can also search by typing :/User. Replace these two lines with the following;

Save the file using :wq and restart the server using sudo service apache2 restart. With that implemented you should be able to upload images properly.

Conclusion

There are a lot of things you can configure using Vagrant but the basic process is fairly straightforward. If you need a quick and dirty server you can get by with a simple command and then install WordPress right away.

Using some virtual hosts and WP-CLI you can create a powerhouse of development or testing very easily in a couple of minutes. Once I started using Vagrant with WordPress I never really looked back and I use this method exclusively. I hope you’ll like it, too!

Do you use a local development environment with WordPress? What do you use? Vagrant? MAMP? XAMPP? Let us know in the comments below.

Tags:

• developers