Getting Started

Dear build monkey master artist,

We created CruiseControl.rb so that you can kick ass.

We want you to have basic continuous integration up and running 10 minutes after reading this page. After that, we want you to find that the tool looks good, does what you expect, and basically just works. Finally, when you need to do something unusual, we want you to be surprised by how easy that was, too.

In short, we want you to love CruiseControl.rb.

Very truly yours,

CruiseControl.rb team
ThoughtWorks

P.S. We also want to know if we somehow fall short of these goals.

Basics

CruiseControl.rb has two parts: a builder and a dashboard.

Builder is a daemon process that polls source control every once in a while for new revisions.

When someone performs a check in, the builder:

  1. detects it
  2. updates its own copy of the project
  3. runs the build
  4. notifies interested parties about the build’s outcome

Dashboard is a web application that helps to monitor the status of project builds and troubleshoot failures.

Each installation of CruiseControl.rb may have multiple projects and multiple builders (one per project). There may also be multiple installations of CruiseControl.rb per computer.

Prerequisites

Assumptions and limitations

Installation

Follow these directions or watch our 5 minute install screencast.

1. Download and unpack CruiseControl.rb

Below, we will refer to the place where you unpack it as [cruise]

2. From [cruise], run ./cruise add your_project --url [URL of your_project Subversion trunk].

Optionally, you can specify username and password by adding --username [your_user] --password [your_password] to the command

This creates a $HOME/.cruise directory (%USERPROFILE%\.cruise if you are on Windows), and that is where CruiseControl.rb keeps its data, and then checks out your_project from the subversion URL you provided to $HOME/.cruise/projects/your_project/work/.

Documentation refers to $HOME/.cruise/ as [cruise data].

Hint: Rakefile of your_project should be in [cruise data]/projects/your_project/work/ directory, not anywhere under it. A common mistake is to specify in --url option the root of project’s SVN repository instead of the trunk. Rakefile then ends up in [cruise data]/projects/your_project/work/trunk/ and CruiseControl.rb does not see it there.

3. From [cruise], run ./cruise start.

Hint: This starts CruiseControl.rb dashboard and builder(s). By default, the dashboard is bound to port 3333, if you want to run your server on a different port, just type ./cruise start -p [port]

4. Browse to http://localhost:3333.

All going well, weather permitting, you will see a page with CruiseControl.rb logo. This is the dashboard, and it should display your project. If it’s passing, you’re done – though you should double check that it’s doing what it should be by clicking on the project name and looking at the build log for the last build. If it’s failing or otherwise misbehaving, go on to step 5.

5. Go to [cruise data]/projects/your_project/work/ and make the build pass.

For a regular Rails app, this involves creating a test database, editing database.yml to connect to that database, performing rake RAILS_ENV=test db:migrate, running rake test and making sure that it passes.

6. Press the “build now” button on the Dashboard to rebuild your project

This should build your_project and place build outputs into [cruise data]/projects/your_project/build-[revision-number]/

Hint: Monitor log/your_project_builder.log for any signs of trouble. Try to check in a change to your_project and see if the builder can detect and build it. Check your_project status in the dashboard.

Hint: ./cruise help displays a list of commands, ./cruise help [command] displays options available for each command.

Next step: read the manual