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.
Vagrant is a tool to "Create and configure lightweight, reproducible, and portable development environments."
Table of Contents
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?
Developing locally rocks. Vagrant is quick, easy, and helps you manage multiple development environments at one time.
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
After Vagrant is installed, pop open your terminal to verify it's installed. You can do this simply by typing this in your terminal:
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:
# 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:
Accessing the Database
From the example above, phpMyAdmin will not be installed. You can install phpMyAdmin through the provisoner if you prefer though. I prefer accessing the database through a desktop client better, however. I use both Sequel Pro or Navicat interchangeably. Connecting to the database is easy and the credentials in this example are available in both the Vagrantfile and the example index.php file located in the public folder. To connect with PHP, use these credentials:
Host: localhost User: root Password: root Port: 3306
Here's what the credentials will look like when connecting to from Sequel Pro:
MySQL Host: 172.22.22.22 (or the IP used) User: root Password: root Port: 3306
Depending on thow the Vagrant file was configured, you might not be able to connect this way since it's considered remotely accessing the database. You can still connect with a desktop client by doing a nice SSH port forwaring trick. You'll more about SSH in the next section.
MySQL Host: localhost or 127.0.0.1 User: root Password: root Port: 3306 SHH Host: 172.22.22.22 SSH User: vagrant SSH Key: ~/.vagrant.d/insecure_private_key (or your path to the private key)
Note that these credentials come directly from running
There's a ton of commands you can use to talk to Vagrant. For a full list see the official docs here, but I'll go over the more common ones.
vagrant up This is the command you just ran to boot the box up and provision the server based on the configuration file Vagrantfile. I use this for starting as well as resuming my environments.
vagrant suspend Use this command to "pause" your virtual environment. Make sure you do this before shutting down your computer to safely be able to restore the environment later.
vagrant up. The state will be saved and everything should be where you left it off from including your database changes.
vagrant destroy This permanently removes the virtual environment from your machine.
vagrant reload and
vagrant reload --provision If your environment suddenly stops working, it's useful to reboot by running this command. If you add the
--provision flag, it will reprovision the box as well. This is useful with removing or adding things to the server via Cookbooks or Puppet.
vagrant ssh Anything you edit on your computer in the public folder is automatically shared to the virtual environment without having to SSH in. However, if for whatever reason you need to connect to the virtual server, just run this command.
vagrant ssh-config This lets you see the detailed login credentials of how you could connect to the virtual environment.
Wrap-Up, Debugging, and Resources
That's all it takes to get up and running with Vagrant. Developing locally, having easy database access like this, being able to provision virtual servers from Chef or Puppet configurations, and maintaining a universal development environment for everyone can be extremely beneficial to workflow. One of the added pluses of using these provisioners are that you could technically use them anywhere to copy environments to say a staging or production server. This way you have identical development, staging, and production environments as well.
If you are having problems getting this up and running, here are some other Vagrant LAMP stacks you can try out are:
- Search GitHub for OpenSource Vagrant Stacks
- Best Vagrant Laravel Stack
- Vagrant LAMP Stack (uses Puppet instead of Chef if getting Cookbook errors)
- Vagrant Omnibus helps resolve Chef related errors
If you have questions, I'll be happy to help as much as possible. Otherwise, try these resources for support:
- Vagrant Official Documentation
- Vagrant Book
- IRC: #vagrant on Freenode
- Vagrant Google Group
- Vagrant Issues on GitHub
- Google for other Blog Posts
If you're dancing circles around this, you'll probably want to go start building and provisioning your own Vagrant boxes that work for you or your organization.
Anyways, I really appreciate anyone who spent the time to read this! I hope you enjoy using Vagrant as much as I do. Goodluck!