launchpad-reviewers team mailing list archive

[Tom Wardill <tom.wardill@xxxxxxxxxxxxx>]

Tom Wardill has proposed merging ~twom/lpbuildbot-worker:improve-readme into lpbuildbot-worker:main.

Commit message:
Improve README

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~twom/lpbuildbot-worker/+git/lpbuildbot-worker/+merge/386744

Add some words about components and expected set up.
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~twom/lpbuildbot-worker:improve-readme into lpbuildbot-worker:main.

diff --git a/README.md b/README.md
index 2316c4b..46f6fc9 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,22 @@
-sudo mkdir /var/lib/buildbot/slaves/xenial-lxd-worker
-sudo chown -R buildbot: /var/lib/buildbot/slaves/xenial-lxd-worker
-sudo usermod --shell /bin/bash buildbot
-sudo addgroup buildbot lxd
+# Launchpad Buildbot Worker Setup
 
-grep root:112:1 /etc/subuid -qs || sudo usermod --add-subuids 112-112 --add-subgids 116-116 root
-
-As buildbot user on host:
-cd /var/lib/buildbot/slaves/xenial-lxd-worker
-git clone https://git.launchpad.net/launchpad
-mkdir -p dependencies/sourcecode
-cd dependencies
-git clone https://git.launchpad.net/lp-source-dependencies download-cache
+This package is intended for installation on a buildbot worker (tested with v0.8.5),
+to provide scripts and tooling for running the Launchpad test suite in a parallel manner.
 
+## Language note
 
+The usage of 'slave' here is problematic but required by the version of buildbot used here - later versions have improved this language, and part of this work is to allow us to upgrade. This document will refer to 'worker' where not explicitly required by the buildbot code/setup.
 
-debuild -uc -us -i -I
+## Components
 
+There are two main types of component. The first creates a base image that has the prerequisites installed.
+The second is the process of performing a test run.
 
+### Creating an image
 
-Set up worker:
+From a fresh installation of Xenial (16.04):
 
+```bash
 sudo add-apt-repository ppa:twom/ppa
 sudo apt-get update
 sudo apt-get install lpbuildbot-setup
@@ -37,6 +34,15 @@ mkdir -p dependencies/sourcecode
 cd dependencies
 git clone https://git.launchpad.net/lp-source-dependencies download-cache
 create-lp-tests-lxd xenial /var/lib/buildbot/slaves/xenial-lxd-worker/
+```
+
+#### Notes
+
+1. This uses the LXD snap, and `pylxd` from apt. The version of `pylxd` in Xenial is very old and missing some features that would be handy, but it does work at the time of writing.
+2. We use `/var/lib/buildbot/slaves/xenial-lxd-worker` as the working directory for the builds, rather than the buildbot provided build directory. This only works as we assume there is only every one build at a time, but allows for the symlinking and bind mounting to be predictable.
+3. Having the buildbot user in the LXD is a convenience, and we do the uid/gid mapping based on known values. These may need adjusting depending on the setup of the host.
+
+### Set up worker
 
 Create /var/lib/buildbot/buildbot.tac:
 
@@ -83,8 +89,11 @@ SLAVE_RUNNER=/usr/bin/buildslave
 SLAVE_ENABLED[1]=1                    # 1-enabled, 0-disabled
 SLAVE_NAME[1]="lp-worker-lxd"         # short name printed on start/stop
 SLAVE_USER[1]="buildbot"              # user to run slave as
-SLAVE_BASEDIR[1]="/var/lib/buildbot"                   # basedir to slave (absolute path)
+SLAVE_BASEDIR[1]="/var/lib/buildbot"  # basedir to slave (absolute path)
 SLAVE_OPTIONS[1]=""                   # buildbot options
 SLAVE_PREFIXCMD[1]=""                 # prefix command, i.e. nice, linux32, dchroot
 ```
 
+### Run the worker
+
+`sudo /etc/init.d/buildslave start`