Abstract

Lately I have been wanting to learn more about development and the process behind pushing code. For many entities, a big part of the process is the CI/CD pipelines that automate various aspects of testing and releasing code. It sounds like an interesting and very useful idea and wanted to learn more about it. So, I decided to pick up and play with Buildbot.

From Buildbot’s docs

Buildbot is a framework to automate the compile and test cycle that is used to validate code changes in most software projects.

Test Environment and General Goals

I didn’t have a lot of goals for this project other than get something to compile stuff (very scientific I know). However, I also know with my lack of development skills and how much I am actually writing code, a CI pipeline is probably not going to be super useful. So, for now the main part of the project is to set up two machines, a master and a worker, that can pull from a git repo and build software. From there, I will work with it further to find more useful things Buildbot can do.

Host 1

Host 1 is going to be a FreeBSD machine acting as the Buildbot master as well as a Forgejo host for the code we will be using in Buildbot. This post is not going to go over setting Forgejo up or installing FreeBSD; however, if you are interested I already made a post on that exact topic. I will mostly be focusing on getting Buildbot setup on a FreeBSD host:

# Install Buildbot with a web interface front-end
pkg install -y buildbot-www
# enable the service (many different ways to do this on FreeBSD)
service buildbot enable
# Go to the directory for Buildbot install (/var/db/buildbot by default)
cd /var/db/buildbot
# edit master.cfg to fit needs
vim master.cfg

It took me a bit to figure out what I was doing with this file; in an attempt to help anyone reading this in the future, I am posting my master.cfg as well as the diff compared with master.cfg.sample.

My master.cfg after editing to make it build stuff.

# -*- python -*-
# ex: set filetype=python:

from buildbot.plugins import *

# This is a sample buildmaster config file. It must be installed as
# 'master.cfg' in your buildmaster's base directory.

# This is the dictionary that the buildmaster pays attention to. We also use
# a shorter alias to save typing.
c = BuildmasterConfig = {}

####### WORKERS

# The 'workers' list defines the set of recognized workers. Each element is
# a Worker object, specifying a unique worker name and password.  The same
# worker name and password must be configured on the worker.
c['workers'] = [worker.Worker("example-worker", "secret_password"), worker.Worker("buildbot", "secret_password")]

# 'protocols' contains information about protocols which master will use for
# communicating with workers. You must define at least 'port' option that workers
# could connect to your master with this protocol.
# 'port' must match the value configured into the workers (with their
# --master option)
c['protocols'] = {'pb': {'port': 9989}}

####### CHANGESOURCES

# the 'change_source' setting tells the buildmaster how it should find out
# about source code changes.  Here we point to the buildbot version of a python hello-world project.

c['change_source'] = []
c['change_source'].append(changes.GitPoller(
        'https://github.com/buildbot/hello-world.git',
        workdir='gitpoller-workdir', branch='master',
        pollInterval=300))

####### SCHEDULERS

# Configure the Schedulers, which decide how to react to incoming changes.  In this
# case, just kick off a 'runtests' build

c['schedulers'] = []
c['schedulers'].append(schedulers.SingleBranchScheduler(
                            name="all",
                            change_filter=util.ChangeFilter(branch='master'),
                            treeStableTimer=None,
                            builderNames=["duskOS"]))
c['schedulers'].append(schedulers.ForceScheduler(
                            name="force",
                            builderNames=["duskOS"]))

####### BUILDERS

# The 'builders' list defines the Builders, which tell Buildbot how to perform a build:
# what steps, and which workers can execute them.  Note that any particular build will
# only take place on one worker.

factory = util.BuildFactory()
# check out the source
factory.addStep(steps.Git(repourl='http://192.168.122.128:3000/fac3/duskOS/', mode='incremental'))
# run the tests (note that this will require that 'trial' is installed)
factory.addStep(steps.ShellCommand(command=["make"],
                                   env={"PYTHONPATH": "."}))

c['builders'] = []
c['builders'].append(
    util.BuilderConfig(name="duskOS",
      workernames=["buildbot"],
      factory=factory))

