This is a quick getting started tutorial for Vagrant to help you get your foot in the door. The official documentation is fantastic at getting you started as well, but this article is geared more towards the absolute beginner and will cut directly to the chase on certain things.

This in no way is a replacement for referencing their documentation, and I encourage anyone who reads this to immediately read the docs after. So, with that being said, read this article if:

• You want to learn what the heck Vagrant is and does.

• You want a low-level understanding of why Vagrant will supercharge your development environment.

• You quickly want to be able to boot up a local PHP 5.4 development environment.

Heads Up! If you’re looking for a tutorial on configuring Vagrant with Chef or Puppet, this article isn’t for you. This article also expects you to have a basic understanding of the command line and Git. Lastly, the instructions here are for Mac users, but it should be very similar for both PC and Linux users.

Vagrant is a tool to “Create and configure lightweight, reproducible, and portable development environments.”

In laymen terms, this means Vagrant takes all the headache out of setting up a local development environment and replaces it with almost a single config file where you can pick and choose what features you want your server to have. No longer are you stuck using XAMMP, configuring virtual environments manually, or working remotely in your editor via FTP.

Vagrant is super powerful, and it is a lot more extensive than what this article will cover or where my understanding goes. This article will cover some pretty cool things with Vagrant, such as:

• Getting a PHP 5.4 LAMP stack running locally on your machine.

• How to easily access the database of your virtual machine.

