export default "data:image/svg+xml;base64,PHN2ZyBhcmlhLWhpZGRlbj0idHJ1ZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgNjAgNzUiPjxkZWZzPjxzdHlsZT4uYXtmaWxsOiNmZmY7fTwvc3R5bGU+PC9kZWZzPjx0aXRsZT5UUlEtTEdPLVEtUkdCPC90aXRsZT48cGF0aCBjbGFzcz0iYSIgZD0iTTkuNzEsOS41NGEyOC44LDI4LjgsMCwwLDAsMCw0MC42NGwuMTMuMTJoMEwzMy43NCw3My44NlY1OC4yNWExOS43LDE5LjcsMCwwLDAsMi4zOS0uMzUsMjguMjksMjguMjksMCwwLDAsMTQuMTYtNy43MkEyOC43MiwyOC43MiwwLDAsMCw5LjcxLDkuNTRaTTQyLjQ0LDQyLjMyYTE3LjQ2LDE3LjQ2LDAsMCwxLTguNzcsNC43NVY1OFMxOC4wNSw0Mi44LDE3LjU2LDQyLjMxYTE3LjYsMTcuNiwwLDEsMSwyNC44OCwwWiIvPjwvc3ZnPg=="
Torque

Getting Started with Vagrant for Local Development

Filed Under

Featured

Published

August 13, 2014

8 Comments

Vagrant is a system for creating local web servers in portable, highly-configurable virtual machines on Linux, Windows, and Mac. Though there are lots of ways to create a local testing environment for WordPress development, Vagrant is one of the most powerful and configurable options.

In this article, I’ll introduce Vagrant, and I will walk you through setting up VVV, a popular WordPress vagrant setup.

The real advantage of Vagrant is that it’s totally customizable. This means you can emulate your production environment in your local development environment. When done right, this means no surprises when you go live.

Developing with the same technologies as you use on the live server can save you from running into bugs on your live site, which never happened locally since the situation that caused them doesn’t exist locally. For example, how can you know that your site has no problems with NGINX if your local web server is powered by apache? Or, how can you be sure your code is compatible with PHP 5.2 or 5.3, which many hosts still use, if you only tested it in the latest version of PHP?

What is Vagrant?

The heart of Vagrant is the vagrant file, which contains a recipe for creating and configuring the virtual machine. While this may sound tricky, and it probably is, don’t be scared. The internet is full of vagrant files and use-case specific vagrant systems you can download, which are ready to use with just a few commands. There are a ton of great vagrant setups that are designed especially for using WordPress.

Most importantly, for all of its power, Vagrant is pretty easy. There is no GUI for Vagrant yet. It must be operated from the command line. Don’t let that scare you. There are really only four commands you ever need to type: “vagrant up” to start vagrant, “vagrant halt” to stop it, and “vagrant provision” to add a new site, which is something I’ll discuss later.

Vagrant and the alternatives

Vagrant isn’t for everyone. I always say it’s the best, but not the easiest way to develop WordPress locally.

There are many GUI tools for creating WordPress sites using XAMMP or a similar technology—for example, DesktopServer by ServerPress, and AMPPS by Softaclous. DesktopServer allows you to easily create a local WordPress site. AMPPS, is very similar to the Softaclous module in cPanel, which allows you to create more than just local WordPress sites.

Services like DesktopServer and AMPPS are very easy to use and as an added bonus, DesktopServer even includes the ability to easily deploy your local site to a production server.

Beyond the customization offered by Vagrant, and the ability to create parity between local and development sites, is the portability. Sharing Vagrant sites is super simple. Since the configuration file and the rest of the site is all contained in one directory, you can send an archive of that directory to another developer. The only thing the recipient needs to do is extract it and run “vagrant provision,” and then they’ll be working in the exact same environment as you do.

WordPress vagrant solutions

Unsurprisingly, given WordPress’s popularity, there are plenty of great pre-built vagrant configurations for WordPress. I’m not going to compare them all in detail, for that you should see the comparison table of WordPress vagrant configurations that Micah Wood curates.

By far, the most popular WordPress vagrant system—and it really is a whole system—is VVV.

VVV, which stands for Varying Vagrant Vagrants, was started by Jeremy Felt at 10up, and is now a community project with many contributors from across the WordPress community. VVV comes preconfigured with four WordPress sites and makes it easy to add more. It also includes a long list of tools for modern WordPress development, from advanced object caching, to debug tools, to version control and dependency management.

The rest of this article will focus on using and installing VVV. Keep in mind that VVV might not be the right choice for you. One good alternative is Chassis. Chassis is sort of the anti-vvv. It’s designed to run one site per vagrant box. Chassis is configured to make it easy to mirror a production server in local development. This makes it perfect for when you’re writing code for a specific site and provides control over how it is configured.

Alternatively, if your concern is testing a theme or plugin in multiple “real world” examples, you should check out wp-vagrant by Bryan Petty. This setup allows you to run three separate virtual machines, each with a different version of PHP, but all sharing the same source files and database.

Installing VVV

Installing Vagrant itself is easy, just download it from VagrantUp.com and run the installer. Also make sure you have VirtualBox or some other compatible virtualization software installed. Personally, I use VirtualBox, though I’ve heard good things about using VMWare.

