What Is Vagrant and Why Should I Care?

If you run a web server, a database server and your scripting language(s) of choice on your main machine and you have not yet switched to using virtualisation in your workflow then this essay may be of some value to you.

I know you exist because I bump into you daily: freelancers coming in to work on our projects; internet friends complaining about reinstalling a development environment because of an operating system upgrade; fellow agency owners who struggle to brief external help when getting a particular project up and running; or even hardcore back-end developers who “don’t do ops” and prefer to run their development stack of choice locally.

There are many perfectly reasonable arguments as to why you may not have already made the switch, from being simply too busy, all the way through to a distrust of the new. I’ll admit that there are many new technologies or workflows that I hear of daily and instantly disregard because I have tool overload, that feeling I get when I hear about a new shiny thing and think “Well, what I do now works – I’ll leave it for others to play with.” If that’s you when it comes to Vagrant then I hope you’ll hear me out. The business case is compelling enough for you to make that switch; as a bonus it’s also really easy to get going.

In this article we’ll start off by going through the high level, the tools available and how it all fits together. Then we’ll touch on the justification for making the switch, providing a few use cases that might resonate with you. Finally, I’ll provide a very simple example that you can follow to get yourself up and running.


You already know what virtualisation is. You use the ability to run an operating system within another operating system every day. Whether that’s Parallels or VMware on your laptop or similar server-based tools that drive the ‘cloud’, squeezing lots of machines on to physical hardware and making it really easy to copy servers and even clusters of servers from one place to another. It’s an amazing technology which has changed the face of the internet over the past fifteen years.

Simply put, Vagrant makes it really easy to work with virtual machines. According to the Vagrant docs:

If you’re a designer, Vagrant will automatically set everything up that is required for that web app in order for you to focus on doing what you do best: design. Once a developer configures Vagrant, you don’t need to worry about how to get that app running ever again. No more bothering other developers to help you fix your environment so you can test designs. Just check out the code, vagrant up, and start designing.

While I’m not sure I agree with the implication that all designers would get others to do the configuring, I think you’ll agree that the “Just check out the code… and start designing” premise is very compelling.

You don’t need Vagrant to develop your web applications on virtual machines. All you need is a virtualisation software package, something like VMware Workstation or VirtualBox, and some code. Download the half-gigabyte operating system image that you want and install it. Then download and configure the stack you’ll be working with: let’s say Apache, MySQL, PHP. Then install some libraries, CuRL and ImageMagick maybe, and finally configure the ability to easily copy files from your machine to the new virtual one, something like Samba, or install an FTP server. Once this is all done, copy the code over, import the database, configure Apache’s virtual host, restart and cross your fingers.

If you’re a bit weird like me then the above is pretty easy to do and secretly quite fun. Indeed, the amount of traffic to one of my more popular blog posts proves that a lot of people have been building themselves development servers from scratch for some time (or at least trying to anyway), whether that’s on virtual or physical hardware.

Or you could use Vagrant. It allows you, or someone else, to specify in plain text how the machine’s virtual hardware should be configured and what should be installed on it. It also makes it insanely easy to get the code on the server. You check out your project, type vagrant up and start work.


It’s worth labouring the point that Vagrant makes it really easy; I mean look-no-tangle-of-wires-or-using-vim-and-loads-of-annoying-command-line-stuff easy to run a development environment.

That’s all well and good, I hear you say, but there’s a steep learning curve, an overhead to switch. You’re busy and this all sounds great but you need to get on; you’ve got a career to build or a business to run and you don’t have time to learn new stuff right now.

In short, what’s the business case?

The business case involves saved time, a very low barrier to entry and the ability to give the exact same environment to somebody else.

Getting your first development virtual machine running will take minutes, not counting download time. Seriously, use pre-built Vagrant files and provisioners (we’ll touch on this below) and you can start developing immediately.

Once you’ve finished developing you can check in your changes, ask a colleague or freelancer to check them out, and then they run the code on the exact same machine – even if they are on the other side of the world and regardless of whether they are on Windows, Linux or Apple OS X.

The configuration to build the machine isn’t a huge binary disk image that’ll take ages to download from Git; it’s two small text files that can be version controlled too, so you can see any changes made to the config and roll back if needed.

