2.4 Creating a buildmaster

As you learned earlier (see System Architecture), the buildmaster runs on a central host (usually one that is publically visible, so everybody can check on the status of the project), and controls all aspects of the buildbot system. Let us call this host buildbot.example.org.

You may wish to create a separate user account for the buildmaster, perhaps named buildmaster. This can help keep your personal configuration distinct from that of the buildmaster and is useful if you have to use a mail-based notification system (see Change Sources). However, the Buildbot will work just fine with your regular user account.

You need to choose a directory for the buildmaster, called the basedir. This directory will be owned by the buildmaster, which will use configuration files therein, and create status files as it runs. ~/Buildbot is a likely value. If you run multiple buildmasters in the same account, or if you run both masters and slaves, you may want a more distinctive name like ~/Buildbot/master/gnomovision or ~/Buildmasters/fooproject. If you are using a separate user account, this might just be ~buildmaster/masters/fooproject.

Once you've picked a directory, use the buildbot create-master command to create the directory and populate it with startup files:

     buildbot create-master -r basedir

You will need to create a configuration file (see Configuration) before starting the buildmaster. Most of the rest of this manual is dedicated to explaining how to do this. A sample configuration file is placed in the working directory, named master.cfg.sample, which can be copied to master.cfg and edited to suit your purposes.

(Internal details: This command creates a file named buildbot.tac that contains all the state necessary to create the buildmaster. Twisted has a tool called twistd which can use this .tac file to create and launch a buildmaster instance. twistd takes care of logging and daemonization (running the program in the background). /usr/bin/buildbot is a front end which runs twistd for you.)

In addition to buildbot.tac, a small Makefile.sample is installed. This can be used as the basis for customized daemon startup, See Launching the daemons.

Using MySQL

If you want to use MySQL as the database backend for your Buildbot, add the --db option to the create-master invocation to specify the connection string for the MySQL database (see Database Specification).

Buildmaster Options

This section lists options to the create-master command. You can also type buildslave create-slave --help for an up-to-the-moment summary.

--force

With this option, create-master will re-use an existing master directory.

--no-logrotate

This disables internal buildslave log management mechanism. With this option buildslave does not override the default logfile name and its behaviour giving a possibility to control those with command-line options of twistd daemon.

--relocatable

This creates a "relocatable" buildbot.tac, which uses relative paths instead of absolute paths, so that the buildmaster directory can be moved about.

--config

The name of the configuration file to use. This configuration file need not reside in the buildmaster directory.

--log-size

This is the size in bytes when to rotate the Twisted log files. The default is 10MiB.

--log-count

This is the number of log rotations to keep around. You can either specify a number or None to keep all twistd.log files around. The default is 10.

--db

The database that the Buildmaster should use. This information is needed earlier than the configuration file can be loaded.