<<TableOfContents()>>

= Testing Deployments with Vagrant =

Testing a server deployment with [[https://www.vagrantup.com/|Vagrant]] can be super convenient in some cases, such as:

 * You're developing a new server bundle.

 * You have obtained a server bundle from someone else (e.g. the [[Deployment/Demo|demo project]]) and wish to test it out.

 * It's time to replace a live server, and you wish to perform a dry run as part of the preparation.

So what exactly is Vagrant?  It is a means by which you can fire up a virtual server, for use as a test target.  It is surprisingly fast considering what it gives you.  When you create a new virtual machine with Vagrant, you are effectively meeting all the [[Deployment/ServerMachinePrep|Server Machine Prep]] requirements in a single step, with a "server" that is completely disposable.

== Prerequisites ==

First you should already have set up your [[Deployment/ControlEnvironment|control environment]].  You can (and typically should) use the same control environment for Vagrant testing that you use for production deployment.

Vagrant supports multiple virtualization back-ends, but the author has only tested with [[https://www.virtualbox.org/|VirtualBox]].  This is free and is the default back-end for Vagrant, so these docs will assume it to be the back-end.  Installing !VirtualBox is mostly outside of the scope of this doc, but it ''should'' be as simple as:

{{{
sudo apt-get install virtualbox
}}}

Now you must install Vagrant.  The author has had poor luck trying to use the packages provided by APT (i.e. on Debian/Ubuntu).  The recommended approach is to [[https://www.vagrantup.com/downloads.html|download Vagrant]] from their website in order to get a more recent version.

== Usage ==

Your server bundle must include a `Vagrantfile` for this to work.  It is assumed that this file exists in the root of the server bundle.  If you do not yet have such a file, you can use this as a starting point (should work fine as-is):

{{{#!highlight ruby numbers=disable
# -*- mode: ruby -*-

Vagrant.configure("2") do |config|
  config.vm.box = "debian/jessie64"
  config.vm.network "forwarded_port", guest: 80, host: 9080
  config.vm.network "forwarded_port", guest: 443, host: 9443
end
}}}

Note that all commands below assume that your working directory is the root of the server bundle.

First boot your virtual machine.  This command will install the machine if it does not yet exist, or will boot it if it's powered off:

{{{
vagrant up
}}}

You should now be able to SSH into the machine with:

{{{
vagrant ssh
}}}

With that all working, you're ready to test a deployment.  The virtual machine behaves like a normal server in all respects; the only "odd" thing about it is that certain ports may be different than usual.  This is to avoid conflicts between the "host" (your) machine and the "guest" (virtual) machine.

Since Vagrant will establish a 'vagrant' user within the virtual machine which has full (and password-less) sudo privileges, it is recommended to connect as this user as opposed to whichever user account you might normally use on your network.  Since we're still just using SSH here, but the details will differ (from your normal routine, but potentially between virtual machines also), you should ask Vagrant to tell you the details:

{{{
(myfab)lance@control:~/src/rattail-fabdemo/servers/host$ vagrant ssh-config
Host default
  HostName 127.0.0.1
  User vagrant
  Port 2222
  IdentityFile /home/lance/src/rattail-fabdemo/servers/host/.vagrant/machines/default/virtualbox/private_key
  <.. more elided ..>
}}}

All the irrelevant parts have been snipped from the output shown above.  What is shown ''is'' necessary however, in order to craft the proper arguments for your Fabric commands.  Here then follows the canonical example, given the above connection details.

First of all, for contrast, here is what our bootstrap command might normally look like (i.e. when used "live" instead of with Vagrant), assuming certain conventions:

{{{
fab -R live bootstrap_all
}}}

Now here is the command we must use based on the particulars of this virtual machine, as reported by Vagrant:

{{{
fab -H localhost --port 2222 -u vagrant -i .vagrant/machines/default/virtualbox/private_key bootstrap_all
}}}