Tutorial
Why & How-To Set Up a WordPress Local-Development Environment With Vagrant
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:
- Download & install the latest version of VirtualBox for your operating system.
- Download the matching VirtualBox Extension Pack (the same for all platforms) and install it on your computer;
- Download & install the latest version of Vagrant for your operating system;
- 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. - Next, execute the initializing command:
vagrant init
- Next, execute the following commands:
vagrant box add precise64 http://files.vagrantup.com/precise64.boxvagrant up
Having VirtualBox installed should make the Extension Pack a recognized file type.
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.
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.
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:
cmdand (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 upNOTE: 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.and convert the key file into PuTTY's format (a .ppk file) by clicking on the Save private key button.
- Windows XP: C:\Documents and Settings\{your username}\.vagrant.d\
- Windows 7: C:\Users\{your username}\.vagrant.d\
Then, launch PuTTY and enter the following connection information:
Category Sub-category Field Value <tr><td>Session</td> <td></td> <td><b>Host Name:</b></td> <td>127.0.0.1</td></tr> <tr><td></td> <td></td> <td><b>Port:</b></td> <td>2222</td></tr> <tr><td></td> <td></td> <td><b>Connection type:</b></td> <td>SSH</td></tr> <tr><td>Connection</td> <td>Data</td> <td><b>Auto-login username:</b></td> <td>vagrant</td></tr> <tr><td>Connection/SSH</td> <td>Auth</td> <td><b>Private key file for authentication:</b></td> <td>Click on the <b>Browse</b> button and find the <b>.ppk</b> private key you just converted</td></tr> <tr><td>Session</td> <td></td> <td><b>Saved Sessions</b></td> <td>vagrant (and then click the <b>Save</b> button for the <b>Load, save or delete a stored session</b> area)</td></tr></table>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:
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.
- At a minimum, complete Steps 1 - 3 under Getting Started, above:
- 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.- 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 upWith 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 192.168.50.4 in a web browser. To start working with WordPress, one more step is necessary.
- Modify your local machine's hosts file so that local.wordpress.dev is mapped to 192.168.50.4;[#]
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.
Additional Resources
- Development Environments Made Easy with Vagrant and DigitalOcean;
- How to Install Vagrant on a VPS Running Ubuntu 12.04;
- How to Use Vagrant on Your Own VPS Running Ubuntu;
- How to Use DigitalOcean as Your Provider in Vagrant on an Ubuntu 12.10;
- How To Install VirtualBox on Ubuntu 12.10 x64 | DigitalOcean;
- How to Install Git on Ubuntu 12.04 | DigitalOcean;
- How to Use Git Effectively | DigitalOcean;
- How to Use Git Branches | DigitalOcean;
- Git Reference;
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.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
About the authorsPablo Carranzaauthor
2 CommentsThis textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Become a contributor for community
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
DigitalOcean Documentation
Full documentation for every DigitalOcean product.
Resources for startups and SMBs
The Wave has everything you need to know about building a business, from raising funding to marketing your product.
The developer cloud
Scale up as you grow — whether you're running one virtual machine or ten thousand.
Get started for free
Sign up and get $200 in credit for your first 60 days with DigitalOcean.*
*This promotional offer applies to new accounts only.
Mac user here, the "box add … " command didn’t work for me (404 error on the url).
After some poking around, I found that it was easier for me to just use “box add ubuntu/trusty32” (My droplets use 14.04 i.e. trusty, so I felt it appropriate to use trusty) followed by vagrant up.
Mac OS command to add vagrant box is incorrect.
Instead of:
‘vagrant box add precise64 http://files.vagrantup.com/precise64.boxvagrant up’
It should be:
‘vagrant box add precise64 http://files.vagrantup.com/precise64.box’ ‘vagrant up’