As with many things in life, I recently learned that I’ve been doing things the hard way when it comes to WordPress development and Vagrant.

I got on the Varying-Vagrant-Vagrants bandwagon years ago.   It made it easy to write my Store Locator Plus code and test it on several different WordPress installations.    Along the way I learned how to provision my test boxes and share code between them.   When VVV 2 came out earlier this year I decided to upgrade.  It did make things easy, but in the early days of limited documentation I followed a few sparse examples and “figure out my own way”.   Of course that turned out to be the hard way of doing things.    I’m going to share with you the shortcuts I learned today to hopefully save you some time.

Getting started with VVV

You’ll need a virtualization product, go get Virtualbox from Oracle.  It’s free, works on most platforms and is as capable as any paid systems I’ve used.   The applications create mini-servers inside your laptop, mimicking what web hosting providers give you but in a self-contained environment ready for your hacking.

You’ll also need the Vagrant software, which is a manager for the virtual machine that allows scripts and other automation tools to do all the hard work of setting things up and breaking them down.  Go get that next.

No you’ll need the Varying Vagrant Vagrants piece.  This is a WordPress-centric set of scripts and configuration files for Vagrant that will help you create a local WordPress development environment.  Perfect for contributing to WordPress Core, building your own plugins and themes, or testing a new design for a client without going through hosting companies.   You’ll probably notice I’ve linked to the main GitHub page for the project.    I’m going to assume you already have git installed and know how to pull a repository.   Use git and clone the repository to a local directory.   The standard is ~/vagrant-local.

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

Now let VVV2 spin up some default WordPress sites including the development and stable versions.   Use vagrant up and the first go-around will pull down the virtual box image then grab all the code for WordPress and put it in a pre-configured local site.

# vagrant up

You may be asked for admin permissions to update your local website directory pointers (the /etc/hosts file) ; keep an eye out for that.

When everything is up and running enter http://local.wordpress.test/ into your browser.   Make sure you use the http:// and ending slash so you don’t fire up a web search that is the default for most browsers that don’t recognize the .test TLD.   You should see a default WordPress site come up.
Side note: VVV2 stopped using .dev as an extension because that TLD is owned by Google and may cause some side effects in the future.  

Now for custom sites…

OK, you’ve got your base VVV setup going and can bring up the site.    Cool.   If you wanted to you could now go hog-wild with WordPress development and start adding code to the ~/vagrant-local/www/wordpress-default directory.  Add your new plugins there, hack up some code.  BUT DO NOT DO THAT.

As I mentioned, I did things the hard way but creating a new isolated site where you can hack-things up is far too easy with VVV2.    Here are the simple steps to do it.

Go to your ~/vagrant-local directory and copy vvv-config.yml to vvv-custom.yml.    This file will now be the default configuration the VVV2 scripts will read to manage your sites on the virtual box.

# cd ~/vagrant-local
# cp vvv-config.yml vvv-custom.yml

Edit your vvv-custom.yml and tell it you want to create a new test setup called called my-site that you will get to at http://my-site.test/, add the following lines to the file.  Make sure they are indented properly as indents are important to YAML.

# These are your websites, and their names map on to the folders they're
# located in. See the docs for how to define these, and what all the keys
# and options are
sites:

  my-site:
    repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template
    hosts:
      - my-site.test

Re-provision your Vagrant box:

# vagrant reload --provision

This will take a little time to create your new WordPress development site but when it is done you will have a clone of the WordPress latest version in a new directory you can hack up as you please.  The best part is you will not mess up the versions that ship with VVV2.   Go ahead and use this to source a new git repo called “my-site”, though I recommend you create your repos on an individual plugin or theme bases.

Check out the custom site

Once your box is done being provisioned you can go back to http://local.wordpress.test/ where you should see your new My-Site entry partway down the page.   Click on it to bring up the new custom site.

No more editing a custom dashboard; I used to add new test sites to my dashboard file on a regular basis.

No more need to create you own custom provision files.

You can now create lots of copies of the default WordPress development setup to hack new sites, themes and plugins.

VVV2 Tips and Tricks

VVV2 has WordPress debugging ready-to go, you only need to turn on xdebug to be able to trace code with real-time tools like the debugging tool built into phpStorm.

# cd ~/vagrant-local
# vagrant ssh -command='xdebug_on'

Change your site to use the latest nightly build of WordPress by adding custom fields to your vvv-custom.yml file:

my-site:
  repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template
  hosts:
    - foo.test
  custom:
    wp_version: nightly

Or specify a WordPress version:

my-site:
  repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template
  hosts:
    - foo.test
  custom:
    wp_version: 4.4