####### BUILDBOT SERVICES

# 'services' is a list of BuildbotService items like reporter targets. The
# status of each build will be pushed to these targets. buildbot/reporters/*.py
# has a variety to choose from, like IRC bots.

c['services'] = []

####### PROJECT IDENTITY

# the 'title' string will appear at the top of this buildbot installation's
# home pages (linked to the 'titleURL').

c['title'] = "Hello World CI"
#c['titleURL'] = "https://buildbot.github.io/hello-world/"
c['titleURL'] = "http://192.168.122.128:3000/fac3/duskOS/"

# the 'buildbotURL' string should point to the location where the buildbot's
# internal web server is visible. This typically uses the port number set in
# the 'www' entry below, but with an externally-visible host name which the
# buildbot cannot figure out without some help.

c['buildbotURL'] = "http://192.168.122.128:8010/"

# minimalistic config to activate new web UI
c['www'] = dict(port=8010,
                plugins=dict(waterfall_view={}, console_view={}, grid_view={}))

####### DB URL

c['db'] = {
    # This specifies what database buildbot uses to store its state.
    # It's easy to start with sqlite, but it's recommended to switch to a dedicated
    # database, such as PostgreSQL or MySQL, for use in production environments.
    # http://docs.buildbot.net/current/manual/configuration/global.html#database-specification
    'db_url' : "sqlite:///state.sqlite",
}

The diff comparing master.cfg.sample to my edited one.

--- master.cfg.sample   2024-09-05 22:27:32.771221000 -0400
+++ master.cfg  2024-09-11 22:59:26.934922000 -0400
@@ -15,7 +15,7 @@
 # The 'workers' list defines the set of recognized workers. Each element is
 # a Worker object, specifying a unique worker name and password.  The same
 # worker name and password must be configured on the worker.
-c['workers'] = [worker.Worker("example-worker", "pass")]
+c['workers'] = [worker.Worker("example-worker", "pass"), worker.Worker("buildbot", "buildbot")]
 
 # 'protocols' contains information about protocols which master will use for
 # communicating with workers. You must define at least 'port' option that workers
@@ -45,10 +45,10 @@
                             name="all",
                             change_filter=util.ChangeFilter(branch='master'),
                             treeStableTimer=None,
-                            builderNames=["runtests"]))
+                            builderNames=["duskOS"]))
 c['schedulers'].append(schedulers.ForceScheduler(
                             name="force",
-                            builderNames=["runtests"]))
+                            builderNames=["duskOS"]))
 
 ####### BUILDERS
 
@@ -58,15 +58,15 @@
 
 factory = util.BuildFactory()
 # check out the source
-factory.addStep(steps.Git(repourl='https://github.com/buildbot/hello-world.git', mode='incremental'))
+factory.addStep(steps.Git(repourl='http://192.168.122.128:3000/fac3/duskOS/', mode='incremental'))
 # run the tests (note that this will require that 'trial' is installed)