• How to automatically update your hostfile to reference the virtual server with pretty URLs (developing on http://localhost:8080 versus http://myprojectname.local).

• Some essential Vagrant commands.

• The best and most useful Vagrant plugins.

• Links to great resources and prebuilt Vagrant stacks.

What is Vagrant and why should I even care?

Simple Reason:

Developing locally rocks. Vagrant is quick, easy, and helps you manage multiple development environments at one time.

Long Reason:

Imagine you’re developing an app with a team of say 15 people. This app is crazy awesome! It uses the Laravel PHP Framework, Redis and Memcached, Imagemagick and GD PHP Modules, curl, MySQL, PostgreSQL, and even MongoDB. On top of this, Laravel has the specific requirements of needing PHP version 5.3.7 or higher and the MCrypt PHP Extension.

Ideally, you’re going to want all 15 people on the team working on this app to have as identical development environemts. Not all the developers on the team are going to have the expertise of Sysops or being a System Admin. Getting the development environments identically setup can be a huge undertaking. On top of that, some people use Mac while others Use Linux or Windows. Before you know it, developers will be throwing computers through walls exhausted from constantly configuring and configuring.

Vagrant manages all this for you so everyone can focus on coding rather than maintaining their development environement.

Then, let’s say half-way through the project, it’s discovered that you need Beanstalkd installed on the server to start processing queues. Normally, everyone on the team will have to reconfigure their environments to use Beanstalkd hoping that it works. With Vagrant, you’ll push an update to the configuration file, and everyone will just need to reload their Vagrant boxes. Boom! Everyone can now start implementing queues in their code. It doesn’t matter if they’re on Windows, Linux, or a Mac, everyone’s development environment remains identical.

Providers and Provisioners

When I reference that Vagrant manages all of this for you, that’s not completely true. Vagrant works with “Providers” and “Provisioners” to help create these development environments. Providers, such as VirtualBox, VMWare, Amazon AWS, and Digital Ocean, are the services where your virtual environment will be created and hosted. If it be just on your local machine with VirtualBox or VMWare, or alternatively, if it be with Amazon or Digital Ocean to quickly deploy these virtual environments into the cloud.

Provisioners are tools that allow you to quickly configure your server to your exact requirements. These are great to use because they automate the sometimes daunting process of setting up a server through configuration before the server is even created. You can configure nearly everything to be installed on the server. Some examples are PHP, PHP Modules, Apache, Git, Vim, databases, logins, Xdebug, etc. The two most common provisioners used with Vagrant are Puppet and Chef. The provisioners are really neat to use because when you need to build your staging or production environments, you can use these exact same blue prints to ensure you have perfectly synced environments between development, staging, and production.

Enough! Let’s get a LAMP stack up and running

This is a step-by-step guide on setting up Vagrant on your Mac. I find that I get incompatibility errors sometimes based on the combined OS, Vagrant version, Chef versions, and even the virtual box version. I am in no way an expert, so these errors might be a lot more minor and fixable than I make them out to be. This also may seem like a lot of points for failure, but when it all works together it is absolutely astounding. Plus, Vagrant support is fantastic and their developers (beast developer?) push fixes and updates all the time. I suggest being exceptionally cautious when upgrading any of the moving parts with Vagrant, especially after you have it working perfectly for you or your organization’s purpose. Your development environment is your baby!

Install Necessary Dependencies

• Install Virtual Box

• Install Vagrant

Note: When this was written, I was currently using Vagrant version 1.4, VirtualBox 4.3.4, and Ruby 1.9 on Mac OS X Mavericks 10.9.

After Vagrant is installed, pop open your terminal to verify it’s installed. You can do this simply by typing this in your terminal:

vagrant -v

The Vagrant installer should automatically add Vagrant to your system’s PATH. You should see something similar to the image below and Vagrant is now successfully installed on your system.

    Earlier we discussed the Chef provisioner. The example we’re going through will use that instead of Puppet. There is a tool called Berkshelf that helps manage Chef’s cookbooks (PHP, PHP Modules, Apache, Git, Vim, databases, logins, Xdebug, etc.). The example also uses this. Vagrant or Chef don’t require Berkshelf, but it’s nice to have in case the Vagrant instance you use or build will take advantage of it. You can install it with the following command on Mac:

gem install berkshelf

Install Useful Vagrant Plugins

The plugins we will be installing are Vagrant Berkshelf, Vagrant Hostmanager, and Vagrant Omnibus.

The Vagrant Berkshelf plugin allows Vagrant to communicate with the Berkshelf cookbook manager we just installed.

The Vagrant Hostmanager plugin lets you add a configuration to Vagrant to automatically update your hostfile and point it to the IP in use. I really enjoy this plugin because it allows you to develop on a pretty URL such as “http://myproject.local” versus “172.22.22.22″ or the IP in use.

The Vagrant Omnibus plugin ensures the desired version of Chef is installed. The example we will be using doesn’t use this, but I find this plugin super useful for debugging when Chef related issues come up. I believe something like this might be baked right into Vagrant core one day.

Installing Vagrant plugins is a breeze once Vagrant is installed. In your terminal simply type:

vagrant plugin install vagrant-berkshelf
vagrant plugin install vagrant-hostmanager
vagrant plugin install vagrant-omnibus

Clone a Vagrant LAMP Stack

You could build your own LAMP Stack and configurations, but for simplicity and the purpose of this tutorial, we’ll just be using an already built one by this awesome developer. I’ve forked and modified the repo to get it working with my version of Vagrant, Mavericks, and VirtualBox.

Navigate to the folder you want your project to be at in your terminal and do:

git clone https://github.com/scotch-io/Vagrant-LAMP-Stack.git myfirstvagrantproject

Next, navigate to the folder and start vagrant:

cd myfirstvagrantproject
vagrant up

At this point Vagrant will start building a virtual environment based on the configuration file called “Vagrantfile”. If you want for future projects, you can go inside of here and set some useful config options that this stack has. The options I usually change are:

vagrant plugin install vagrant-berkshelf
vagrant plugin install vagrant-hostmanager
vagrant plugin install vagrant-omnibus# IP Address for the host only network, change it to anything you like
# but please keep it within the IPv4 private network range
ip_address = "172.22.22.22"

# The project name is base for directories
# Will also be the hostname for your project (e.g.: http://projectname.local)
project_name = "projectname"

After Vagrant has successfully completed, open up your browser and navigate to http://projectname.local or 172.22.22.22 to connect to your local environment (note that the image URL below is not correct for this tutorial and from an older version):

That’s it! You’re now up and running with Vagrant. To edit files and start developing, just navigate to the public folder and begin coding as you normally would. Any changes made on your computers public folder are automatically shared to the virtual environment.

You can even open up VirtualBox to see the virtual environment that you and Vagrant just created. Here’s what mine looked like at the time of writing this: