Back in October I penned a two piece series on setting up Yosemite with Apache with PHP, APC, Virtual Hosts and other goodies. There are other options available however, and one of the more popular ones is to use Vagrant to easily spin up a pre-configured virtual-machine.

In this tutorial, we'll step through the process of getting an RTD (ready-to-develop) environment installed on your Mac, Windows, or Linux desktop.

Why Vagrant?

Vagrant provides functionality that makes it easy to configure and provision reproducible environments on your local machine. What this means is that you can create an environment that you know will always run your software, and will run it the same way no matter what platform you are on, be it Mac, Windows or Linux. This is a very useful capability in this modern web development world where dealing with setup and platform requirements can be tricky, especially to the uninitiated.

For more detailed information on why Vagrant can improve your workflow, check out the official docs. Also Bob Rockefeller wrote up a high-level overview of Grav and Vagrant on his blog.

Installing Vagrant

Vagrant has a simple native installer for Mac, Windows or Linux (DEB, RPM). So head over to the Vagrant Download page, grab the appropriate package, and install it.

Installing VirtualBox

VirtualBox is free cross-platform virtualization platform that is very well supported by Vagrant. Parallels and VMWare Workstation/Fusion are also supported and provide better performance, but they are commercial products. In this guide, we will focus on VirtualBox, but you will find comments about Parallels where appropriate.

To install VirtualBox, you simply need to head over the VirtualBox official downloads page and download the appropriate package for you platform. Then install the application.

PuPHPet Configuration

Now you have Vagrant installed, the next step is to configure and build your Vagrant box. To make this process easier, we have already created a manifest with the help of a great online tool called PuPHPet. It provides a nice GUI to configure our Vagrant box with all the bits we need to run Grav properly.

This configuration is also useful for other development such as for WordPress and Joomla because it already comes with the following features:

• Debian 7.5 x64 OS (vim, htop, curl packages)
• Apache 2.4 (cache, expires, headers, rewrite, ssl packages)
• PHP 5.6 (composer, apc, xdebug, cli, common, curl, gd, imagick, intl, mbstring, mcrypt, memcache, sqlite packages)
• NFS File Shares (Mac/Linux)
• MariaDB (MySQL compatible)
• SQLite
• MailCatcher

Download Manifest

Click the big blue button below to grab the latest version of the pre-configured Grav manifest:

Now we have pretty much all we need to get our Vagrant box up and running. Extract your freshly downloaded grav-puphpet-master.zip manifest file into a good location on your computer (Projects/vagrant for example) and rename the randomly created folder to something more useful. I have mine named apache-php56, so the full folder name is Projects/vagrant/apache-php56. You can do this easily from a terminal:

$ mkdir ~/Projects/vagrant
$ cd ~/Projects/vagrant
$ unzip ~/Downloads/grav-puphpet-master.zip && mv grav-puphpet-master apache-php56
$ cd apache-php56

Spinning Up!

Before we go any further, you should install the BindNFS Vagrant plugin:

$ vagrant plugin install vagrant-bindfs

If yor on a windows-based machine you should also install WinNFSd Vagrant plugin also for improved performance:

$ vagrant plugin install vagrant-winnfsd

Now we can bring start the process of installing our Vagrant box:

$ vagrant up

This will kick off the process of download the VM image and setup according to our configuration. This can take a little time this first time, but not to worry, it will be faster after the initial heavy-lifting is done.

If you are on Mac or Linux, Vagrant will use NFS file shares, and these require your system password to setup, so when you see the prompt:

==> default: Exporting NFS shared folders...
==> default: Preparing to edit /etc/exports. Administrator privileges will be required...

Simply enter your administrator password and press return, the installation should proceed after. When you are returned to a command prompt, your Vagrant box will be up and running.

To ensure the box is running properly, we can SSH to it with Vagrant:

$ vagrant ssh
Linux packer-parallels-iso 3.2.0-4-amd64 #1 SMP Debian 3.2.57-3 x86_64
Welcome to your Vagrant-built virtual machine.
Last login: Thu Jul 17 11:48:07 2014 from 10.211.55.2

[12:33 PM]-[vagrant@packer-parallels-iso]-[~]
$

To Exit, simply type exit.

Grav Virtual Host

The Vagrant box has already been configured with a Grav virtual host, but to take advantage of this, we need to add an try in our local hosts file:

192.168.50.4  grav.dev, www.grav.dev

Now you will be able to use grav.dev, or www.grav.dev in your browser to reach the web server.

You will notice there is an existing ~/Projects/vagrant/apache-php56/grav folder. This actually is mounted directory for your http://grav.dev virtual host.

For your convenience the Grav Vagrant box includes a simple landing page as well as Grav Core, Blog Skeleton, OnePage Skeleton, and Shop Skeleton already installed.

Simply point your browser to http://grav.dev and you should see the landing page with links to each of the installed Grav instances.

Of course you can install others or copies of these and modify them as you wish.

Shutting Down

To shutdown the Vagrant box simply bring up a terminal, ensure you are in the correct Vagrant directory and run halt:

$ vagrant halt

Reconfiguring Vagrant

There are situations where you wish to make changes to your Vagrant box. Perhaps to update a configuration setting, or include a new module, or perhaps enable a new service. To accomplish this all you need to is edit your puphpet/config.yml file directly, or drag it to the PuPHPet.com service again and modify there.

After you have make your changes, you need to instruct Vagrant to re-provision the box:

$ vagrant provision

This will perform all the processing tasks similar to those that it ran through when you ran vagrant up the first time.

Destroying a Vagrant instance

For the sake of completeness, if you ever need to start over, you can completely destroy a Vagrant box. Note, this does not cause the mounted files to be lost, but the VM will be completely removed.

$ vagrant destroy

You will be able to create a new vagrant instance by calling vagrant up again.