Merge "Add clarity to *Zuul from Scratch* instructions"

1 files changed, 18 insertions, 9 deletions

diff --git a/doc/source/admin/zuul-from-scratch.rst b/doc/source/admin/zuul-from-scratch.rst
index edbcd87f4..ce69e77a8 100644
--- a/doc/source/admin/zuul-from-scratch.rst
+++ b/doc/source/admin/zuul-from-scratch.rst
@@ -11,6 +11,14 @@ Environment Setup
 We're going to be using Fedora 27 on a cloud server for this
 installation.
 
+Prerequisites
+~~~~~~~~~~~~~
+
+- Port 9000 must be open and accessible from the internet so that 
+  Github can communicate with the Zuul web service.
+- You need an OpenStack cloud that serves as your node pool.
+  For experimentation, DevStack is fine.
+
 Login to your environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -89,15 +97,14 @@ fedora user's home directory.  It should be called
 that will be installed when instantiating the servers::
 
    cd ~
-   source <username>-openrc.sh  # this will prompt for password - enter it
-   umask 0066
-
+   source <username>-openrc.sh  # this may prompt for password - enter it
    ssh-keygen -t rsa -b 2048 -f nodepool_rsa  # don't enter a passphrase
    openstack keypair create --public-key nodepool_rsa.pub nodepool
 
 We'll use the private key later wheen configuring Zuul.  In the same
 session, configure nodepool to talk to your cloud::
 
+   umask 0066
    sudo mkdir -p ~nodepool/.config/openstack
    cat > clouds.yaml <<EOF
    clouds:
@@ -113,7 +120,8 @@ session, configure nodepool to talk to your cloud::
    sudo chown -R nodepool.nodepool ~nodepool/.config
    umask 0002
 
-Once you've written out the file, double check all the required fields have been filled out.
+Once you've written out the file, double check all the required fields
+have been filled out.
 
 ::
 
@@ -392,7 +400,8 @@ Create a `GitHub application
 
 * Set Where can this GitHub App be installed to "Any account"
 * Create the App
-* Generate a Private key in the app settings page and save the file for later
+* Generate a Private key in the app settings page and save the file
+  for later
 
 .. TODO See if we can script this using GitHub API
 
@@ -406,7 +415,7 @@ Edit ``/etc/zuul/zuul.conf`` to add the following::
   driver=github
   app_id=<APP ID NUMBER>
   app_key=/etc/zuul/github.pem
-  webhook_token=<WEBHOOK TOKEN>
+  webhook_token=<WEBHOOK SECRET>
 
 Upload the private key which was generated earlier, and save it in
 ``/etc/zuul/github.pem``.
@@ -424,14 +433,14 @@ delivered since Zuul wasn't configured at the time, so click
 ``Resend`` and verify that it is delivered now that Zuul is
 configured.
 
-Visit the public app page on GitHub,
-https://github.com/apps/my-org-zuul, and install the app into your org.
-
 Create two new repositories in your org.  One will hold the
 configuration for this tenant in Zuul, the other should be a normal
 project repo to use for testing.  We'll call them `zuul-test-config`
 and `zuul-test`, respectively.
 
+Visit the public app page on GitHub,
+https://github.com/apps/my-org-zuul, and install the app into your org.
+
 Edit ``/etc/zuul/main.yaml`` so that it looks like this::
 
    - tenant: