We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

Why & How-To Set Up a WordPress Local-Development Environment With Vagrant

Posted Aug 12, 2013 38.2k views WordPress System Tools

The Limitations of LAMP Stacks

Historically, when setting up a local development environment, WordPress developers resorted to traditional LAMP stacks (Linux + Apache + MySQL + PHP) such as MAMP, WAMP or XAMPP. Meanwhile, advances in WordPress development have landed most modern WordPress installations on virtual private servers ("VPS") running Nginx with configurations – that emphasize caching – tailored specifically toward speeding up WordPress. MAMP, WAMP or XAMPP, however, run on Apache; with no optimization for WordPress and with no widely-accepted configuration for caching or any other optimization measures.

Developers agree that it is "extremely important to make sure that your development environment is identical to the production environment, and matches staging and testing servers if you have those too."[#]

By not mirroring your environments, the chance increases that something that seems to work just fine in an Apache-based local development environment will fail to work on the production server. A common frustration with LAMP stacks today is that they, now, seldom match the environment of the live, or production, server. Cutting-edge server setups for WordPress hosting these days include some combination of Nginx, MySQL, PHP-FPM and Memcached (note the 'd'!) – at a minimum.

Why Vagrant?

Even subtle differences between environments increase the likelihood that your code modifications, plugins or web apps will fail in the testing, or staging, environment – resulting in wasted time troubleshooting, when you otherwise could be developing further. Now, consider the possibility that you may want to test your WordPress configurations by throwing into the mix the PECL memcache extension, or Varnish, and you'll happily discover: Why Vagrant. With Vagrant, you can easily recreate the same environment, anywhere, (literally) no matter what operating system or platform you choose for development. You can provision machines locally or with a VPS such as DigitalOcean.

Not Ready to Break up with your Beloved LAMP Stack?

With Vagrant, even those that continue developing with a LAMP stack have discovered that "Vagrant ... seems to solve all of the issues I've had in the past when trying to get a local environment up for WordPress."[#] Lastly, Vagrant is portable – allowing other members of your team to create their development environments from the same configuration you use – ensuring that all your team members are running code through the same environment, against the same dependencies, all configured the same way; regardless of whether any of them are working from Linux, Mac OS X, or Windows workstations.

Prerequisite for Windows users

Vagrant is configured with a shell, or an operating system's command line interface ("CLI"), and OpenSSH. Unfortunately, an SSH client is generally not distributed with Windows, by default. However, Windows users can connect to Vagrant with any of their favorite SSH clients, e.g. one of the shells provided in GitHub for Windows; a terminal in Cygwin; Git Bash or PuTTY, among others.

Getting Started

On your local workstation, you'll need to:
  1. Download & install the latest version of VirtualBox for your operating system.
  2. Download the matching VirtualBox Extension Pack (the same for all platforms) and install it on your computer;
  3. Having VirtualBox installed should make the Extension Pack a recognized file type.
  4. Download & install the latest version of Vagrant for your operating system;
  5. The first step for any project is to configure the Vagrantfile. The purpose of the Vagrantfile is twofold: (i.) Mark the root directory of your project (a lot of the configuration of Vagrant is relative to this root directory); and (ii.) Describe the kind of machine and resources you need to run your project, as well as what software to install and how you want to access it.
  6. Mac OS X & Linux-variant users: Open a shell, e.g. terminal, and create, or navigate to, the directory in which you'd like to save your Vagrantfile (on Ubuntu, this would look like):
    sudo mkdir ~/[name of your choosing]cd [newly-created folder]
    Vagrant has a built-in command for initializing the newly-created directory for usage with Vagrant: vagrant init. NOTE: You can also run vagrant init in a pre-existing directory to setup Vagrant for an existing project.
  7. Next, execute the initializing command:
    vagrant init
  8. This will place a Vagrantfile in your current directory. Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile is supposed to be committed to version control (e.g. Git). This way, every person working with that project can benefit from Vagrant without any of the upfront legwork.One concept to be mindful of is Vagrant's use of boxes. Vagrant uses .box files as templates from which to spin up a new VPS. Instead of building a VPS from scratch – which would be a slow and tedious process – Vagrant uses a base image to quickly clone a VPS. These base images are referred to as boxes, and specifying the box to use for your Vagrant environment is always the next step after creating a new Vagrantfile.
  9. Next, execute the following commands:
    vagrant box add precise64 http://files.vagrantup.com/precise64.boxvagrant up
  10. Microsoft Windows users: Regardless of the command line program, the next steps are the same. If you choose to continue with Windows' command prompt, you can open the relevant CLI by (i.) pressing, on your keyboard, the Windows key (ii.) followed by the R key; which will open the RUN dialog box. Now, (iii.) type:
    and (iv.) press Enter.Next, execute the following commands (pressing Enter after each line):
    cd C:\HashiCorp\Vagrant\binvagrant box add precise64 http://files.vagrantup.com/precise64.boxvagrant init precise64vagrant up
    NOTE: Sometimes, Windows workstations will spit out an error message when attempting to execute an initial Vagrant command. Restarting the computer usually remedies most post-installation issues. Later, if you get an error message to the effect that an "ssh executable is not found," and restarting the computer did not update the path, automatically, you can set the SSH PATH by executing the following command (assuming the ssh.exe file is in the folder referenced, below):
    set PATH=%PATH%;C:\Program Files (x86)\Git\bin
After running the above commands, you'll have a fully running VPS in VirtualBox running Ubuntu 12.04 LTS 64-bit. You can connect to this machine, via SSH, with the command vagrant ssh

Using PuTTY?

PuTTY is not compatible with OpenSSH, out-of-the-box. Consequently, PuTTY will not recognize the insecure_private_key provided by Vagrant as a valid private key. A workaround is to use PuTTYgen to Load (i.e. import) the insecure_private_key found in the .vagrant.d folder in your Home Directory, e.g.
  • Windows XP: C:\Documents and Settings\{your username}\.vagrant.d\
  • Windows 7: C:\Users\{your username}\.vagrant.d\
and convert the key file into PuTTY's format (a .ppk file) by clicking on the Save private key button.

Then, launch PuTTY and enter the following connection information:

Category Sub-category FieldValue
Session Host Name:
Port: 2222
Connection type: SSH
Connection Data Auto-login username: vagrant
Connection/SSH Auth Private key file for authentication: Click on the Browse button and find the .ppk private key you just converted
Session Saved Sessions vagrant (and then click the Save button for the Load, save or delete a stored session area)

Finally, click on the Open button, at the bottom of the PuTTY window, to log in automatically to your Ubuntu VPS;

and when you're done playing around, you can remove all traces of it with the command vagrant destroy. The Using a Box and subsequent sections of Getting Started | VagrantDocs are quite good – please refer to that guide for a walk-through of setting up a more complete project, if you would like to continue building on your own, custom Vagrant box. Once you've got your box all set up, you can deploy WordPress, and whatever other software packages you'd like. However, if you're a little timid about 'flying solo' ...

Not to Fear, the Power of the Open-source Community is Here!

If you'd like to get a jump-start on developing WordPress, locally, with Vagrant, check out Varying Vagrant Vagrants for WordPress Development, on GitHub (an exploration into the world of Vagrant and how it can help make development efficient and in sync with production systems; by replacing the common MAMP or XAMPP setups that we have become familiar with, while ensuring that all members of the team can develop in the same environment for a project without worrying about the operating system on their local machine).With Varying Vagrant Vagrants, you will be able to fire up an instance by executing the simple vagrant up command, that will automatically install Nginx, PHP-FPM, and MySQL; before proceeding to move configuration files around and import SQL dumps – so that just minutes after the initial command, you can go to an existing development site in your browser or initiate a brand new WordPress install.[#]

And so, without further ado:

  1. At a minimum, complete Steps 1 - 3 under Getting Started, above:
  2. OS X & Linux-variant users: Open a terminal and create, or navigate to, the directory in which you'd like to save your work (on Ubuntu, this would look like):
    sudo mkdir -p /srv/[name of your choosing]cd /srv/[newly-created folder]
    and clone Varying Vagrant Vagrants from GitHub, by executing the following commands:
    sudo git clone https://github.com/10up/varying-vagrant-vagrants [local folder name of your choosing]
    Windows users: that downloaded & installed GitHub for Windows can click on the button (the default storage directory can be changed under tools => options – in addition to the default shell); or, if you would rather not use GitHub for Windows, you can download a ZIP file of the repository to a local directory, that you'd like to use for your Vagrantfile, and extract it from there.
  3. Now, in a terminal or Windows command prompt, navigate to the new directory:
    cd [new local folder w/repository from Step 2, above]
    and execute the following command:
    vagrant up
  4. With that, your VPS is running (the first time you vagrant up, however, Vagrant can take approx. 30-60 minutes, as it downloads all the pre-packaged software and relevant updates). Test it immediately by going to in a web browser. To start working with WordPress, one more step is necessary.
  5. Modify your local machine's hosts file so that local.wordpress.dev is mapped to;[#]
  6. Once mapped, visiting local.wordpress.dev in your browser will bring up an initial WordPress installation. Follow through that to create your first WordPress development environment in Vagrant. Themes and plugins that you are developing can go into the relative www/wordpress-default/wp-content/ directories.
From here, you should experiment. If you are familiar with object caching, the common plugins for working with PECL memcache can be installed. Memcached itself is already installed and running for when you're ready. If you start poking around the internal documentation for Varying Vagrant Vagrants, you'll see quite a few places where you can hook in with customizations of your own to continue to extend the development environment. For alternative approaches, that have also done a lot of the upfront legwork for you, check out: Getting Started With Vagrant | Scott Warren or Getting Started with Vagrant for WordPress Development | Mike Green.

Additional Resources

As always, if you need help with the steps outlined in this HowTo, look to the DigitalOcean Community for assistance by posing your question(s), below.

Article Submitted by: Pablo Carranza


Creative Commons License