Savadur Quick Start
                            -------------------

Savadur is a light build bot for triggering a build when commits are
done and to schedule periodical builds.

It's a client-server based application. The normal way to use it is to
have a server that deliver orders to build-slave clients. But having only
one client is also supported. In client-server mode all XML configuration
files are automatically deployed from the server to the clients.

It's SCM agnostic. Savadur does not know anything about Subversion,
CVS or Git. But it is very easy to teach him how to interact with a new
SCM. Savadur come with Git and Subversion support.



Quick start
===========

We want to run a client and server on the same machine.

   $ export SAVADUR_DIR=$HOME/opt/savadur/savadurdir

   $ make && make INSTALL=$SAVADUR_DIR/.. install

Server
------

   $ cd $SAVADUR_DIR/server
   $ ./scripts/create_database.sh

We allow a single client named "builder" which can run the default, check and
try_patch scenarii:

   $ cat <<EOF > config/project_list.xml
   <project_list>
        <project id="v2p" log_size="50">
                <scenario id="default">
                        <client key="builder"/>
                </scenario>
                <scenario id="check">
                        <client key="builder"/>
                </scenario>
                <scenario id="try_patch">
                        <client key="builder"/>
                </scenario>
        </project>
   </project_list>

The server will run on port 8181:

   $ ./savadur --server --config  --id server --endpoint http://localhost:8181

Then we setup a projet (savadur itself in this example):

   $ cat <<EOF > projects/savadur.xml
   <project>
     <name id="savadur" />
     <scm id="git" />

     <variable id="url"
        value="http://repo.or.cz/r/savadur.git" />

     <action id="make">
       <cmd>make setup all</cmd>
     </action>

     <action id="regtests">
       <cmd>make regtests</cmd>
     </action>

     <scenario id="default">
       <scm_action id="version" status="require_change" on_error="quit" />
       <scm_action id="pull" />
       <action id="make" />
       <action id="regtests" />
     </scenario>

     <scenario id="check" periodic="03:00/+60">
       <scm_action id="version" status="require_change" on_error="quit" />
       <scm_action id="pull" />
       <action id="make" />
       <action id="regtests" />
     </scenario>

     <scenario id="try_patch" patch_file="true" use_tmp="true">
       <scm_action id="pull" />
       <scm_action id="apply" />
       <action id="make" />
     </scenario>
   </project>

Run the server:

   $ ./savadur --server

Client
------

Set the client endpoint (named "builder" as descrived on the server side):

   $ ./savadur --client --config --id builder --endpoint http://localhost:8282

Add reference for the remote server we have configured just above:

   $ ./savadur --client --remote --add localhost http://localhost:8181

Run the client:

   $ ./savadur --client



Advanced Configuration
======================

SCM
---

Adding support for git is simple as adding a file scm/git.xml in the server
savadur directory. Note that the specific action named "init" is mandatory
and is expected to retreive the sources from the given SCM. If present the
version action must return a single id representing the current HEAD
revision number.

   $ cat scm/git.xml

   <scm>
     <name id="git" />
     <filter id="files_updated" regexp=" ([^\n]*) *\|  "/>

     <action id="init">
       <cmd>git clone $url $sources</cmd>
     </action>

     <action id="pull">
       <cmd filter1="files_updated">git pull</cmd>
     </action>

     <action id="version" result="value">
       <cmd regexp="^([^\t]*)">git ls-remote origin refs/heads/master</cmd>
     </action>
   </scm>

Project
-------

The project file savadur.xml:

   <project>
     <name id="savadur" />
     <scm id="git" />

     <variable id="url"
        value="http://repo.or.cz/r/savadur.git" />

     <action id="make">
       <cmd>make setup all</cmd>
     </action>

     <action id="regtests">
       <cmd>make regtests</cmd>
     </action>

     <scenario id="default">
       <scm_action id="version" status="require_change" on_error="quit" />
       <scm_action id="pull" />
       <action id="make" />
       <action id="regtests" />
     </scenario>

     <scenario id="check" periodic="03:00/+60">
       <scm_action id="version" status="require_change" on_error="quit" />
       <scm_action id="pull" />
       <action id="make" />
       <action id="regtests" />
     </scenario>

     <scenario id="try_patch" patch_file="true" use_tmp="true">
       <scm_action id="pull" />
       <scm_action id="apply" />
       <action id="make" />
     </scenario>
   </project>

