[yocto-autobuilder2,1/2] README-Guide: cleanup, clarify setup instructions

Submitted by Trevor Gamblin on June 22, 2020, 2:18 p.m. | Patch ID: 173780

Details

Message ID 20200622141848.3461211-2-trevor.gamblin@windriver.com
State New
Headers show

Commit Message

Trevor Gamblin June 22, 2020, 2:18 p.m.
Broke the document up into more sections, and added some info
to make it clear that the same instructions for setting up
the systemd autobuilder can be used to start it manually.

Signed-off-by: Trevor Gamblin <trevor.gamblin@windriver.com>
---
 README-Guide.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

Patch hide | download patch | download mbox

diff --git a/README-Guide.md b/README-Guide.md
index 21dd7c1..83e30d0 100644
--- a/README-Guide.md
+++ b/README-Guide.md
@@ -4,6 +4,8 @@  This guide will walk through how to install a stand-alone autobuilder controller
 
 ## 1) Stand-alone Installation
 
+### 1.1) Basic Requirements
+
 The final outputs of this section are a controller and worker installed in the same server, ready for trimming back to an individual organization's needs.
 
  > NOTE: The guide assumes that your host OS has the packages installed to support BitBake for the release(s) you are targeting.  Please refer to the Yocto manual for those packages.
@@ -17,6 +19,8 @@  sudo pip3 install buildbot buildbot-www buildbot-waterfall-view buildbot-console
 
 It is recommended to also install `testtools` and `libccpunit-subunit-dev` (via apt, in this case) on the worker in order for certain image tests to work correctly (e.g., `core-image-sato-sdk:do_testimage`).
 
+### 1.2) Creating the Autobuilder User's Directory
+
 For a new installation you will need a system user that can run Autobuilder2 as well as a couple of repositories: Autobuilder2 itself and a helper plugin.  As root:
 
 ```
@@ -27,11 +31,14 @@  buildbot-worker create-worker -r --umask=0o22 yocto-worker localhost example-wor
 cd yocto-controller
 git clone https://git.yoctoproject.org/git/yocto-autobuilder2 yoctoabb
 ln -rs yoctoabb/master.cfg master.cfg
-cd ~
+cd -
 git clone https://git.yoctoproject.org/git/yocto-autobuilder-helper
 chown -R pokybuild3:nogroup /home/pokybuild3
 ```
 
+Note: depending on the configuration of your system, you may need to
+replace "nogroup" with "pokybuild3" for the last command to work.
+
  > **IMPORTANT:** In the above command you created a controller and a worker, which will attempt to join the controller using `pass` as the password.  Feel free to change this, knowing that if you do, you must change the controller's master configuration file to match.
 
 At the end of this, your build user's home directory (e.g., `/home/pokybuild3`) should look like this:
@@ -43,6 +50,8 @@  yocto-controller/yoctoabb
 yocto-worker
 ```
 
+### 1.3) Customizing the Autobuilder Configuration
+
 Next, we need to update the `yocto-controller/yoctoabb/master.cfg` towards the bottom where the `title`, `titleURL`, and `buildbotURL` are all set.  This is also where you would specify a different password for binding workers to the master.
 
 Then, we need to update the `yocto-controller/yoctoabb/config.py` to include our worker.  In that file, find the line where `workers` is set and add: ["example-worker"].  _NOTE:_ if your worker's name is different, use that here.  Section 3.1 discusses how to further refine this list of workers.
@@ -61,9 +70,27 @@  Set `BASE_HOMEDIR` should be your build user's home directory.  (There are she
 
  > NOTE: The way the build step is written, the worker will pull a fresh copy of the helper from the server.  Therefore these configuration files must be committed to the `yocto-autobuilder-helper` repo location you have specified in `yoctoabb/config.py` because the worker is given a build step that pulls from that repo (see `yoctoabb/builders.py`).
 
-Finally, as root, add the `yocto-*.service` files to `/lib/systemd/system` (See Appendix A).  Run: `systemctl daemon-reload`.  You should now be able to successfully start these services (e.g., `sudo systemctl start yocto-*`).  The controller may take up to 15 seconds to start.
+### 1.4) Starting the Autobuilder
+
+At this point, you can start your Autobuilder controller, worker, and
+janitor in one of two ways: using buildbot manually, or by creating
+systemd service files.
+
+#### 1.4.1) Manually Starting the Autobuilder
+
+Run the following from the pokybuild3 directory:
+
+ 1. yocto-autobuilder-helper/janitor/ab-janitor&
+ 2. buildbot start yocto-controller
+ 3. buildbot-worker start yocto-worker
+
+#### 1.4.2) Creating Service Files
+
+ 1. As root, add the `yocto-*.service` files to `/lib/systemd/system` (See Appendix A).  
+ 2. Run: `systemctl daemon-reload`.  
+ 3. You should now be able to successfully start these services (e.g., `sudo systemctl start yocto-*`). The controller may take up to 15 seconds to start.
 
-### 1.1) Configuring the Worker's Hash Equivalency Server
+### 1.5) Configuring the Worker's Hash Equivalency Server
 
 A key part of the autobuilder setup is the use of a hash equivalency
 server, which is started manually on the Yocto hosts. By default, the