.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "buildbot" "7" "2024-01-15" "" "Services Administration"
.P
.SH NAME
.P
buildbot - master instances creation, upgrade and management
.P
.SH DESCRIPTION
.P
Buildbot master instances are located under individual folders in
\fI/var/lib/buildbot/masters\fR.\& This manual explains how to manage them.\&
.P
.SH CREATION
.P
To create a new Buildbot master instance named \fI$NAME\fR, use the following
commands:
.P
.nf
.RS 4
buildbot create-master /var/lib/buildbot/masters/$NAME
chown -R buildbot: /var/lib/buildbot/masters/$NAME
.fi
.RE
.P
After which, you should review and edit the \fImaster.\&cfg.\&sample\fR configuration
file located in the master base directory and rename it to \fImaster.\&cfg\fR.\&
.P
The configuration file syntax is extensively described in
\fI/usr/share/doc/buildbot/html\fR (installed with the \fBbuildbot-doc\fR package).\&
.P
\fBnote\fR
.RS 4
In the default configuration Buildbot uses a file-based SQLite
database, stored in the \fIstate.\&sqlite\fR file of the master'\&s base
directory.\& If you want to use another database engine, you may need to
install additional packages (e.\&g.\&, \fBpostgresql\fR and \fBpython3-psycopg2\fR
to use PostgreSQL).\& Refer to the Buildbot documentation for the
associated \fImaster.\&cfg\fR syntax.\&
.P
.RE
\fBATTENTION\fR
.RS 4
The new Buildbot web dashboard cannot be integrated into Debian yet
because of policy violation (See: bug #883529).\& In the meantime, if you
want to enable it in your configuration, it can be installed with \fBpip3
install buildbot-www\fR.\&
.P
.RE
You may use the following command to validate your configuration file:
.P
.nf
.RS 4
buildbot checkconfig /var/lib/buildbot/masters/$NAME/master\&.cfg
.fi
.RE
.P
Once you are satisfied with your configuration file, you may start the Buildbot
master instance.\& Depending on the init system you use, this is done differently.\&
.P
.SS systemd
.P
To start the instance:
.P
.nf
.RS 4
systemctl start buildbot@$NAME\&.service
.fi
.RE
.P
To enable automatic start on boot:
.P
.nf
.RS 4
systemctl enable buildbot@$NAME\&.service
.fi
.RE
.P
If you want to tune the way the instance is started (e.\&g.\&, to change
the user that runs the process), you may use a systemd drop-in:
.P
.nf
.RS 4
mkdir -p /etc/systemd/system/buildbot@$NAME\&.service\&.d
editor /etc/systemd/system/buildbot@$NAME\&.service\&.d/user\&.conf
.fi
.RE
.P
With the following contents:
.P
.nf
.RS 4
[Service]
User=my-user
Group=my-group
.fi
.RE
.P
.SS sysvinit
.P
First, you need to edit \fI/etc/default/buildbot\fR and configure your instance.\& The
syntax is pretty self explanatory, but here is an example:
.P
.nf
.RS 4
# 1-enabled, 0-disabled
MASTER_ENABLED[1]=1
# short name printed on start/stop
MASTER_NAME[1]="$NAME"
# user to run master as
MASTER_USER[1]="buildbot"
# basedir to master (absolute path)
MASTER_BASEDIR[1]="/var/lib/buildbot/masters/$NAME"
# buildbot options
MASTER_OPTIONS[1]=""
# prefix command, i\&.e\&. nice, linux32, dchroot
MASTER_PREFIXCMD[1]=""
.fi
.RE
.P
After which, you may start the instance:
.P
.nf
.RS 4
service buildbot start $NAME
.fi
.RE
.P
By default, it will automatically start on boot.\&
.P
.SH UPGRADE
.P
By default, Buildbot master instances are automatically upgraded when installing
new versions.\& This consists in the following operations for each instance:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
The instance is stopped.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fIbuildbot upgrade-master /var/lib/buildbot/masters/$NAME\fR is executed.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
The instance is started again.\&

.RE
.P
You may disable the automatic upgrade globally by running:
.P
.nf
.RS 4
dpkg-reconfigure buildbot
.fi
.RE
.P
Or for a specific master instance by creating a \fI.\&no-auto-upgrade\fR file in its
base directory:
.P
.nf
.RS 4
touch /var/lib/buildbot/masters/$NAME/\&.no-auto-upgrade
.fi
.RE
.P
In any case, the upgrade operation is mandatory and Buildbot will fail to
restart an instance that has not been upgraded.\&
.P
After upgrading, you will find that Buildbot has created a new
\fImaster.\&cfg.\&sample\fR file in the instance base directory.\& You can review it and
check the differences with your own configuration file.\& But in most cases, it
is safe to delete this file.\&
.P
.SS upgrading from 0.8.x
.P
If upgrading from a 0.\&8.\&x version, all master instances in must be manually
migrated.\& This may require a number of changes to the master configuration.\&
Please refer to the "nine-upgrade" chapter in the documentation for details.\&
Once you have finished migrating, you may delete the \fI.\&no-auto-upgrade\fR files
to allow further automatic upgrades to proceed.\&
.P
The \fIbuildmaster\fR service has been renamed to \fIbuildbot\fR.\&
.P
Also, to avoid spurious errors on boot, the automatic start of each existing
instance has been "disabled" in \fI/etc/default/buildbot\fR (which was renamed from
\fI/etc/default/buildmaster\fR).\& If you which to use systemd to manage your
instances, please refer to the \fBCREATION\fR section of this manual.\&
.P
.SH FILES
.P
\fI/var/lib/buildbot/masters/$NAME\fR
.RS 4
Working directory for the \fI$NAME\fR Buildbot master instance.\&
.P
.RE
\fI/etc/systemd/system/buildbot@$NAME.\&service.\&d\fR
.RS 4
Directory containing customization drop-ins for the \fI$NAME\fR Buildbot
master instance service.\&
.P
.RE
\fI/etc/default/buildbot\fR
.RS 4
The master instances services definition for sysvinit users.\&
.P
.RE
.SH SEE ALSO
.P
\fBbuildbot\fR(1), \fBsystemctl\fR(1), \fBsystemd.\&unit\fR(5), \fBservice\fR(8)
.P
.SH AUTHOR
.P
Robin Jarry <robin@jarry.\&cc>