No more ‘It works for me’ reports; no ‘Oh, I was using PHP 5.3.3, not PHP 5.3.11’ – you’re both working on exact same copies of the development environment. With a tested and verified provisioning file you’ll have the confidence that when you brief your next freelancer in to your team there won’t be that painful to and fro of getting the system up and running, where you’re on a Skype call and they are uttering the immortal words, ‘It still doesn’t work’. You know it works because you can run it too.

This portability becomes even more important when you’re working on larger sites and systems. Need a load balancer? Multiple front-end servers and a clustered database back-end? No problem. Add each server into the same Vagrant file and a single command will build all of them. As you’ll know if you work on larger, business critical systems, keeping the operating systems in sync is a real problem: one server with a slightly different library causing sporadic and hard to trace issues is a genuine time black hole. Well, the good news is that you can use the same provisioning files to keep test and production machines in sync using your current build workflow.

Let’s also not forget the most simple use case: a single developer with multiple websites running on a single machine. If that’s you and you switch to using Vagrant-managed virtual machines then the next time you upgrade your operating system or do a fresh install there’s no chance that things will all stop working. The server config is all tucked away in version control with your code. Just pull it down and carry on coding.

OK, got it. Show me already

If you want to try this out you’ll need to install the latest VirtualBox and Vagrant for your platform. If you already have VMware Workstation or another supported virtualisation package installed you can use that instead but you may need to tweak my Vagrant file below. Depending on your operating system, a reboot might also be wise.

Note: the commands below were executed on my MacBook, but should also work on Windows and Linux. If you’re using Windows make sure to run the command prompt as Administrator or it’ll fall over when trying to update the hosts file.

As a quick sanity check let’s just make sure that we have the vagrant command in our path, so fire up a terminal and check the version number:

$ vagrant -v
Vagrant 1.6.5

We’ve one final thing to install and that’s the vagrant-hostsupdater plugin. Once again, in your terminal:

$ vagrant plugin install vagrant-hostsupdater
Installing the 'vagrant-hostsupdater' plugin. This can take a few minutes...
Installed the plugin 'vagrant-hostsupdater (0.0.11)'!

Hopefully that wasn’t too painful for you.

There are two things that you need to manage a virtual machine with Vagrant:

  1. a Vagrant file: this tells Vagrant what hardware to spin up
  2. a provisioning file: this tells Vagrant what to do on the machine

To save you copying and pasting I’ve supplied you with a simple example (ZIP) containing both of these. Unzip it somewhere sensible and in your terminal make sure you are inside the Vagrant folder:

$ cd where/you/placed/it/24ways

$ ls -l
-rw-r--r--@  1 bealers  staff  11055  9 Nov 09:16 bealers-24ways.md
-rw-r--r--@  1 bealers  staff  118152 9 Nov 10:08 it-works.png
drwxr-xr-x   5 bealers  staff  170    8 Nov 22:54 vagrant

$ cd vagrant/

$ ls -l
-rw-r--r--@ 1 bealers  staff  1661  8 Nov 21:50 Vagrantfile
-rwxr-xr-x@ 1 bealers  staff  3841  9 Nov 08:00 provision.sh

The Vagrant file tells Vagrant how to configure the virtual hardware of your development machine. Skipping over some of the finer details, here’s what’s in that Vagrant file:

www.vm.box = "ubuntu/trusty64"  

Use Ubuntu 14.04 for the VM’s OS. Vagrant will only download this once. If another project uses the same OS, Vagrant will use a cached version.

www.vm.hostname = "bealers-24ways.dev"     

Set the machine’s hostname. If, like us, you’re using the vagrant-hostsupdater plugin, this will also get added to your hosts file, pointing to the virtual machine’s IP address.

www.vm.provider :virtualbox do |vb|
    vb.customize ["modifyvm", :id, "--cpus", "2" ]

Here’s an example of configuring the virtual machine’s hardware on the fly. In this case we want two virtual processors.

Note: this is specific for the VirtualBox provider, but you could also have a section for VMware or other supported virtualisation software.

www.vm.network "private_network", ip: ""   

