Vagrant

This repository contains a working Vagrant configuration (directory vagrant), which you can use to initialize a virtual machine to test applications in an isolated environment. It's a good idea to use if you want to avoid polluting your OS with services used by different applications.

Instructions

To boot up a Vagrant-managed virtual machine, simply do the following:

1. Install Vagrant and VirtualBox
2. Download this repository
3. Navigate into this repository's vagrant directory
4. Drop your pre-seeded keys there (the ones the admin gave you)
5. Set up your minion file (see below)
6. Run vagrant up
7. Go to localhost:10080 and check that the app is running (see below)

Before Vagrant Up

Before step 6, you should have the following files in salt-config/vagrant:

• Vagrantfile: main Vagrant virtual box configuration
• minion: configuration for the minion
• key.pem: private key
• key.pub: public key

If you're missing any of those, review the steps above again.

Stopping the VM

To stop the virtual box:

vagrant halt

To remove (delete) your virtual box:

vagrant destroy

Note that removing it will not delete your downloaded OS image, so starting a new one will be a lot faster from now on.

Details and Customizations

If you'd like to know how all this is accomplished with only four files (or if that didn't work for you) read on.

Minion File Configuration

When provisioning a virtual box, Vagrant will look for the Minion configuration in a file named minion (option salt.minion_config in the Vagrantfile), which you need to create from scratch. Just kidding: copy the minion.example as minion, set your minion id in there (which the admin gave you with the keys) and you're done.

Really, there's no point in changing anything right now because we have a single app. Well, you could change the env to prod if you wanted to use your local PostgreSQL instead of SQLite...

Host-Guest Communication

When running Vagrant, your guest (virtual machine) will not be isolated from your host (real machine): Vagrant will forward a few ports and synchronize filesystem directories.

The ones done by Vagrant automatically:

• host :2222 -> guest :22 (SSH)
• host current dir -> /vagrant

The ones added by our configuration (the Vagrantfile):

• host :10080 -> guest :80 (HTTP)
• host two levels above current dir -> /home/vagrant/apps

You can also ssh into the guest machine by running:

vagrant ssh

Highstate

The option salt.run_highstate in the Vagrantfile instructs vagrant to communicate with the Salt Master and run all the states required for this Minion. This will install all the software and execute all the commands required to have the application up and running. If you don't want this (???), you can disable it by setting it to false or commenting it out.

Repository Pulling

During the highstate, your Minion will try to checkout the repository of the application into your guest's /home/vagrant/apps, so that might add a new repository to your local filesystem (remember that the directories are synchronized!)

However, it's a rather safe operation since it will only checkout if there is no directory with the same name, or if the directory is the same repository and it's clean (ie, it has no uncommitted changes).

Maybe an example will help understand that. Imagine that I have the following structure:

/home/kako/dev/projects/
  salt-config/
    vagrant/ > current working directory for vagrant
    ...
  some-repo/
    ...
  another-repo/
    ...
/home/kako/dev/libs
  ...

In that case, it will pull the repository into /home/kako/dev/projects, because there's no directory there with that name.

But if I have a directory with the same name but it is not the same repository:

/home/kako/dev/projects/
  salt-config/
    vagrant/ > current working directory for vagrant
    ...
  some-repo/
    ...
  pjtracker/ > random directory that is not the same repo
    ...

It won't pull it. Which, in turn, will disable all the states that need that repository, so the application will not start either. So if it didn't and you were wondering why, that's a possible reason, but salt will let you know why a state failed.