Using Vagrant for WordPress

In the beginning, we had M/W/X/AMP(/P/S)

One common way to spin up a server for local WordPress development involves using an Acronym Soup server locally, AMPPS, MAMP, Bitnami MAMP Stack, WAMP, XAMPP, or a built-in development server (like the Apache that ships on Mac OS).

The upside to this is that you can quickly spin up a local server and start banging out some code for your project.

The downside to this is that your local development environment may not match your staging and/or production environment(s). You may have to maintain multiple versions of tools locally on your desktop or laptop that are unwieldy or cumbersome from one project to the next. You may need to share a configuration with your team mates that can’t be replicated without giving them a list of tools they need to install and the instructions to do so. You may be using Apache locally, and have Nginx on production. You may be using PHP 5.4 locally, and have PHP 5.3 on production. PHP libraries may be missing from your local dev server, or vice versa. Your installed version control system may have a different binary version locally than it does on production.

Then we had the VM

This is where a virtual machine (VM) can be very useful.

Traditionally, spinning up a VM involved downloading pre-configured boxes for Virtualbox or VMWare that were sort of like the target production environment. They might be overloaded with lots of preconfigured software that may not be necessary, or have a complete GUI attached to them, making the VM large and unwieldy. They might be missing some packages that you need that are specific to your production environment. Depending on how the box was created, you may end up with bloated boxes that are a pain to manage, and sharing the 10 GB VM amongst a team that includes remote workers may be unfeasible. Do you check the VM into version control for the project? How large do you want your version control repository to be on initial checkout for that newb on the project?

Then came Vagrant

This is where Vagrant comes in.

From Vagrant’s About page :

Vagrant is a tool for building complete development environments. With an easy-to-use workflow and focus on automation, Vagrant lowers development environment setup time, increases development/production parity, and makes the “works on my machine” excuse a relic of the past.

Using Vagrant, you can define and spin up a headless server environment that can be used for local development. Some cloud providers, such as Amazon Web Service and Rackspace, even support Vagrant boxes as production servers.

You could start with a base box definition that closely resembles your destination production environment by finding one at the Hashicorp Vagrant community box repository, or from the repository.

Technically you could configure a Vagrant box, spin it up, and begin installing all the necessary packages for your server at the command line with apt-get, yum, or whatever package manager the OS of the Vagrant box provides.

Managing installed packages

Fortunately, there are tools to automate and assist with package management as well.


Puppet is a tool designed to manage the configuration of Unix-like and Microsoft Windows systems declaratively. You can use Puppet to manage packages for you.

You can use Puppet to install Apache, or Nginx, MySQL, PHP and other packages that your Vagrant box needs to match production. With Puppet and Vagrant together, you can create virtual machines that reliably match your production environment to a tee.


PuPHPet is and online “wizard” that allows you to create a Puppet and Vagrant configuration without a deep knowledge of either tool’s specific configuration formats and directives. You could go to the PuPHPet website, spec out the OS, hostname, memory allocation, installed packages, etc., and download a zip archive that contains the configurations. Unzip the archive on your local machine, cd into it, run vagrant up, and your server is ready, without learning all the details of configuring Vagrant or Puppet directly.

Using a tool like PuPHPet, it is a breeze to define the Vagrant box, the OS and installed packages, the whole nine yards, and check the entire configuration into version control. While still being lightweight, your team can check out the configuration, run vagrant up, and start developing in a production environment quickly.

WordPress Vagrants

There are a number of WordPress specific Vagrant Projects that you could use to jumpstart your WordPress development, depending on your needs.

WordPress specific Vagrant boxes aren’t typically aimed at helping you match a specific server environment. They are usually intended to quickly spin up a type of WordPress project setup, i.e. for WP Core contributions, WP Theme Reviews, WP theme development, WP plugin development, or even client site development. They often come pre-loaded and configured with WordPress development tools, and some of them follow best practices for large scale WordPress production environments. They can be quite useful, for example, if you need to share a server configuration amongst a team, or if you need to do VIP development.

VIP Quickstart

VIP Quickstart is a local development environment created by Automattic for VIP developers. The goal is to provide developers with an environment that closely mirrors along with all the tools they recommend developers use.

Varying Vagrant Vagrants

The “big guy” in WP specific Vagrant boxes, this is the one you will hear of most often when researching Vagrant with WP.
Although it started as a 10up project, it has transitioned to a community project.


Chassis is a virtual server for your WordPress site, built using Vagrant.
From the project README: You can imagine it as MAMP/WAMP on steroids.

Primary Vagrant

Developed as a VVV alternative that uses Apache instead of Nginx.

Useful WordPress Vagrant Tools

VVV Site Wizard

An Alison Barrett project (Nerdery Alum, former Automattician, current 10up).
A Bash script to automate setting up new WordPress sites with Varying Vagrant Vagrants.

Variable VVV

A fork of VVV Site Wizard that adds a number of useful features, including deployment options.
Although I have not had a chance to test it, it looks like a very interesting project tool worth exploring.

WordPress Theme Review VVV

A VVV setup script intended as a WPTRT theme review environment.

Vagrant Manager

A handy tool (available for OS X and Windows) to manage your Vagrant boxes right from the desktop.
See which Vagrants are running or halted, and issue commands to them from an easy to use menu.

Hey, where’s the tutorial, code, or in-depth walk-through?

This post isn’t a tutorial. This post is a brief intro to what Vagrant is, and why you should consider using it for WordPress development.

I hope to inspire WordPress developers who may have “heard” of Vagrant, but aren’t sure how it can be useful for them, or don’t know where to start, to dig in a little deeper. Look into some of the GitHub repos I’ve linked to, and see if one of them might work for your next project. Try using PuPHPet to build your own ideal Vagrant setup for your next WordPress project.

My advice, if you haven’t used Vagrant before, and you just want to get started with using Vagrant, clone Alison Barrett’s VVV Site Wizard and follow the directions. You’ll have a WP specific Vagrant box up and running in no time.

If you want a little more fine grain control over your Vagrant box setup, go to the PuPHPet website and spec out your ideal box. Then the rest… setting up a DB, installing WP, etc., is in your complete control.

Hey, what about Chef / Berkshelf, or Ansible, or SaltStack, or (insert yet another tool name here)?

Yup. Those are other tools that you can use, rather than Puppet. I’ve heard great things about them, however, I have not had the time to dig into all of them myself.

If you have the time to research them, and you find a compelling reason to use one over another, by all means, use it, write about it, then share your discoveries and experiences. The single greatest thing about the WordPress community, I have found through the years, is all the knowledge that the community shares.