Why Not WAMP or MAMP?

Recently I wanted to get the PHP extension Enchant working for an app I am developing. While php.net says this extension is bundled with PHP after v 5.3, I found that wasn't the case with my installations on either WAMP Server 2.0/2.2 or on MAMP. I tried and failed to get the extension working many times before throwing in the towel and turning to Vagrant. If you're unsure what Vagrant is, let's just call it a mysterious a form of dark magic that makes setting up a virtual machine on your native OS amazingly simple. Why would you want to do this? Are you a server admin now? Well yes and no, but mainly yes. I believe that any web developer owes it to themselves and their clients/company to understand the environment in which their app exists. Packages like WAMP and MAMP abstract this away from developers enough so that they don't have to worry about it too much which is all well and good for the most basic of apps, but for anything more complex, you're giving yourself a huge advantage on shipping a better product if you understand the stack where you house it. You're also removing personal limitations that stop you from learning new things, and that's a huge, huge plus in an industry that can quite literally change over night. Combining Vagrant with PuPHPeT almost feels like cheating. Almost. There are a couple of fiddly things you may need to do on both Windows and OS X but I'll be going through everything that I learned here so hopefully that will be enough to get you through. Just a note - this guide is relevant to Windows 7 and OS X Mavericks. Also, this is a guide that's mainly focused on setting up a LAMP stack, but I'm confident that after following all the steps, you'll become pretty well acquainted with Vagrant and will most likely be able to set up any kind of stack you require afterwards.

Things you'll need

  1. Vagrant
  2. VirtualBox 
  3. Msysgit (Windows only)
  4. PuPHPet files (not required but definitely makes things easier)
  5. Some command line / shell experience
  6. Something to do while waiting (when you play the game of waiting, you either listen to Homer or you die)

Step 1 - Install Vagrant & VirtualBox

Super easy stuff, just download the relevant installers for your OS and install them. After installing Virtual Box, just close it, you won't really need to touch it - Vagrant does that for you. I had a slight problem installing Vagrant on Mavericks as it kept telling me I didn't have permission to do so, even though I was the admin. If you have this problem, 'right' click the Vagrant.pkg file and select Get Info. After that, open up the sharing and permissions drop down and click that tiny lock icon you see near the bottom right to unlock the file. You should be good to go after that.

Step 2 - Install Msysgit (Windows only!)

If you're on Windows and you don't have this installed already...shame on you! But seriously get it right now and install it. You'll get some cool stuff like Git GUI and more importantly for this guide - Git Bash. This basically gives you a non crappy command line tool complete with git and familiar Linux command prompts. No more dir or %HOMEPATH%, you can ls -la and cd ~ all you like. If you think Git Bash also sucks, go one step further and install conemu.

Step 3 - Make a hostname file

This is a tip I received from my good friend @okonomiyaki3000. I'm not entirely sure how it works, but doing this will stop your Vagrant install from getting the following error
 failed receiving fact fqdn
I'm still not sure what this is related to (it could be something to do with Ruby but don't quote me on that) or even if it is a problem, but as a general rule of thumb, if you can avoid errors, you should. So this is how you stop this one from occurring
cd ~
mkdir .vagrant.d
cd .vagrant.d 
sudo vim Vagrantfile
Now inside of this Vagrant file paste the following then save and you're done.
Vagrant.configure("2") do |config|
config.vm.hostname = "local.myhostname"
Go to back your home directory
cd ~
And run
mkdir vagrant
That's it for now, we'll come back to this directory after the next step.

Step 4 - Get a PuPHPet zip

Now you're ready to use PuPHPet. Go to the site and go through all the configuration options. For the record I chose the following
  • CentOS 6.4 x64 - Virtual Box 4.3
  • Installed Packages: vim-common
  • Apache 2
  • Apache modules: php, rewrite
  • Server name corresponding to myhostname from step 3
  • PHP v 5.4
  • MySQL (with an empty starting database)
Now for a very cool feature about Vagrant - synchronized folders. Yep, you can tell Vagrant to sync a local machine folder to a folder on your virtual box. This is really great if you are working as part of a team or have all your projects backing up to the cloud for easy access across multiple devices. PuPHPet makes this super simple. In the configuration section titled Sharing Folders with Local VM, simply put the paths to your local directory and the directory you want to map its files to on the VM in the correct input fields. I put my sync'd files in /var/www/html/sync. After you're done, create your manifest and download the zip file.
Note: I've had issues with synchronized  folders on OS X. Basically the permissions for the majority of directories inside the sync'd folder (/var/www/html/sync) are wrong thereby denying me access to them via the browser. I'm really not sure how this happened, or how some folders have correct permissions and others do not, so as of this time, I'm still looking for a solution. Any help would be appreciated!

Step 5 - Vagrant up yourself!

You're almost there. Unzip the contents of your puphpet.zip file and copy the puhphet directory and Vagrantfile directly to your chosen Vagrant directory (mine was ~/vagrant). Once you've done that, open up the command line and do the following
cd ~/vagrant
vagrant up
And that's pretty much it. Remember how I said you'd need something to do while waiting? Well do that thing, now. This is going to take some time, especially if it's the first time you're installing your box's operating system (you'll only ever have to do that once). Once the whole process is done, you should be able to shell into your box using the following command
vagrant ssh
And that's it! You now have a Vagrant box set up on your computer.

Accessing your VM in the browser

You'll need to boot the server each time you start up your computer. To do that just open up your command line tool and once again run
cd ~/vagrant
vagrant up
Don't worry it will only take a few seconds this time to start up. When the server is running, you can access your /var/www/html directory by going to the server's IP address in the browser (if you left this unchanged in PuPHPet it should be If you don't like entering an IP address in your address bar, open up your hosts file and direct that IP to any url you like.

The end of this Vagrant Story...

That wraps up this guide, but unlike one of the most awesome video games in history, this one will probably have a sequel some time soon. Got any comments, questions or advice? Please feel free to let me know in the comments section.