BuildbotSlaveHowto.mdwn

   1 *How to set up a BuildBot Slave for OpenAFS*
   2
   3 _Rationale_
   4
   5 Why would I want to?  OpenAFS supports multiple platforms, but the strength of support for
   6 each of those individual platforms is directly proportional to the amount of testing done thereon.
   7 Although there are many different types of testing that can be done, one of the most basic is
   8 that of changes to the code base.  A BuildBot slave allows for automated testing of each gerrit
   9 commit and is therefore a great resource to developers, most of whom do not have the time or
  10 resources to test their code on every platform prior to submission.  Therefore, we encourage you
  11 to contribute a system as a build slave for a platform not already covered!  You know you want to!
  12
  13 _Approach_
  14
  15 This is a consumer-oriented, high-level "how-to" to (hopefully) show how simple it is to set up
  16 your own build slave (and thereby contribute to OpenAFS!).  This document is not intended to be
  17 platform-specific -- there are just too many different ways of doing things across
  18 Linux/Windows/SunOS/IRIX/AIX/BSD etc.  There are additional notes elsewhere on this Wiki
  19 (see: [[BuildbotMasterNotes]]) about setting up the BuildBot Master, and some of this material
  20 is covered there as well -- however, this page is an attempt to make the process more understandable
  21 (specifically the buildslave setup).
  22
  23 _Overview_
  24
  25 A quick overview of the process:
  26
  27 1. Acquire suitable system
  28 1. Install required software
  29 1. Compile OpenAFS from git
  30 1. Create buildbot account and home directory
  31 1. Contact OpenAFS BuildBot admin for configuration details
  32 1. Edit configuration files
  33 1. Start build slave
  34 1. Set up startup scripts
  35 1. Optional configuration
  36
  37 *Of note:* since BuildBot slaves pull all their information from the master (rather than having it pushed
  38 to them by the master), there is no need to open an incoming port on your firewall, etc.  As long as the
  39 slave can contact the master on the port you're given (which will be explained later), you're good to go!
  40
  41 _Hardware Requirements_
  42
  43 * Any system which OpenAFS currently supports (the greater diversity of build slaves, the better)
  44 * Enough free disk space to build OpenAFS tree (a couple gigabytes should do)
  45
  46 The machine does not necessarily need to be dedicated entirely to being a buildslave; a build slave
  47 could run on any lightly-loaded, non-critical system (subject to your security requirements, etc.,
  48 of course).  Some of the OpenAFS buildslaves are run by volunteers at their own homes, for instance.
  49
  50 If you happen to have an older system with multiple processors, you can run more than one build slave
  51 instance on the same machine.  The workload will be distributed across them by the master: successive
  52 gerrit commit builds are started on the next free instance, thus reducing the overall time to
  53 test multiple commits.
  54
  55 _Software Requirements_
  56
  57 BuildBot has the following software dependencies:
  58
  59 * Python: [[http://www.python.org/]]
  60 * Twisted: [[http://twistedmatrix.com/]]
  61 * ZopeInterface: [[http://www.zope.org/Products/ZopeInterface]]
  62 * Git: [[http://git-scm.com/]]
  63
  64 Links to the above software websites are provided for reference only -- you may very well have a more
  65 convenient method for installing software on your platform than downloading the source, building,
  66 and installing by hand.  Check public software repositories for your platform first to save yourself some
  67 effort.  BuildBot is not particularly sensitive to dependency versioning, so you may not need the
  68 absolute latest version of everything installed.  (For instance, BuildBot 0.7.12 is known to work with Python 2.5.2,
  69 Git 1.7.9, ZopeInterface 3.3.0, Twisted 9.0.0.)
  70
  71 Git version 1.7.9 or above is required.   The "git clean -e" option must be present and the
  72 "git clean -X -e excluded-file" behavior must be correct.
  73
  74 And, of course, you'll need to install BuildBot itself: [[http://buildbot.net/trac]]
  75
  76
  77 _Compile OpenAFS from git_
  78
  79 Use git to clone the openafs repo, then make sure the software will compile successfully. For Unix platforms, the typical build process is
  80 "sh regen.sh && ./configure && make && make dest"
  81 The actual buildbot builds will configure using the --enable-checking argument
  82 to configure (as well as several others); this activates more compiler errors
  83 and you will probably want to do manual builds with checking enabled, to
  84 fix any build errors encountered before the buildslave enters regular use.
  85
  86 _Create buildbot account and home directory_
  87
  88 It is recommended that you use a special-purpose non-priviledged user account to run the build slave
  89 (i.e., "buildbot").  The build master does not need to know the account's password -- in fact, the
  90 account does not necessarily need remote login priviledges and may be locked or otherwise secured
  91 as long as your platform still allows you to run commands as that user.
  92
  93 Test that you can run the buildbot command successfully (without error messages that might indicate
  94 installation issues): /path/to/buildbot
  95
  96 _Contact OpenAFS BuildBot Master admin for configuration details_
  97
  98 Contact jason at rampaginggeek.com regarding the settings you'll
  99 need to add your machine as an OpenAFS build slave.  These settings will include:
 100
 101 * buildmaster_host: this is the OpenAFS build master
 102 * port: this is the port on the build master which your slave will talk to
 103 * slavename: a unique descriptive name for your new build slave, usually representing your operating system and architecture (and not necessarily anything to do with your systems' hostname)
 104 * passwd: a password assigned to your slave for use in connecting with the master
 105
 106 _Create your build slave configuration_
 107
 108 As your buildbot user:
 109
 110 Inside the user's home directory (say, /home/buildbot), create a subdirectory which will contain all of the buildslave files (say, /home/buildbot/slave1).
 111 Buildbot will not touch anything outside of this directory.
 112
 113 Substituting the appropriate values from above, the execute:
 114
 115 /path/to/buildbot create-slave /home/buildbot/slave1 buildmaster_host:port slavename passwd
 116
 117 Starting with buildbot version 0.8, the command-line tool was split into
 118 buildbot and buildslave, so the buildslave utility should be used with such
 119 newer buildbot versions.
 120
 121 Check the configuration file /home/buildbot/slave1/buildbot.tac to make sure the settings you entered are reflected in it.
 122 Make sure that "usepty" is set to "0". "usepty = 1" it is known to fail on at least one architecture.
 123
 124 *Optional, but recommended:* Edit the /home/buildbot/slave1/info/{admin,host} files to describe the system (in host) and send
 125 yourself a shout-out (tell who you are in admin).  These show up on the web if you drill down to the build slave information
 126 on the OpenAFS buildbot web portal, so you may want to obfuscate your contact information.
 127
 128 *Note:* if you are planning on running multiple OpenAFS buildslave instances, you simply repeat this and all later steps,
 129 specifying a different base directory (i.e., /home/buildbot/slave2, /home/buildbot/slave3, etc.)
 130
 131 _Start build slave_
 132
 133 /path/to/buildbot start
 134
 135 Check the logs to make sure it started properly.  Check the OpenAFS BuildBot web portal to see the build progress presented
 136 graphically.
 137
 138 There may be some kinks to work out of the system with the first few builds, especially if you are contributing a slave system
 139 for a less-heavily-used platform whose support might suffer from bit rot between releases (hey, it happens!).
 140
 141 _Set up startup scripts_
 142
 143 Self-explanatory.  Make sure they run /path/to/buildbot start as your buildbot user.
 144
 145 _Set up log rotation and various other useful settings_
 146
 147 The buildbot.tac configuration file can be used to optimize your build slave.  For instance, you may want to change maxRotatedFiles
 148 so you don't end up with a bunch of logs littered about /home/buildbot/slave1/.  Have a look at the BuildBot documentation if
 149 you wish, though you can expect to be able to take a fairly hands-off approach to administering your new OpenAFS build slave.
 150
 151 Link to current BuildBot documentation: [[http://buildbot.net/buildbot/docs/current/]]
 152
 153 Thanks for your help!
 154