Prudent Devs

Your Complete Guide To Vagrant On Mac

Developers, don't develop in a system close to production system, making deployment painful. Vagrant fills this gap.


Most of us, developers, don’t develop in a system close to production system. We develop in Mac (or Windows), but usually deploy on a linux flavour. This makes deployment painful. Vagrant fills this gap in the web-development process.

Vagrant makes it easy to create development boxes as close to production. Technically, virtualisation by VMWare and VirtualBox solved this issue partially. I say partially, because it has been a tedious procedure to setup a virtual machine. Vagrant abstracts virtualisation from developer and makes creating virtual boxes smooth and quick.

By developing in the virtualised machines (VMs), you can keep the development machine clutter-free.

It is also possible to share the Vagrant boxes. So all your developers can have the same development environment without cluttering their machines.

Enough of theory. Let us install Vagrant on Mac.

Vagrant uses virtualisation at the background. You could use either VirtualBox or VMWare. I use VirtualBox because it is free.

Before going ahead with installations, one advice: since these are long installation process, it is better to disable energy setting. Otherwise while installing 50 - 90 packages unattended, system might go into sleep-mode and you may have to restart the installation again

1. Install VirtualBox

Latest version of VirtualBox, as of writing, is 4.3.12. Download and open the dmg file.

Install VirtualBox

Proceed with the instructions on the screen, which are fairly self-explanatory.

2. Install Vagrant

Latest version of Vagrant, as of writing, is 1.6.3. Similar to VirtualBox, download the dmg file and open it. Proceed with the instruction on the screen to install it.

3. Discover & Download Vagrant Box

Now let us create our first vagrant box. One of the feature of vagrant eco-system is that lot of prebuilt boxes are available for download. Go to, Vagrant Cloud, and search for a box. I chose a minimal centos box.

Since I have an unreliable internet connectivity, I prefer to download the box locally and then create a vagrant box (Bit of a detail, but will help new Mac users. All of the below commands are issued in Terminal app).

If you have a reliable bandwidth, then you can type:

vagrant init chef/centos-6.5
vagrant up

This will:

  • create a Vagrantfile
  • download the centos box
  • configure everything for use
  • bring up the virtual box

If you downloaded the box first, then the commands are:

vagrant box add --name centos65 file:////Users/jjude/downloads/
vagrant up

I also prefer to create a directory for every VM box I create.

If the download (or addition) was successful, vagrant box list should list the box that was just added.

4. Essential Vagrant Plugins

When I first installed VirtualBox and Vagrant and brought up vagrant box, I got an error:

Failed to mount folders in Linux guest. This is usually because
the "vboxsf" file system is not available. Please verify that
the guest additions are properly installed in the guest and
can work properly. The command attempted was:

mount -t vboxsf -o uid=`id -u vagrant`,gid=`getent group vagrant | cut -d: -f3` vagrant /vagrant
mount -t vboxsf -o uid=`id -u vagrant`,gid=`id -g vagrant` vagrant /vagrant

This is because, vagrant is trying to setup a shared folder and it fails because shared folders can be set only if Guest Additions are installed for VirtualBox. Instead of going to VirtualBox and installing it, this error can be solved with a vagrant plugin called vagrant-vbguest. Install the plugin using,

vagrant plugin install vagrant-vbguest

and try again to bring up the vagrant box.

While we are at vagrant plugins, install another useful vagrant plugin, vagrant-list. This adds a functionality to Vagrant which will list all the boxes created using vagrant and also provide their statues. Very useful if the system becomes slow because you are running too many virtual boxes.

vagrant plugin install vagrant-list

Now if you issue, vagrant list, it will list, the details of the vagrant boxes, including those that are running.

5. Connect & Configure Vagrant Box

It is always a good practice to update the vagrant box as soon as it is created. So let us do that now. But before that you need to connect:

vagrant ssh

This will connect to the virtual machine and show vagrant prompt. Issue these within vagrant box.

sudo rpm -iUvh
sudo yum update -y

It will take sometime to update everything. If you are stepping out in-between, be sure to modify the ‘energy settings’, otherwise you may have to start over.

Once completed, exit from vagrant and reload the box again.

vagrant reload

6. Package Vagrant Box

Now that you have updated your base box, you can package this box to be used as a base box. Let us do that:

vagrant package --output

Now let us add this box to our vagrant boxes.

vagrant box add --name baseCentos65 file:////Users/jjude/boxes/

From now on, you can use this to create new vagrant boxes:

vagrant init baseCentos65
vagrant up

In case you want to remove the earlier box,

vagrant box remove centos65

7. Few useful Vagrant commands

  • stop the virtual machine: vagrant halt
  • delete a virtual machine: vagrant destroy (Beware that this is really destructive and can’t restore. Be sure what you are doing)
  • list all the virtual machines: vagrant list (after you have installed the plugin mentioned earlier)

8. SharedFolder & VagrantFile

Cool thing about vagrant is that it automatically sets up the current host folder as the share folder within the virtual machine. It is accessible at /vagrant from within the virtual machine.

When you create a vagrant box (by vagrant init), it creates a config file named VagrantFile in the host’s folder. So far I have played around with this config file only for port forwarding. There are other uses too. You should refer to the documentation. How does port forwarding works? Let’s say you run a web server within vagrant and you want to access the server from the host’s browser. Then you forward the guest’s port (virtual machine) to the host. The configurations are: "forwarded_port", guest: 8080, host: 8080 "forwarded_port", guest: 9200, host: 9200

Here, I forward two ports from the guest’s to the host’s.

Remember to vagrant reload if you change the VagrantFile while vagrant is up and running.

9. Uninstall Vagrant

In case you want to remove Vagrant from your Mac, say for upgrading:

sudo rm -rf /Applications/Vagrant
sudo rm /usr/bin/vagrant
sudo rm -rf ~/.vagrant.d

10. References

Vagrant documentation is detailed and that should serve you well. There are other blog posts that helped me as well.

Vagrant DocumentationDevelopment and production environments with Vagrant, VirtualBox and GITEasy Custom Vagrant Packages

Published On:
Under: #tech , #devops
Sign up for my newsletter