I saw a commercial on late night TV, it said,”Forget everything you know about slipcovers.” So I did. And it was a load off my mind.
— Mitch Hedberg
You can forget everything you know about vagrant…
There are a million ways to use it, there are countless tutorials on how to get it going to work for your app, but still when the time comes to actually try vagrant out … well nothing makes any sense.
The illusive Vagrantfile
I’m sure this is probably the first thing you’ve encountered while reading up on vagrant. This file seems to be the main hurdle to make your installation work.
This is where the config goes and once you run that magic command vagrant up, all your provisioning dreams will be fulfilled.
I wish it were that easy. I think the most obvious question one would ask at this point is .. “well, what do I put into my config i.e. Vagrantfile“?
And that’s where all hell breaks loose…
Frantic googling
In an epic quest to find answers as to just how to properly setup our vagrant we start researching and find countless examples of setting up a local dev environment with vagrant.
There are lots of stacks and pre-configured examples available on github… and with a few minor tweaks it seems like it’s just about to work… but alas, this or that constantly fails.
We have tried chef, puppet, ansible and good ol’ bash scripts, we’ve made changes to config and private keys, but still something, somewhere is amiss.. and we try again.
Enter puphpet.com
The unpronounceable puphpet.com service (yeah, the “p” is silent) … wraps a nice web-based GUI around the Vagrantfile config.
Behind the scenes it will use puppet for provisioning various tools that your might require in your project.
However the main reason I recommend puphpet over manual configuration, is due to relative simplicity of how the setup is achieved.
You pick the tools and extensions via a GUI (databases, vim, htop, apcu, redis, composer, etc.) and the necessary config is created for you. All you have to do is download your “zipped” vagrant box and place it in a directory creatively called vagrant inside your project. (This way if you ever need to get rid of it or re-create your box, as you probably will, you just blow away the dir and create a new one with the new VM).
Key concepts
Maybe we should’ve have started with that, but my guess is that you’ve already done some reading on the subject.
However, it is still important to take a step back and figure out what it is that we are trying to accomplish?
- We need an environment that can run our project
- We need a localhost (i.e.
local.example.com) where can we see our app in the browser - We need a way to edit our app files cloned from the remote using our favorite text editor (or IDE)
- We need a local db(s) and ability to browse it (them)
As we probably know, vagrant allows us to do all of the above, but we still haven’t managed to figure out just how, exactly?
Virtual Hosts
First, let me address the virtual host issue. Each vagrant box will get an IP address assigned, just like a remote server you’d buy at AWS, for example. As such, you could easily assign a local IP to your app (i.e. 192.168.56.103) and make the following entry in your /etc/hosts file (on your host machine, NOT inside vagrant VM).
192.168.56.103 local.example.com
Now, if you go to your browser and load up http://local.example.com, the server should load the document root to which you’ve pointed your vagrant’s web server (be it apache or nginx).
Let’s talk about this part next… Pointing things to the right places.
Synced Directories
This is important. During your vagrant configuration you need to specify a local directory and the “mapped” vagrant directory where your code will reside.
Here’s an example…
On my local machine the project lives in /home/users/teknoid/work/my-project, this is the directory I cd into when working on the files locally.
On my vagrant box I can map this location to say, /srv/my-project.
Following this example, when I run vagrant ssh (to login into my virtual server) I will typically cd /srv/my-project to run a command such as composer update (Or maybe app/Console/cake test app, if trying to run CakePHP tests).
The cool part is that if you need to modify any of the app files or write a new unit test, you don’t have to use “vi” or other tool on the virtual server. You can open up your project from /home/users/teknoid/work/my-project (following our example) and any changes made to the files will be automatically reflected in your vagrant VM.
Databases
Hopefully by now you see how the vagrant virtual box is getting married to your host OS via filesystem and web hosts.
However, you’d typically want to browse the database which stores your application data. Of course, since the actual db is running inside your VM you cannot access it by using “localhost” and some GUI client.
(You could for example install phpmyadmin for MySQL, but that’s not a very clean solution).
Rather it is recommended to use SSH authentication and connect through a dedicated client.
A picture is worth a thousand words, so let’s take a look at a sample config from my SequelPro
Let’s just note a couple of things:
- First, we are using an SSH connection (or SSH tunnel).
- The whole portion of the SSH setup is how you’d authenticate the client to access the vagrant box.
- The IP address of the SSH host is the one we’ve assigned to our vagrant box. (Consequently it should be the same as the one you’ve used for your /etc/hosts file).
- The MySQL connection remains the same as it typically would. Just some credentials that you’ve already setup for your app.
- The key part (pun intended) is the SSH Key setting. If using puphpet.com you’ll get an ssh key just like the ones you use for password-less authentication. By default it will be located in:
vagrant/puphpet/files/dot/ssh, so you’d simply point your client to theid_rsakey.
Do not be afraid
Even if you use the best tools and follow the greatest tutorials, chances are some incompatibility somewhere may break things. If you find yourself digging for complex solution, I recommend re-creating a new vagrant box and double-checking various config values.
Do not be afraid, to completely remove your vagrant directory (that’s why I recommend keeping it inside a subdir) and start from scratch. Use puphpet.com to create as many custom vagrant boxes as you need with various configs and settings. Try and fail and learn. The only thing you’ll need to do is make a few extra clicks and keep running vagrant up until the magic happens.
vagrant cheers
