doc/ARCHITECTURE

   1 0. ABSTRACT
   2
   3 Below is a description of the way the builder infrastructure works. You should
   4 read it in order to be able to understand what's exactly going on when you try
   5 to build a package.
   6
   7 (It assumes you have a basic understanding of how RPM packages are created.)
   8
   9 1. OVERVIEW
  10
  11 The builder infrastructure is divided into three parts:
  12 - the client
  13 - the source builder
  14 - the binary builders
  15
  16 The basic idea is to allow developers (requesters) to easily specify which
  17 package they want built, and have the rest of the system take care of building
  18 and upgrading packages, uploading them where appropriate and reporting back to
  19 the developers on the results (were there errors, how long it took to build,
  20 etc.).
  21
  22 What follows is a more detailed description of what each part is supposed to
  23 do.
  24
  25 1.1 NOTES ON UPLOADING
  26
  27 When talking of uploading packages and logs it is meant as placing them
  28 somewhere on the original system (via a simple 'cp'; this also includes copying
  29 to /dev/null), or placing them on a remote system via the scp or rsync
  30 protocols.
  31
  32 1.2 TOOLS USED
  33
  34 99% of the system is written in python, with remaining parts using shell
  35 scripts (POSIX shell is assumed, bashisms are to be shot at sight and their
  36 authors beheaded in a public display). The presence of various helper tools is
  37 assumed. They are: gpg, rsync and scp command line utilities.
  38
  39 2. SHORT DIAGRAM
  40
  41 Below are complete basics of how data is tossed around. Only the most relevant
  42 transfers are presented.
  43
  44          status info          status info
  45        +--------------+<--+------------------+
  46        |    build     |   |                  |
  47        V   request    |   V       src.rpm    |
  48 requester ---------> src.builder ---------> bin.builders
  49                           |                  |
  50                           | arch.rpms        |
  51            FTP server <---+------------------+
  52
  53 3. CLIENT
  54
  55 Main task: sending build requests to source builders.
  56
  57 This is the simplest part. It consists of a shell script (make-request.sh),
  58 which, based on the way it's configured and on the cmdline parameters given to
  59 it, generates an xml-formated build request, which it then signs with the
  60 requester's PGP key (using the gpg utility) and then sends it to the source
  61 builder via a sendmail compatible command line application (by default invoking
  62 "sendmail -t").
  63
  64 Two modes of operation are:
  65 - sending requests to build chosen package(s) on a specified group of builders
  66 - sending a chosen command to be executed on a specified group of builders
  67
  68 See HOWTO-CLIENT for a hands-on approach to setting yourself up for being able
  69 to send out build requests.
  70
  71 4. SOURCE BUILDER (AKA SRC.BUILDER)
  72
  73 Main task: building src.rpm packages and serving them to binary builders.
  74 Additional tasks: reporting back to the requester about the status of the build
  75 and uploading generated src.rpm packages where appropriate. Also -- tagging,
  76 access control, uploading buildlogs and keeping the 'queue.html' file in sync.
  77
  78 The source builder is the central place for managing access rights for
  79 requesters. Upon receiving a request (via email), it first checks the pgp
  80 signature with which the request was signed, against the pgp key currently
  81 assigned to the requester (all done with the 'gpg' command). After verifying
  82 that the requester name/requester pgp signature pair match, it then checks if
  83 the requester is actually allowed to perform the actions she wants to perform.
  84 That is: does she have access to a specified binary builder, is she allowed to
  85 specify the 'upgrade' flag or not, is she allowed to use the priority she set
  86 for the request and even if she is allowed to request building of a given
  87 package.
  88
  89 Once a request passes all verifications, the src.builder uses its own chroot
  90 equipped with a basic build environment to fetch the sources of a given
  91 package, tag them if configured to do so and create a src.rpm out of them (all
  92 done by invoking the 'builder' script as found in the SPECS module of the PLD
  93 cvs repository (see http://www.pld-linux.org/Repositories for details)).
  94
  95 After finishing the build procedure the src.builder reports (via email) to the
  96 requester on the status of the build (OK/FAIL), updates the 'queue.html' file
  97 with that information (urls for PLD2.0 and 3.0 queues:
  98 http://ep09.pld-linux.org/~buildsrc/queue.html and
  99 http://src.th.pld-linux.org/queue.html) and, if configured to do so,
 100 uploads the complete log of the whole procedure (called the buildlog)
 101 somewhere, most likely to our PLD buildlogs system
 102 (http://buildlogs.pld-linux.org).
 103
 104 If the build procedure was successful, the resulting src.rpm file is most
 105 likely uploaded somewhere (if configured to do so; in our case it's our FTP
 106 server) and, what is most important, it's being served via a http server for
 107 the binary builders to download. An xml-formated (and pgp signed) 'queue.gz'
 108 and a small 'max_req_no' files are also updated with relevant information, in
 109 order for the bin.builders to be able to notice new requests and figure out
 110 which are addressed to which builders.
 111
 112 The last matter taken care of by the src.builder is receiving (gpg signed)
 113 emails from bin.builders with status information regarding what happened to
 114 various builds (whether they succeeded or failed) and updating the 'queue.html'
 115 file accordingly.
 116
 117 See the HOWTO-BUILDERS file for a hands-on approach on setting up builders. All
 118 of the technical details are there.
 119
 120 5. BINARY BUILDERS (AKA BIN.BUILDERS)
 121
 122 Main task: building arch.rpm packages and uploading them where appropriate.
 123 Additional tasks: reporting back to the requester and the source builder on the
 124 status of the build. Also -- uploading buildlogs.
 125
 126 Upon noticing that a new request has been published by the src.builder and
 127 verifying the appropriate gpg signatures, binary builders download the relevant
 128 src.rpm files and use their build-environment-equipped chroots to start
 129 building them (by invoking the 'rpmbuild' command). Once a build is completed
 130 (meaning arch.rpm files are produced, or the whole procedure is interrupted for
 131 whatever reason), the status of the build (OK/FAIL) is sent via email both to
 132 the requester and to the src.builder.
 133
 134 Procedure for uploading the produced arch.rpms and buildlogs is the same as
 135 with the src.builder.
 136
 137 Bin.builders however need to deal with one thing src.builders are mostly not
 138 affected by -- managing the build environments inside their chroots. That means
 139 installing new packages if required by a given build (using the 'poldek'
 140 package manager; http://poldek.pld-linux.org/), upgrading older packages for
 141 much the same reasons, downgrading from time to time and locally caching newly
 142 built files for short periods of times.
 143
 144 All of this, along with lots of quirks and obscure details is explained in the
 145 HOWTO-BUILDERS file.
 146
 147 6. Q/A
 148
 149 Q: What's this 'tagging' all about with the src.builder?
 150 A: When a src.rpm is created and arch.rpms built based on it, it is sometimes
 151 useful to be able to check which sources were used to build them. Casual users
 152 might be satisfied with just extracting everything from the src.rpm (that is
 153 what they are uploaded to the ftp server for), but the old ones aren't always
 154 available and even if they are, developers require source control in order to
 155 work efficiently. Hence all sources used to build a given src.rpm for a given
 156 line are tagged appropriately in the PLD CVS repository, for example trying to
 157 build cthulu.spec on the 2.0 (codename Ac) line of our distro might result in a
 158 tag looking something like this being set -- 'auto-ac-cthulu-6.6-6'.
 159 (Technically the previous sentence is not 100% correct due to (a) the way our
 160 DISTFILES infrastructure impacts which sources are and aren't in the CVS repo
 161 and hence are subject to tagging and (b) specific policies regarding tagging
 162 for each distro line; for the latter refer to appropriate policies.)
 163
 164
 165 # vi: formatoptions=aw expandtab