Before installing VVV, you’ll want to install two vagrant plugins. They are technically optional but make life so much easier. The first one, vagrant-triggers, allows VVV to backup your databases every time it shuts down, which is an incredibly useful feature. The second, vagrant hosts-updater, makes it easier to update hostnames.

To install these two plugins, simply open up your terminal and type:

vagrant plugin install vagrant-hostsupdater

And once that’s done type:

vagrant plugin install vagrant-triggers

Now you are ready to install VVV.

First, make sure you are in the root of your user by typing:

cd ~/

Now, if you already have Git installed, you can clone the VVV repository from GitHub by typing:

git clone https://github.com/Varying-Vagrant-Vagrants/VVV vagrant

You can also use VVV as a zip file, and unpack the zip file in a folder called “vagrant,” in the user root. Personally I prefer to use Git, so it’s easy to stay up to date with improvements to VVV.

Now in the terminal switch to the new vagrant directory by typing:

cd vagrant

From there, you need to do your first vagrant up. Vagrant up is the command that powers up Vagrant. The first thing it does is check if Vagrant is already provisioned. If it is, it loads the existing Vagrant box and you’re ready to work in about 10-20 seconds.

Since this is your first vagrant up, Vagrant will need to provision a new virtual machine. This can take a while, so unless you like watching commands go by in the terminal, now is a good time to go get a drink, or, if your internet connection is really slow, go get lunch.

Once its done, you should be able type http://local.wordpress.dev in your browser and see a brand new WordPress site.

Using VVV

By default, VVV gives you four sites. You can see the source code for each one in the www folder of the main Vagrant directory. That’s actually symlinked to the www directory of the virtual server. All you need to do is drop one of those directories into your IDE and you can start developing.

VVV provides four sites by default:

VVV adds a cool utility site at http://vvv.dev that has links to the default sites, as well as to phpmyadmin for database management, as well as utilities for monitoring the object cache and for accessing webgrid.

When you’re done with Vagrant, to shut it down, simply type in the terminal “vagrant halt” and it will shut down. You can also destroy your virtual machine with “vagrant destroy.”

For more information on using VVV, see the VVV wiki.

Adding custom sites to VVV

For some people the default sites may be enough. What makes VVV cool is that it’s very easy to add new sites to the existing vagrant configuration. There are lots of great add-ons out there, which you can use simply by cloning or downloading them into the www directory and then in terminal by typing “vagrant provision.”

There are many pre-built VVV site configurations you can use. For example, there is a theme review VVV configuration. It’s designed for reviewing themes for WordPress.org but makes for a perfect theme-development environment. There are also configurations that use composer for dependency management, and one that uses Facebook’s HHVM for improving PHP’s performance.

You can also create your own new site from scratch by adding a new directory to www with a few files. I have posted a GitHub repo with a boilerplate VVV new site configuration. You can use this as a starting point for your sites or modify it as need be. You should also check out this page in the VVV wiki for more information on this process and links to other starting points for new sites.

To use it, download or clone the repo into the directory you created and then make a few changes to the files. First, open vvv-hosts and set the url you want to use for this site, ensuring it ends in “.dev.” Then open nginx.conf, and on the line that starts with “server_name” change the rest of the line to the url that you set in the host’s file. Also, in nginx.conf, you will need to change the line that starts with “root” to point to the directory you’re using.

Lastly, open up the file vvv-init.sh. Currently, the name of the database is “site.” You will want to change that to something more meaningful. If you intend to import an existing database, you should set the database name to match the one you’re importing. You may choose to change the username and password for the MySQL user, but I generally leave it with the same user that the default VVV sites use.

Keep in mind that this configuration doesn’t actually include WordPress itself. That’s intentional, as how I add and setup WordPress varies from project to project. Often times I’m copying from a client’s live server. Other times I’ll install it via Git, or use composer to manage it as a dependency. How you add and configure WordPress is up to you.

This configuration will create an empty database. Once it’s done, you will be taken to the WordPress installer. If you’re copying a live site, you will want to go into phpmyadmin and import the database now. You can access phpmyadmin from http://vvv.dev/database-admin/ when Vagrant is running

Once you’re ready, go to the terminal and type “vagrant provision.” When it’s done, depending on your OS, your new site may be available to you at the URL you specified in vvv-hosts. If not, you will need to use vagrant halt and once it’s stopped vagrant up again.

Welcome to the world of Vagrant

If you’re still with me and you got Vagrant up and running, congratulations and welcome to the wonderful world of using Vagrant for local development. I know it can be frustrating at times, it sure has been for me, but using Vagrant and VVV has made me a better developer.

It’s a tool worth mastering if you want to get more serious as a WordPress developer, as you can use it to work more efficiently and solve complex problems more quickly. At the same time you can avoid issues that arise from using a development environment that doesn’t match your production environment.

Did you find this introduction useful? Share your thoughts in the comments below!

Reader Interactions

There are 8 comments

How do you stay on top of your WordPress game?

A good way to start is to sign up for our weekly newsletter. We keep you up to date by bringing you the freshest WordPress content from the brightest minds in the industry.