Add steps for setting up a latent worker on Amazon EC2

diff --git a/contrib/ci-workers/README.md b/contrib/ci-workers/README.md
index 72b832fcb1a68873d589013efcea1ace4de1175a..cc3c85ac221f68ac410c4752e52c3185512d8e81 100644 (file)
--- a/contrib/ci-workers/README.md
+++ b/contrib/ci-workers/README.md
@@ -2,3 +2,47 @@
 
 This folder contains the Ansible playbooks for configuring a fresh OS
 installation for use as a Buildbot worker in Zcash's CI.
+
+# Setting up a latent worker on Amazon EC2
+
+- Add a regular (non-latent) worker to the master.cfg for dev-ci.z.cash, and
+  deploy the changes.
+  - This enables the Ansible playbook to run to completion, ending in the worker
+    connecting to the master.
+
+- Start a basic EC2 instance using the template AMI for the target OS.
+  - Choose the smallest instance size, it won't be used for building Zcash.
+
+- Figure out which user to log into the instance with.
+  - E.g. for the Ubuntu template, use "ubuntu" instead of "root"
+  - If you get an Ansible error later with a message like "Failed to connect to
+    the host via ssh: Received message too long 1349281121\r\n", that means the
+    instance is sending a text string in response to the SSH connection, and the
+    Ansible protocol is balking. Try manually logging in with the same
+    credentials to diagnose.
+
+- Create `inventory/hosts` containing the following:
+
+    [zcash-ci-worker-unix]
+    some-name ansible_host=<INSTANCE_IP> ansible_ssh_user=<USERNAME>
+
+- Run `ansible-playbook -i inventory/hosts unix.yml`, passing in the worker's
+  Buildbot name and password.
+  - After a successful run, the worker should be connected to dev-ci.z.cash and
+    visible in its worker list.
+
+- Create an AMI from the instance. This is the worker AMI to put into the
+  master.cfg for dev-ci.z.cash.
+  - 16 GB of storage should be sufficient.
+
+- SSH into the instance, and edit the worker config to connect to ci.z.cash.
+
+- Create an AMI from the instance. This is the worker AMI to put into the
+  master.cfg for ci.z.cash.
+  - 16 GB of storage should be sufficient.
+
+- Delete the instance (it is no longer needed).
+
+- Edit the master.cfg to turn the new worker into a latent (using the new AMI
+  IDs), add it to the appropriate worker groups, set up new builders etc.
+  - Deploy this via the normal PR review process.