1.1.1.Goal

This tutorial will take you from zero to running your first buildbot master and worker as quicklyas possible, without changing the default configuration.

This tutorial is all about instant gratification and the five minute experience: in five minutes wewant to convince you that this project works, and that you should seriously consider spending timelearning the system. In this tutorial no configuration or code changes are done.

This tutorial assumes that you are running Unix, but might be adaptable to Windows.

Thanks tovirtualenv, installing buildbot in a standalone environment is very easy. For those morefamiliar withDocker, there also exists adocker version of these instructions.

You should be able to cut and paste each shell block from this tutorial directly into a terminal.

1.1.2.Simple introduction to BuildBot

Before trying to run BuildBot it’s helpful to know what BuildBot is.

BuildBot is a continuous integration framework written in Python. It consists of a master daemonand potentially many worker daemons that usually run on other machines. The master daemon runs aweb server that allows the end user to start new builds and to control the behaviour of theBuildBot instance. The master also distributes builds to the workers. The worker daemons connect tothe master daemon and execute builds whenever master tells them to do so.

In this tutorial we will run a single master and a single worker on the same machine.

A more thorough explanation can be found in themanual section of the Buildbot documentation.

1.1.3.Getting ready

There are many ways to get the code on your machine.We will use the easiest one: viapip in avirtualenv.It has the advantage of not polluting your operating system, as everything will be contained in the virtualenv.

To make this work, you will need the following installed:

• Python and the development packages for it

• virtualenv

Preferably, use your distribution package manager to install these.

You will also need a working Internet connection, as virtualenv and pip will need to download otherprojects from the Internet. The master and builder daemons will need to be able to connect togithub.com via HTTPS to fetch the repo we’re testing.

If you need to use a proxy for this ensure that either theHTTPS_PROXY orALL_PROXYenvironment variable is set to your proxy, e.g., by executingexportHTTPS_PROXY=http://localhost:9080 in the shell before starting each daemon.

1.1.4.Creating a master

The first necessary step is to create a virtualenv for our master.We first create a separate directory to demonstrate the distinction between a master and worker:

mkdir-p~/buildbot-test/master_rootcd~/buildbot-test/master_root

Then we create the virtual environment. On Python 3:

python3-mvenvsandboxsourcesandbox/bin/activate

Next, we need to install several build dependencies to make sure we can install buildbot and its supporting packages.These build dependencies are:

• GCC build tools (gcc for RHEL/CentOS/Fedora based distributions, orbuild-essentialfor Ubuntu/Debian based distributions).

• Python development library (python3-devel for RHEL/CentOS/Fedora based distributions, orpython3-dev for Ubuntu/Debian based distributions).

• OpenSSL development library (openssl-devel for RHEL/CentOS/Fedora based distributions, orlibssl-dev for Ubuntu/Debian based distributions).

• libffi development library (libffi-devel for RHEL/CentOS/Fedora based distributions, orlibffi-dev for Ubuntu/Debian based distributions).

Install these build dependencies:

# if in Ubuntu/Debian based distributions:sudoapt-getinstallbuild-essentialpython3-devlibssl-devlibffi-dev# if in RHEL/CentOS/Fedora based distributions:sudoyuminstallgccpython3-developenssl-devellibffi-devel

or refer to your distribution’s documentation on how to install these packages.

Now that we are ready, we need to install buildbot:

pipinstall--upgradepippipinstall'buildbot[bundle]'

Now that buildbot is installed, it’s time to create the master.my_master represents a path to a directory, where future master will be created:

buildbotcreate-mastermy_master

Buildbot’s activity is controlled by a configuration file. Buildbot by default uses configurationfrom file atmaster.cfg, but its installation comes with a sample configuration file namedmaster.cfg.sample. We will use the sample configuration file unchanged, but we have to renameit tomaster.cfg:

mvmy_master/master.cfg.samplemy_master/master.cfg

Finally, start the master:

buildbotstartmy_master

You will now see some log information from the master in this terminal.It should end with lines like these:

2014-11-01 15:52:55+0100 [-] BuildMaster is runningThe buildmaster appears to have (re)started correctly.

From now on, feel free to visit the web status page running on the port 8010:http://localhost:8010/

Our master now needs (at least) one worker to execute its commands.For that, head on to the next section!

1.1.5.Creating a worker

The worker will be executing the commands sent by the master.In this tutorial, we are using the buildbot/hello-world project as an example.As a consequence of this, your worker will need access to thegit command in order to checkout some code.Be sure that it is installed, or the builds will fail.

Same as we did for our master, we will create a virtualenv for our worker next to the master’s one.It would however be completely ok to do this on another computer - as long as theworker computeris able to connect to themaster’s . We first create a new directory for the worker:

mkdir-p~/buildbot-test/worker_rootcd~/buildbot-test/worker_root

Again, we create a virtual environment. On Python 3:

python3-mvenvsandboxsourcesandbox/bin/activate

Install thebuildbot-worker command:

pipinstall--upgradepippipinstallbuildbot-worker# required for `runtests` buildpipinstallsetuptools-trial

Now, create the worker:

buildbot-workercreate-workermy_workerlocalhostexample-workerpass

The username (example-worker), and password (pass) should be the same as those inmy_master/master.cfg; verify this is the case by looking at the section forc['workers']:

cat../master_root/my_master/master.cfg

And finally, start the worker:

buildbot-workerstartmy_worker

Check the worker’s output.It should end with lines like these:

2014-11-01 15:56:51+0100 [-] Connecting to localhost:99892014-11-01 15:56:51+0100 [Broker,client] message from master: attachedThe worker appears to have (re)started correctly.

Meanwhile, from the other terminal, in the master log (twisted.log in the masterdirectory), you should see lines like these:

2014-11-01 15:56:51+0100 [Broker,1,127.0.0.1] worker 'example-worker' attaching fromIPv4Address(TCP, '127.0.0.1', 54015)2014-11-01 15:56:51+0100 [Broker,1,127.0.0.1] Got workerinfo from 'example-worker'2014-11-01 15:56:51+0100 [-] bot attached

1.1.6.Wrapping up

Your directory tree now should look like this:

~/buildbot-test/master_root/my_master  # master base directory~/buildbot-test/master_root/sandbox    # virtualenv for master~/buildbot-test/worker_root/my_worker  # worker base directory~/buildbot-test/worker_root/sandbox    # virtualenv for worker

You should now be able to go tohttp://localhost:8010, where you will see a web page similar to:

Click on “Builds” at the left to open the submenu and thenBuilders to see that the worker you just started (identifiedby the green bubble) has connected to the master:

Your master is now quietly waiting for new commits to hello-world.This doesn’t happen very often though.In the next section, we’ll see how to manually start a build.

We just wanted to get you to dip your toes in the water. It’s easy to take your first steps, butthis is about as far as we can go without touching the configuration.

You’ve got a taste now, but you’re probably curious for more.Let’s step it up a little in the second tutorial by changing the configuration and doing an actual build.Continue on toA Quick Tour.