This specifies that we want a private networking link between your computer and the virtual machine. It’s probably best to use a reserved private subnet like or

www.vm.synced_folder "../", "/var/www/24ways",
        owner: "www-data", group: "www-data"

A particularly handy bit of Vagrant magic. This maps your local 24ways parent folder to /var/www/24ways on the virtual machine. This means the virtual machine already has direct access to your code and so do you. There’s no messy copying or synchronisation – just edit your files and immediately run them on the server.

www.vm.provision :shell, :path => "provision.sh"

This is where we specify the provisioner, the script that will be executed on the machine.

If you open up the provisioner you’ll see it’s a bash script that does things like:

  • install Apache, PHP, MySQL and related libraries
  • configure the libraries: set permissions, enable logging
  • create a database and grant some access rights
  • set up some code for us to develop on; in this case, fire up a vanilla WordPress installation

To get this all up and running you simply need to run Vagrant from within the vagrant folder:

$ vagrant up

You should now get a Matrix-like stream of stuff shooting up the screen. If this is the first time Vagrant has used this particular operating system image – remember we’ve specified the latest version of Ubuntu – it’ll download the disc image and cache it for future reuse. Then all the packages are downloaded and installed and finally all our configuration steps occur incluing the download and configuration of WordPress.

Halfway through proceedings it’s likely that the process will halt at a prompt something like this:

==> www: adding to (/etc/hosts) :  bealers-24ways.dev  # VAGRANT: 2dbfbced1b1e79d2a0942728a0a57ece (www) / 899bd80d-4251-4f6f-91a0-d30f2d9918cc

You need to enter your password to give vagrant sudo rights to add the IP address and hostname mapping to your local hosts file.

Once finished, fire up your browser and go to http://bealers-24ways.dev. You should see a default WordPress installation. The username for wp-admin is admin and the password is 24ways.

A screenshot of the installation working.

If you take a look at your local filesystem the 24ways folder should now look like:

$ cd ../

$ ls -l

-rw-r--r--@  1 bealers  staff    13074  9 Nov 10:14 bealers-24ways.md
drwxr-xr-x  21 bealers  staff      714  9 Nov 10:06 code
drwxr-xr-x   3 bealers  staff      102  9 Nov 10:06 etc
-rw-r--r--@  1 bealers  staff   118152  9 Nov 10:08 it-works.png
drwxr-xr-x   5 bealers  staff      170  9 Nov 10:03 vagrant
-rwxr-xr-x   1 bealers  staff  1315849  9 Nov 10:06 wp-cli

$ cd vagrant/

$ ls -l
-rw-r--r--@ 1 bealers  staff  1661  9 Nov 09:41 Vagrantfile
-rwxr-xr-x@ 1 bealers  staff  3836  9 Nov 10:06 provision.sh

The code folder contains all the WordPress files. You can edit these directly and refresh that page to see your changes instantly.

Staying in the vagrant folder, we’ll now SSH to the machine and have a quick poke around.

$ vagrant ssh
Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-39-generic x86_64)

* Documentation:  https://help.ubuntu.com/

System information as of Sun Nov  9 10:03:38 UTC 2014

System load:  1.35              Processes:           102
Usage of /:   2.7% of 39.34GB   Users logged in:     0
Memory usage: 16%               IP address for eth0:
Swap usage:   0%

Graph this data and manage this system at:

Get cloud support with Ubuntu Advantage Cloud Guest:

0 packages can be updated.
0 updates are security updates.


You’re now logged in as the Vagrant user; if you want to become root this is easy:

vagrant@bealers-24ways:~$ sudo su -

Or you could become the webserver user, which is a good idea if you’re editing the web files directly on the server:

root@bealers-24ways:~# su - www-data

www-data’s home directory is /var/www so we should be able to see our magically mapped files:

www-data@bealers-24ways:~$ ls -l
total 4
drwxr-xr-x 1 www-data www-data  306 Nov  9 10:09 24ways
drwxr-xr-x 2 root     root     4096 Nov  9 10:05 html

www-data@bealers-24ways:~$ cd 24ways/

