Configuring Integral

So now you’ve got Integral installed, what do you do? Well, you need to do a couple of things. You can do them in any order, but you’ll want to step through each of the following tasks:

1. Setting up config.yml
2. Add applications to the database
3. Write some integration tests

Setting up config.yml

The default config file looks like this:

servers:
  test: staging.mydomain
  live: live.mydomain

version_command: ssh $hostname cat $path/REVISION

Set the hostnames of your test and live servers. If you deploy to multiple live servers simultaneously you only need to list one of them in the config file.

The version_command is used to determine the current version of an application on either the test or live servers. The $hostname and $path variables are substituted with either the test/live server’s hostname and the application’s path (which you’ll be setting up below). You can run any command you like to determine an application’s version number, but at the time of writing only $hostname and $path are substituted within version_command. If you use the default (which works nicely with Rails) it obviously pays to configure ssh to allow you to login without continuously re-entering your password.

Add Applications to the Database

As we saw in the previous section, Integral needs to know how to work out which version of each application is installed on your test and live servers. By default it runs an ssh command that returns the contents of a file called REVISION within each application’s directory. You set each application’s directory when you add it to the database. In this example, the REVISION file would live at /path/to/myapp/REVISION:

Note that when you deploy a Rails application with Capistrano you automatically get a REVISION file at /var/apps/myapp/current/REVISION.

Repeat the app:add task until you’ve added all your applications. You can review your progress like so:

If you make an error when adding an application you can remove it with the app:remove task and re-add it, but note that once you’ve got test runs stored in the database it’s best not to remove an application as you’ll lose history associated with it (deactivate apps instead if you no longer want to record their presence when running tests).

It’s worth noting that you’ve got a Rails like console available to you as well, so you can tweak the contents of the database using ActiveRecord (the model classes are all defined in database.rb):

Write Some Integration Tests

All you have to do here is to launch your test script from the integrate.rb file. If your tests fail the integrate.rb file should exit with a non-zero exit code, otherwise Integral will record the test run as a success.

Now you’re on to the last step – how to go about Running Your Tests.