===============
buildbot-worker
===============

-------------------------------------------------
worker instances creation, upgrade and management
-------------------------------------------------

:Date: 2019-01-08
:Author: Robin Jarry <robin@jarry.cc>
:Manual section: 7
:Manual group: Services Administration

DESCRIPTION
===========

Buildbot worker instances are managed under individual folders in
*/var/lib/buildbot/workers*. This manual explains how to manage them.

CREATION
========

To create a new Buildbot worker instance named *$NAME*, use the following
commands::

   buildbot-worker create-worker \
         /var/lib/buildbot/workers/$NAME <master> <name> <passwd>
   chown -R buildbot: /var/lib/buildbot/workers/$NAME

After which you may start the worker instance. Depending on the init system you
use, this is done differently.

systemd
-------

To start the instance::

   systemctl start buildbot-worker@$NAME.service

To enable automatic start on boot::

   systemctl enable buildbot-worker@$NAME.service

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::

   mkdir -p /etc/systemd/system/buildbot-worker@$NAME.service.d
   editor /etc/systemd/system/buildbot-worker@$NAME.service.d/user.conf

With the following contents::

   [Service]
   User=my-user
   Group=my-group

sysvinit
--------

First, you need to edit */etc/default/buildbot-worker* and configure your
instance. The syntax is pretty self explanatory, but here is an example::

   WORKER_ENABLED[1]=1                    # 1-enabled, 0-disabled
   WORKER_NAME[1]="$NAME"                 # short name printed on start/stop
   WORKER_USER[1]="buildbot"              # user to run worker as
   WORKER_BASEDIR[1]="/var/lib/buildbot/workers/$NAME"  # basedir to worker (absolute path)
   WORKER_OPTIONS[1]=""                   # buildbot-worker options
   WORKER_PREFIXCMD[1]=""                 # prefix command, i.e. nice, linux32, dchroot

After which, you may start the instance::

   service buildbot-worker start $NAME

By default, it will automatically start on boot.

UPGRADE
=======

When installing new versions, each worker instance is automatically restarted.
No additional action is required.

upgrade from 0.8.x
------------------

Since version 0.9.0 of Buildbot "slave"-based terminology is deprecated in
favor of "worker"-based terminology.

If you are upgrading from a 0.8.x version, all old buildbot-slave instances in
*/var/lib/buildbot/slaves* must be manually migrated. The simplest way of doing
that is to create new workers re-using the same *<master>*, *<name>* and
*<passwd>* arguments. See the **CREATION** section of this manual for more
details.

Once migrated, you may safely delete the old "slave" directory::

   rm -rf /var/lib/buildbot/slaves/$NAME

FILES
=====

``/var/lib/buildbot/workers/$NAME``
   Working directory for the ``$NAME`` Buildbot worker instance.

``/etc/systemd/system/buildbot-worker@$NAME.service.d``
   Directory containing customization drop-ins for the *$NAME* Buildbot worker
   instance service.

``/etc/default/buildbot-worker``
   The worker instances services definition for sysvinit users.

SEE ALSO
========

``buildbot-worker``\(1), ``systemctl``\(1), ``systemd.unit``\(5),
``service``\(8)