-factory.addStep(steps.ShellCommand(command=["trial", "hello"],
+factory.addStep(steps.ShellCommand(command=["make"],
                                    env={"PYTHONPATH": "."}))
 
 c['builders'] = []
 c['builders'].append(
-    util.BuilderConfig(name="runtests",
-      workernames=["example-worker"],
+    util.BuilderConfig(name="duskOS",
+      workernames=["buildbot"],
       factory=factory))
 
 ####### BUILDBOT SERVICES
@@ -83,14 +83,15 @@
 # home pages (linked to the 'titleURL').
 
 c['title'] = "Hello World CI"
-c['titleURL'] = "https://buildbot.github.io/hello-world/"
+#c['titleURL'] = "https://buildbot.github.io/hello-world/"
+c['titleURL'] = "http://192.168.122.128:3000/fac3/duskOS/"
 
 # the 'buildbotURL' string should point to the location where the buildbot's
 # internal web server is visible. This typically uses the port number set in
 # the 'www' entry below, but with an externally-visible host name which the
 # buildbot cannot figure out without some help.
 
-c['buildbotURL'] = "http://localhost:8010/"
+c['buildbotURL'] = "http://192.168.122.128:8010/"
 
 # minimalistic config to activate new web UI
 c['www'] = dict(port=8010,

The important parts to get the master and the worker to communicate is to modify the ‘workers’ list to add the worker credentials to be used in the buildbot.tac file on the work (will be explained below). From there, you can modidy the steps in the factory.addStep section to add the repository of code to be downloaded as well as the corresponding command to build the code. To finish the process and get it to show up on the web interface, modify the util.BuilderConfig and workernames to match the project repo and the worker to be used respectively. Run the following command to reload the config:

buildbot reconfig

Oncethe worker is setup appropriately, the project should be available and ready to run.

Host 2

Host 2 is going to be the buildbot worker running a very standard FreeBSD install, so as on the first host I will not go into detail about that. Installing the worker is very straightforward:

# Installing the worker
pkg install buildbot-worker
# Enabling the service
echo 'buildbot_worker_enable="YES"' > /etc/rc.conf
# Adding the base directory for the worker service
echo 'buildbot_worker_basedir="/var/db/buildbot/workers"' > /etc/rc.conf
# Generate the `buildbot.tac` file for the worker
# Make sure the ${BUILDBOT_USER} and ${SECRET_PASSWORD} match
# the username and password given to buildbot master in the `master.cfg` file
# the directory location should match what went into `/etc/rc.conf`
su -m buildbot -c 'buildbot-worker create-worker /var/db/buildbot/workers 192.168.122.128:9989 ${BUILDBOT_USER} ${SECRET_PASSWORD}'
# Start the service
service buildbot-worker start

Below is roughly what buildbot.tac looks like on my buildbot-worker system:

import os

from buildbot_worker.bot import Worker
from twisted.application import service

basedir = '/var/db/buildbot/workers'
rotateLength = 10000000
maxRotatedFiles = 10

# if this is a relocatable tac file, get the directory containing the TAC
if basedir == '.':
    import os.path
    basedir = os.path.abspath(os.path.dirname(__file__))

# note: this line is matched against to check that this is a worker
# directory; do not edit it.
application = service.Application('buildbot-worker')

from twisted.python.logfile import LogFile
from twisted.python.log import ILogObserver, FileLogObserver
logfile = LogFile.fromFullPath(
    os.path.join(basedir, "twistd.log"), rotateLength=rotateLength,
    maxRotatedFiles=maxRotatedFiles)
application.setComponent(ILogObserver, FileLogObserver(logfile).emit)

buildmaster_host = '192.168.122.128'
port = 9989
connection_string = None

workername = 'buildbot'
passwd = 'secret_password'
keepalive = 600
umask = None
maxdelay = 300
numcpus = None
allow_shutdown = None
maxretries = None
use_tls = 0
delete_leftover_dirs = 0
proxy_connection_string = None
protocol = 'pb'

s = Worker(buildmaster_host, port, workername, passwd, basedir,
           keepalive, umask=umask, maxdelay=maxdelay,
           numcpus=numcpus, allow_shutdown=allow_shutdown,
           maxRetries=maxretries, protocol=protocol, useTls=use_tls,
           delete_leftover_dirs=delete_leftover_dirs,
           connection_string=connection_string,
           proxy_connection_string=proxy_connection_string)
s.setServiceParent(application)

Actually trying stuff out

Now that the workers and the jobs are setup in Buildbot, let’s try it out to see what happens. First, to confirm our worker go to TODO{insert path here} and the example worker should show up as well as the new worker. In my case, the new worker is called “buildbot”; to confirm that the worker has been added properly go to Builds -> Workers in the sidebar.

Next let’s run a job. Currently the only job I have is building duskOS. To see the build jobs, go to Builds -> Builders

To actually get something to run, click the force button at the top right corner of the screen, then the Start Build button on the bottom button on the window that pops up.

After clicking the Start Build button a new screen will appear showing the STDOUT of the build job.

Closing Thoughts

I am going to close out this blog post, but will continue working with Buildbot and writing about it once I have learned more about it, and CD/CI systems in general.