doc/README

   1
   2                             Savadur Quick Start
   3                             -------------------
   4
   5 Savadur is a light build bot for triggering a build when commits are
   6 done and to schedule periodical builds.
   7
   8 It's a client-server based application. The normal way to use it is to
   9 have a server that deliver orders to build-slave clients. But having only
  10 one client is also supported. In client-server mode all XML configuration
  11 files are automatically deployed from the server to the clients.
  12
  13 It's SCM agnostic. Savadur does not know anything about Subversion,
  14 CVS or Git. But it is very easy to teach him how to interact with a new
  15 SCM. Savadur come with Git and Subversion support.
  16
  17
  18
  19 Quick start
  20 ===========
  21
  22 We want to run a client and server on the same machine.
  23
  24    $ export SAVADUR_DIR=$HOME/opt/savadur/savadurdir
  25
  26    $ make && make INSTALL=$SAVADUR_DIR/.. install
  27
  28 Server
  29 ------
  30
  31    $ cd $SAVADUR_DIR/server
  32    $ ./scripts/create_database.sh
  33
  34 We allow a single client named "builder" which can run the default, check and
  35 try_patch scenarii:
  36
  37    $ cat <<EOF > config/project_list.xml
  38    <project_list>
  39         <project id="v2p" log_size="50">
  40                 <scenario id="default">
  41                         <client key="builder"/>
  42                 </scenario>
  43                 <scenario id="check">
  44                         <client key="builder"/>
  45                 </scenario>
  46                 <scenario id="try_patch">
  47                         <client key="builder"/>
  48                 </scenario>
  49         </project>
  50    </project_list>
  51
  52 The server will run on port 8181:
  53
  54    $ ./savadur --server --config  --id server --endpoint http://localhost:8181
  55
  56 Then we setup a projet (savadur itself in this example):
  57
  58    $ cat <<EOF > projects/savadur.xml
  59    <project>
  60      <name id="savadur" />
  61      <scm id="git" />
  62
  63      <variable id="url"
  64         value="http://repo.or.cz/r/savadur.git" />
  65
  66      <action id="make">
  67        <cmd>make setup all</cmd>
  68      </action>
  69
  70      <action id="regtests">
  71        <cmd>make regtests</cmd>
  72      </action>
  73
  74      <scenario id="default">
  75        <scm_action id="version" status="require_change" on_error="quit" />
  76        <scm_action id="pull" />
  77        <action id="make" />
  78        <action id="regtests" />
  79      </scenario>
  80
  81      <scenario id="check" periodic="03:00/+60">
  82        <scm_action id="version" status="require_change" on_error="quit" />
  83        <scm_action id="pull" />
  84        <action id="make" />
  85        <action id="regtests" />
  86      </scenario>
  87
  88      <scenario id="try_patch" patch_file="true" use_tmp="true">
  89        <scm_action id="pull" />
  90        <scm_action id="apply" />
  91        <action id="make" />
  92      </scenario>
  93    </project>
  94
  95 Run the server:
  96
  97    $ ./savadur --server
  98
  99 Client
 100 ------
 101
 102 Set the client endpoint (named "builder" as descrived on the server side):
 103
 104    $ ./savadur --client --config --id builder --endpoint http://localhost:8282
 105
 106 Add reference for the remote server we have configured just above:
 107
 108    $ ./savadur --client --remote --add localhost http://localhost:8181
 109
 110 Run the client:
 111
 112    $ ./savadur --client
 113
 114
 115
 116 Advanced Configuration
 117 ======================
 118
 119 SCM
 120 ---
 121
 122 Adding support for git is simple as adding a file scm/git.xml in the server
 123 savadur directory. Note that the specific action named "init" is mandatory
 124 and is expected to retreive the sources from the given SCM. If present the
 125 version action must return a single id representing the current HEAD
 126 revision number.
 127
 128    $ cat scm/git.xml
 129
 130    <scm>
 131      <name id="git" />
 132      <filter id="files_updated" regexp=" ([^\n]*) *\|  "/>
 133
 134      <action id="init">
 135        <cmd>git clone $url $sources</cmd>
 136      </action>
 137
 138      <action id="pull">
 139        <cmd filter1="files_updated">git pull</cmd>
 140      </action>
 141
 142      <action id="version" result="value">
 143        <cmd regexp="^([^\t]*)">git ls-remote origin refs/heads/master</cmd>
 144      </action>
 145    </scm>
 146
 147 Project
 148 -------
 149
 150 The project file savadur.xml:
 151
 152    <project>
 153      <name id="savadur" />
 154      <scm id="git" />
 155
 156      <variable id="url"
 157         value="http://repo.or.cz/r/savadur.git" />
 158
 159      <action id="make">
 160        <cmd>make setup all</cmd>
 161      </action>
 162
 163      <action id="regtests">
 164        <cmd>make regtests</cmd>
 165      </action>
 166
 167      <scenario id="default">
 168        <scm_action id="version" status="require_change" on_error="quit" />
 169        <scm_action id="pull" />
 170        <action id="make" />
 171        <action id="regtests" />
 172      </scenario>
 173
 174      <scenario id="check" periodic="03:00/+60">
 175        <scm_action id="version" status="require_change" on_error="quit" />
 176        <scm_action id="pull" />
 177        <action id="make" />
 178        <action id="regtests" />
 179      </scenario>
 180
 181      <scenario id="try_patch" patch_file="true" use_tmp="true">
 182        <scm_action id="pull" />
 183        <scm_action id="apply" />
 184        <action id="make" />
 185      </scenario>
 186    </project>
 187
 188 This project file describes:
 189
 190  - The project name "savadur",
 191
 192  - The scm type "git", all scm_action will reference actions in the
 193    SCM xml file (here savadurdir/server/scm/git.xml),
 194
 195 -  The repository URL (referenced into the SCM as $url),
 196
 197  - The action list. For this small project only two actions : make and
 198    regtests,
 199
 200  - The scenario list. We have defined three scenarios:
 201
 202        * The "default" scenario, referencing four actions. The
 203          scm_action "version" is a special action that requires
 204          changes (we want to compile only if there is a new commit)
 205          and quit the build process if no change.
 206
 207        * The "check" scenario which is run at 03:00 and every 60 minutes.
 208
 209        * The "try_patch" scenario using a temporary directory and
 210          applying the patch file uploaded by the developer.
 211
 212 Remote Servers
 213 --------------
 214
 215 On the client side (found in client/server/*.xml), the remote server
 216 configuration is:
 217
 218 <server>
 219    <name value="builder"/>
 220    <location urt="http://localhost:8181"/>
 221    <log_path value="/home/savadur/logs"/>
 222    <log_prefix value="builder_"/>
 223    <send_log value="true"/>
 224 </server>
 225
 226 Where:
 227
 228    - log_path is the directory where all client's logs will be written.
 229
 230    - log_prefix is the string prepended to the log filename. The filename
 231      will be <log_path>/<action_id>-<log_prefix><action_name>
 232
 233    - send_log if true the log content is sent to the server. If false the
 234      log file is kept on the client side but not sent to the server. It is
 235      true by default.
 236
 237 Note that on the server side the logs are only kept into the database.
 238
 239 Environment
 240 -----------
 241
 242 It is possible to set some specific environment variables by adding an XML
 243 document into "env/<project>.xml" on the client side. The syntax of this
 244 document is simple:
 245
 246    <?xml version="1.0" encoding="utf-8"?>
 247    <environment_variables>
 248      <var name="PATH" value="/opt/gnat/2009/bin:/usr/bin" mode="append" />
 249    </environment_variables>
 250
 251 where mode can be:
 252
 253    append   : add the corresponding value at the end of the variable
 254    replace  : replace the variable with the given value
 255    clear    : clear the variable
 256
 257 Trigger a build
 258 ---------------
 259
 260 To trigger a build it is possible to send a simple HTTP request to the server
 261 for a specific project and scenario.
 262
 263    $ wget --no-proxy \
 264           http://<server>:<port>/run?p=<project>\&s=<scenario>\&l=<latency>
 265
 266      <project>  : the project name
 267      <scenario> : the specific scenario to run
 268      <latency>  : seconds to wait before launching the run
 269
 270 Following the example above:
 271
 272    $ wget --no-proxy \
 273      http://my_server_machine.my_company.com:8181/run?p=savadur\&s=default
 274
 275 Notifications
 276 -------------
 277
 278 XMPP and SMTP notifications can be activated on the server side using an
 279 XML document named notify.xml. This document is used to configure the SMTP
 280 and/or the Jabber server.
 281
 282 For XMPP:
 283
 284    <notifications>
 285      <jabber>
 286        <server value="jabber.org" />
 287        <jid value="savadur-bot" />
 288        <password value="savadur_pwd" />
 289      </jabber>
 290      <smtp>
 291        <server value="smtp.example.com"/>
 292        <sender value="savadur@here.com"/>
 293        <user value="savadur@here.com"/>
 294        <password value="secret_smtp_pwd"/>
 295      </smtp>
 296    </notifications>
 297
 298 For SMTP, user and password are optional.
 299
 300 For now only PLAIN authentication is supported for SMTP.
 301
 302 The actual E-Mail or Jabber addresses recipients of the notifications are set
 303 on the server's database using the correspondong Web forms.
 304
 305 Committers e-mail
 306 -----------------
 307
 308 In some case there is no direct association between the committer name and
 309 the commiter e-mail. In Subversion using HTTP protocole, for example, the
 310 committer e-mail cannot be determined from the name found in the log.
 311
 312 To work around this problem an XML file containing the proper associations
 313 can be placed on the server side.
 314
 315    <committers>
 316      <set name="obry" value="pascal@obry.net"/>
 317      <set name="ramonat" value="olivier@ramonat.fr"/>
 318      <set name="*" value="@mydomain.com"/>
 319    </committers>
 320
 321 The last association is a catch-all one. For all name not listed the specified
 322 domain is appended to form the e-mail.