Vagrant Development Environment Introduction

Vagrant helps automate the use of virtual machines to normalize a dev environment. Simple commands like » vagrant up make it easy to manage virtual machines from a command line or script. Vagrant's configuration files can automatically get a VM ready for development by installing the required dependencies.

Development within a VM makes bugs more likely to be repeatable. If the same VM is deployed to production there's less chance of a difference between production and development systems causing unforeseen problems.

This isn't an in depth tutorial. This page covers only the most basic info. For a complete tutorial read the Vagrant Manual. The main attraction here is a Vagrantfile with a bunch more notes and examples.

Installing Vagrant

First you need to install a Virtual Machine Provider. The examples use Virtual Box since it's free, but Vagrant also works with VMWare and other VMs.

Some OS distributions have Vagrant in their software repositories. In my experience, it's best to grab a fresh copy from the Vagrant Downloads page. Vagrant has installers for GNU/Linux, Mac & Windows.

A Test Run

Once Vagrant is installed open a terminal and enter:

mkdir vagrant-test
cd vagrant-test
vagrant init hashicorp/precise64

That last line will pull in a 64bit Ubuntu 12.04 Vagrant Box (VM image) from the Vagrant Cloud. There are many other Vagrant Boxes to choose from. Some are bare bones and others come with a suite of software pre-installed.

During Vagrant initialization, a Vagrantfile is created in the current directory. The file contains basic setup for the VM. You might want to open it & skim through to get a sense of what the next command does.

Now to bring the VM up for the first time:

vagrant up

This command processes the Vagrantfile and starts the VM running. On first start up Vagrant also performs provisioning (dependency installation & your config).

Vagrant Boxes typically have a local SSH tunnel setup. To access it just run:

vagrant ssh

You can also customize SSH config using the Vagrantfile.

Within the Vagrant Box VM you'll find the directory /vagrant/ is mapped to the directory in the host that was initialized, vagrant-test in this example. If everything is working properly you should see the Vagrantfile there. Try to create a file then exit the SSH session:

touch /vagrant/hello.txt

If synchronization is working the /vagrant-test/ directory should contain a hello.txt file.

To stop running the Vagrant Box use:

vagrant halt

From this point you could restart the VM via » vagrant up or destroy it via:

vagrant destroy

Vagrantfile Notes

Rather than initializing a specific Vagrant Box we can do a plain initialization:

mkdir vagrant-test
cd vagrant-test
vagrant init

This will place a Vagrantfile in the vagrant-test directory. Open the file and you'll find some notes to help you get started with vagrant.

I've added more tips and examples to the stock Vagrantfile. For example: How to use an external script for provisioning. Some details I've noted are not mentioned in the official documentation.

Download the Vagrantfile with extra notes here. My additions are marked with [CL].

Once you've modified the Vagrantfile place it and your development files in the initialized directory then » vagrant up to start the VM and test your project.