This project file describes:

 - The project name "savadur",

 - The scm type "git", all scm_action will reference actions in the
   SCM xml file (here savadurdir/server/scm/git.xml),

-  The repository URL (referenced into the SCM as $url),

 - The action list. For this small project only two actions : make and
   regtests,

 - The scenario list. We have defined three scenarios:

       * The "default" scenario, referencing four actions. The
         scm_action "version" is a special action that requires
         changes (we want to compile only if there is a new commit)
         and quit the build process if no change.

       * The "check" scenario which is run at 03:00 and every 60 minutes.

       * The "try_patch" scenario using a temporary directory and
         applying the patch file uploaded by the developer.

Remote Servers
--------------

On the client side (found in client/server/*.xml), the remote server
configuration is:

<server>
   <name value="builder"/>
   <location urt="http://localhost:8181"/>
   <log_path value="/home/savadur/logs"/>
   <log_prefix value="builder_"/>
   <send_log value="true"/>
</server>

Where:

   - log_path is the directory where all client's logs will be written.

   - log_prefix is the string prepended to the log filename. The filename
     will be <log_path>/<action_id>-<log_prefix><action_name>

   - send_log if true the log content is sent to the server. If false the
     log file is kept on the client side but not sent to the server. It is
     true by default.

Note that on the server side the logs are only kept into the database.

Environment
-----------

It is possible to set some specific environment variables by adding an XML
document into "env/<project>.xml" on the client side. The syntax of this
document is simple:

   <?xml version="1.0" encoding="utf-8"?>
   <environment_variables>
     <var name="PATH" value="/opt/gnat/2009/bin:/usr/bin" mode="append" />
   </environment_variables>

where mode can be:

   append   : add the corresponding value at the end of the variable
   replace  : replace the variable with the given value
   clear    : clear the variable

Trigger a build
---------------

To trigger a build it is possible to send a simple HTTP request to the server
for a specific project and scenario.

   $ wget --no-proxy \
          http://<server>:<port>/run?p=<project>\&s=<scenario>\&l=<latency>

     <project>  : the project name
     <scenario> : the specific scenario to run
     <latency>  : seconds to wait before launching the run

Following the example above:

   $ wget --no-proxy \
     http://my_server_machine.my_company.com:8181/run?p=savadur\&s=default

Notifications
-------------

XMPP and SMTP notifications can be activated on the server side using an
XML document named notify.xml. This document is used to configure the SMTP
and/or the Jabber server.

For XMPP:

   <notifications>
     <jabber>
       <server value="jabber.org" />
       <jid value="savadur-bot" />
       <password value="savadur_pwd" />
     </jabber>
     <smtp>
       <server value="smtp.example.com"/>
       <sender value="savadur@here.com"/>
       <user value="savadur@here.com"/>
       <password value="secret_smtp_pwd"/>
     </smtp>
   </notifications>

For SMTP, user and password are optional.

For now only PLAIN authentication is supported for SMTP.

The actual E-Mail or Jabber addresses recipients of the notifications are set
on the server's database using the correspondong Web forms.

Committers e-mail
-----------------

In some case there is no direct association between the committer name and
the commiter e-mail. In Subversion using HTTP protocole, for example, the
committer e-mail cannot be determined from the name found in the log.

To work around this problem an XML file containing the proper associations
can be placed on the server side.

   <committers>
     <set name="obry" value="pascal@obry.net"/>
     <set name="ramonat" value="olivier@ramonat.fr"/>
     <set name="*" value="@mydomain.com"/>
   </committers>

The last association is a catch-all one. For all name not listed the specified
domain is appended to form the e-mail.