Project Configuration

Added by Jon Tirsen, last edited by Jon Tirsen on Sep 29, 2004  (view change)

h2 How to set up DamageControl to work with your project
This page explains how to make a particular project DamageControlled. You'll be surprised how easy it is. (If your project is not on Codehaus, you should also get a geek to set up the DamageControl server for you).

These are the basic steps:

  1. Install the DamageControl trigger into your source management system (if you are using triggering).
  2. Set up polling for you source management system (if you are using polling).
  3. Configure the options for your project.

If you need help, ask on the mailing lists or the irc channel, see Contacting the project.

If you have a feature request or bug report, report them here: http://jira.codehaus.org/secure/BrowseProject.jspa?id=10260. Patches are always welcome, preferrably in unified diff format.

Installing the DamageControl trigger into your SCM

Manually installing DamageControl into CVS

This section explains how to DamageControl a CVS module.

A CVS module is DamageControlled by configuring the CVS repository to fire an event (over XML/RPC) to the DamageControl server. This is done by editing some files in the CVSROOT module.

Install DamageControl on the source control server

Refer to Subversion Access for more instructions.

Check out CVSROOT

First check out the CVSROOT of your project.

cvs -d<cvsroot to your repository> checkout CVSROOT

Install the trigger

Add the following line to CVSROOT/loginfo.

<name of module> <path to your DamageControl installation>/bin/requestbuild(.cmd) --url http://your-damagecontrol-host:4712/private/xmlrpc --projectname <name of project>

Explanation:

  • The first token <name of module> is the name of the CVS module for which you want to enable DC builds.
  • The rest of the line is an invocation to a script in your DamageControl installation. Append .cmd to the script if on Windows, otherwise leave it out.
  • The url to your DamageControl server is usually http://localhost:4712/private/xmlrpc if running on the same host as your source control system.
  • The projectname should be exactly the same project name you used to configure your project in DamageControl (yes, it is sensitive to case).
  • This will override any DEFAULT line you may have, so you might want to consider using ALL for other entries.

Test it!

Do a test commit. It should start the build and print out something like the following:

Trigging build of ProjectName DamageControl on http://localhost:4712/private/xmlrpc
Monitor build results at:
http://localhost:4712/public/project?project_name=#{project_name}

Installing DamageControl trigger into Subversion

TODO
Basically follow something like the above procedure. But instead of checking out CVSROOT put the invocation to requestbuild(.cmd) into <subversion repo root>/hooks/post-commit(.bat) on the server where Subversion was installed.

(NEW!) Centralised configuration

There is a new way of storing configuration files for DamageControl. This explains how this work.

Create a Configuration file

The new centralised configuration is a lot easier to administrate. To configure your project you need to access to the DamageControl server to be able to create the configuration files necessary.

Create a file in <damagecontrol config root>/<project name> named conf.yaml }}. {{<damagecontrol config root> is the root you specify when starting DamageControl, on Codehaus this is ~dcontrol/build.

(In the rest of these instructions, xxx means the name of your CVS module. Ex: foo or foo/bar).

Specify the information that the DamageControl server will need in order to build your code and notify you:

project_name: Foo
scm_spec: ":ext:dcontrol@cvs.codehaus.org:/cvsroot/blah:foo"
build_command_line: "maven clean jar:deploy site:deploy"
nag_email: foo-dev@lists.codehaus.org
  • project_name is the unique name of your project and should be the same as the name of the directory where you put that file. No spaces here! Makes sure it's unique by looking at http://builds.codehaus.org/logs/.
  • scm_spec is the CVS "URL" followed by a ':' and the CVS module name.
  • build_command_line is the command line that will run the build.
  • nag_email is the email address where DamageControl will notify about the build result.

Note that if you specify the :ext: protocol, the dcontrol user must be part of the project. This is to enable DamageControl to tag the CVS after a successful build. (File a Codehaus Chore if you want to add the dcontrol user to your project). Otherwise, if you don't care about DamageControl tagging your CVS, just specify :pserver:anonymous instead.

If the specified nag_email is a mailing list that allows posts from members only, you should subscribe dcontrol@builds.codehaus.org to the specified mailing list. This can be done via the mailman interface at http://lists.codehaus.org/. Make sure to tick the nomail option. If you don't know the password for your mailing list, file a Codehaus Chore in JIRA for this.

Check out CVSROOT

A CVS module is DamageControlled by configuring the CVS repository to fire an event (over TCP/IP) to the DamageControl server. This is done by editing and adding some files in the CVSROOT module.

Create triggering script

To use the following Ruby script to do the triggering you need to install ruby 1.8 and xmlrpc4r (http://www.fantasy-coders.de/ruby/xmlrpc4r/) on the client machine and install the dctrigger.rb script that triggers the server.

Create a file called dctrigger.rb in the CVSROOT with the following content:

require 'xmlrpc/client'
  
url = ARGV[0]
project_name = ARGV[1]

puts "Triggering DamageControl build to #{url} for project #{project_name}"
client = XMLRPC::Client.new2(url)
build = client.proxy("build")
result = build.trig(project_name, Time.now.utc.strftime("%Y%m%d%H%M%S"))
puts result

Add this file using cvs add.

If you want you can use any other scripting language that supports XML/RPC. The URL to call is http://beaver.codehaus.org:8080/build, the signature of the method is build.trig(String, String) where the first argument is project name, and the second argument is the timestamp that the build should work off, it must be in UTC timezone and formatted YYYYMMDDmmhhss.

Tell CVS about the trigger script

Add the name of your trigger script file to CVSROOT/checkoutlist.

dctrigger.rb

Set up loginfo to run the trigger script

The last step is to configure CVS to run the trigger script which will fire off a message over the wire when new files are committed in the CVS module you want to be DamageControlled.

Add the following line to CVSROOT/loginfo:

modulename ruby dctrigger.rb http://builds.codehaus.org:4712/private/xmlrpc projectname

Explanation:

  • The first token (modulename) is the name of the module for which you want to enable DC builds.
  • The tokens after ruby dctrigger.rb should be the url to the private (authenticated) XMLRPC server, it is as you can see an http url.
  • The last token is the name of your project, you must use the same name as you specified in your conf.yaml and as your directory name.
  • This will override any DEFAULT line you may have, so you might want to consider using ALL for other entries.
  • If you have existing entries for your module (modulename), you can add the above command at the end (separated with a ';').

Commit CVSROOT back to CVS

Add and commit all the files you modified into your CVSROOT.

That's it!

If you now try to commit files to your DamageControlled CVS module, you should see something like this on the output from your CVS client:

Checking in prump.txt;
/cvsroot/blah/foo/prump.txt,v  <--  prump.txt
new revision: 1.4; previous revision: 1.3
done
DamageControl server on 0.0.0.0/0.0.0.0 got message from eng.werken.com / 66.216.68.111

http://damagecontrol.codehaus.org/

Success, CVS operation completed

In addition to the emails you'll be getting, you can also monitor build status here:

(If your DamageControl server is running somewhere else, ask the guy who set it up where to access this information).

Setup DamageControl to poll your source management system

This is not yet supported.

Configuring the options for your project

TODO

Labels

 
(None)