devel/BuildbotWorkerHowto.mdwn

   1 # How to set up a BuildBot Worker for OpenAFS
   2
   3 ## Rationale
   4
   5 Why would I want to?  OpenAFS supports multiple platforms, but the strength of
   6 support for each of those individual platforms is directly proportional to the
   7 amount of testing done thereon.  Although there are many different types of
   8 testing that can be done, one of the most basic is that of changes to the code
   9 base.  A BuildBot worker allows for automated testing of each gerrit commit and
  10 is therefore a great resource to developers, most of whom do not have the time
  11 or resources to test their code on every platform prior to submission.
  12 Therefore, we encourage you to contribute a system as a build worker for a
  13 platform not already covered!  You know you want to!
  14
  15 ## Approach
  16
  17 This is a consumer-oriented, high-level how-to to show how simple it is to set
  18 up your own build worker.  This document is not intended to be
  19 platform-specific -- there are just too many different ways of doing things
  20 across different platforms.
  21
  22 ## Overview
  23
  24 A quick overview of the process:
  25
  26 1. Acquire suitable system which will be continuously available
  27 1. Install the required software to build OpenAFS on the worker
  28 1. Verify you are able to compile OpenAFS from a git checkout on the worker
  29 1. Contact OpenAFS BuildBot admin for worker name and password
  30 1. Install the buildbot worker and verify it starts automatically
  31
  32 Since BuildBot workers pull all their information from the master, rather than
  33 having it pushed to them by the master, there is no need to open an incoming
  34 port on your firewall.  As long as the worker can contact the master on the
  35 port you are given, you are good to go!
  36
  37 ## Hardware Requirements
  38
  39 * Any system which OpenAFS currently supports
  40 * Enough free disk space to build OpenAFS tree (a couple gigabytes should do)
  41
  42 The machine does not necessarily need to be dedicated entirely to being a build
  43 worker; a build worker could run on any lightly-loaded, non-critical system
  44 subject to your security requirements, etc., of course.  Some of the OpenAFS
  45 build workers are run by volunteers at their own homes, for instance.
  46
  47 ## Software Requirements
  48
  49 The software to build OpenAFS is platform dependent. See
  50 [[HowToBuildOpenAFSFromSource]] to install the tools to build OpenAFS.
  51
  52 You platform may already include a buildbot worker package included, otherwise
  53 use python `pip` to install the buildbot worker software and required
  54 dependencies.
  55
  56     pip install buildbot-worker
  57
  58 If you cannot or do not wish to install the buildbot into a site-wide location,
  59 you can also install it into the account's home directory or any other location
  60 using a tool like `virtualenv`.
  61
  62 ## Compile OpenAFS from git
  63
  64 Use git to clone the openafs repo, then make sure the software will compile
  65 successfully. For Unix platforms, the typical build process is:
  66
  67     git clone git://git.openafs.org/openafs.git
  68     cd openafs
  69     sh regen.sh
  70     ./configure
  71     make
  72
  73 ## Create buildbot account and home directory
  74
  75 It is recommended that you use a special-purpose non-privileged user account
  76 to run the buildbot worker.  The name 'buildbot' is commonly used as the
  77 account name to run the buildbot worker.
  78
  79 The build master does not need to know the account's password -- in fact, the
  80 account does not necessarily need remote login privileges and may be locked or
  81 otherwise secured as long as your platform still allows you to run commands as
  82 that user.
  83
  84 ## Contact OpenAFS BuildBot Master admin for configuration details
  85
  86 The buildbot admin can be contacted by making a request on the
  87 openafs-devel@openafs.org mailing list.
  88
  89 The admin will provide the following settings:
  90
  91   * A buildbot worker name
  92   * A buildbot worker password. Keep this secret.
  93
  94 ## Create your buildbot worker
  95
  96 Log in as the `buildbot` user. Create a sub directory called
  97 `/home/buildbot/openafs`.  Buildbot will not touch anything outside of this
  98 directory.
  99
 100 As the `buildbot` user, create the buildbot worker configuration with the name
 101 and password provided by the buildbot admin:
 102
 103     buildbot-worker create-worker /home/buildbot/openafs buildbot.openafs.org <NAME> <PASSWORD>
 104
 105 Edit file `openafs/info/admin` to set your name and email
 106 address. This is the worker admin address, and will be visible from the build
 107 status page, so you may wish to munge it a bit if address-harvesting spambots
 108 are a concern.
 109
 110 Edit the file `openafs/info/host` to set a brief description of the host, such
 111 as OS, version, memory size, CPU speed, versions of relevant libraries
 112 installed.
 113
 114
 115 ## Start build worker
 116
 117 As the `buildbot` user, manually verify the buildbot worker starts and connects
 118 to the buildbot master:
 119
 120    buildbot-worker start openafs
 121
 122 Check the logs to make sure it started properly.  Check the OpenAFS BuildBot
 123 web portal to see the build progress presented graphically.
 124
 125 ## Set up startup scripts
 126
 127 Make sure the buildbot worker starts automatically when the host is started.
 128 This, of course is platform dependent.  If you installed the buildbot worker
 129 with your package manager, the init scripts systemd files should already be
 130 installed.  If you installed the buildbot worker with pip, you will need to
 131 setup init scripts or systemd files to start the worker when the host is
 132 started.
 133
 134 Here is an example systemd unit file to start the buildbot worker on
 135 systemd based hosts. Save as `/etc/systemd/system/buildbot-worker.service`
 136
 137     [Unit]
 138     Description=BuildBot worker service
 139     After=network.target
 140
 141     [Service]
 142     User=buildbot
 143     Group=buildbot
 144     WorkingDirectory=/home/buildbot/openafs
 145     ExecStart=/home/buildbot/venv/bin/buildbot-worker start --nodaemon
 146
 147     [Install]
 148     WantedBy=multi-user.target
 149
 150 If the worker is running on a virtual machine, be sure the guest will be
 151 automatically restarted when the hypervisor is restarted.
 152
 153 ## Set up log rotation and various other useful settings
 154
 155 The buildbot.tac configuration file can be used to optimize your buildbot
 156 worker.  For instance, you may want to change maxRotatedFiles so you don't end
 157 up with a bunch of logs littered about.  Have a look at the BuildBot
 158 documentation if you wish, though you can expect to be able to take a fairly
 159 hands-off approach to administering your new OpenAFS build slave.
 160
 161 Link to current BuildBot documentation: [[http://buildbot.net/buildbot/docs/current/]]
 162
 163 Thanks for your help!