www-data@bealers-24ways:~/24ways$ ls -l
total 1420
-rw-r--r-- 1 www-data www-data   13682 Nov  9 10:19 bealers-24ways.md
drwxr-xr-x 1 www-data www-data     714 Nov  9 10:06 code
drwxr-xr-x 1 www-data www-data     102 Nov  9 10:06 etc
-rw-r--r-- 1 www-data www-data  118152 Nov  9 10:08 it-works.png
drwxr-xr-x 1 www-data www-data     170 Nov  9 10:03 vagrant
-rwxr-xr-x 1 www-data www-data 1315849 Nov  9 10:06 wp-cli

We can also see some of our bespoke configurations:

www-data@bealers-24ways:~/24ways$ cat /etc/php5/mods-available/siftware.ini 
upload_max_filesize = 15M
log_errors = On
display_errors = On
display_startup_errors = On
error_log = /var/log/apache2/php.log
memory_limit = 1024M
date.timezone = Europe/London

www-data@bealers-24ways:~/24ways$ ls -l /etc/apache2/sites-enabled/
total 0
lrwxrwxrwx 1 root root 43 Nov  9 10:06 bealers-24ways.dev.conf -> /var/www/24ways/etc/bealers-24ways.dev.conf

If you want to leave the server, simply type Ctrl+D a few times and you’ll be back where you started.

www-data@bealers-24ways:~/24ways$ logout
root@bealers-24ways:~# logout
vagrant@bealers-24ways:~$ logout
Connection to closed.

You can now halt the machine:

$ vagrant halt
==> www: Attempting graceful shutdown of VM...
==> www: Removing hosts

Bonus level

The example I’ve provided isn’t very realistic. In the real world I’d expect the Vagrant file and provisioner to be included with the project and for it not to create the directory structure, which should already exist in your project. The same goes for the Apache VirtualHost file. You’ll also probably have a default SQL script to populate the database.

As you work with Vagrant you might start to find bash provisioning to be quite limiting, especially if you are working on larger projects which use more than one server. In that case I would suggest you take a look at Ansible, Puppet or Chef. We use Ansible because we like YAML but they all do the same sort of thing. The main benefit is being able to use the same Vagrant provisioning scripts to also provision test, staging and production environments using your build workflows.

Having to supply a password so the hosts file can be updated gets annoying very quicky so you can give Vagrant sudo rights:

$ sudo visudo

Add these lines to the bottom (Shift+G then i then Ctrl+V then Esc then :wq)

Cmnd_Alias VAGRANT_HOSTS_ADD = /bin/sh -c echo "*" >> /etc/hosts
Cmnd_Alias VAGRANT_HOSTS_REMOVE = /usr/bin/sed -i -e /*/ d /etc/hosts

Vagrant caches the operating system images that you download but it’ll download the installed software packages every time. You can get around this by using a plugin like vagrant-cachier or, if you’re really keen, maintain local Apt repositories (or whatever the equivalent is for your server architecture).

At some point you might start getting a large number of virtual machines running on your poor hardware all at the same time, especially if you’re switching between projects a lot and each of those projects use lots of servers. We’re just getting to that stage now, so are considering a medium-term move to a containerised option like Docker, which seems to be maturing now.

If you are keen not to use any command line tools whatsoever and you’re on OS X then you could check out Vagrant Manager as it looks quite shiny.

Finally, there are a huge amount of resources to give you pre-built Vagrant machines from the likes of VVV for Wordpress, something similar for Perch, PuPHPet for generating various configurations, and a long list of pre-built operating systems at VagrantBox.es.

Wrapping up

Hopefully you can now see why it might be worthwhile to add Vagrant to your development workflow. Whether you’re an agency drafting in freelancers or a one-person band running lots of sites on your laptop using MAMP or something similar.

Vagrant makes it easy to launch exact copies of the same machine in a repeatable and version controlled way. The learning curve isn’t too steep and, once configured, you can forget about it and focus on getting your work done.

About the author

Darren Beale is a Linux sysadmin and backend developer in Shropshire who these days spends most of his time in cashflow projections and talking to the clients of his agency, Siftware.

His dream is to retire to the woods and make furniture all day but until he can find a well paying consulting gig doing this I’m afraid we’re stuck with him.

Darren tweets and blogs about things like business, self-funded product development and chainsaws.

More articles by Darren