From 22736fd0ce374de102147af96927286e6b5a7473 Mon Sep 17 00:00:00 2001
From: Bernd Bausch <berndbausch@gmail.com>
Date: Mon, 26 Mar 2018 12:57:32 +0900
Subject: [PATCH] Add clarity to *Zuul from Scratch* instructions

A few small changes to make the instructions more robust
and clearer:
- list a few prerequisites, incl. accessibility of port
  9000 by Github.
- Move the umask 066 command as close as possible to where it
  belongs.
- clarify that webhook token==secret
- create the two Github repos before installing
  the Github app into the Github org.

Change-Id: Id1ff18b454e9bd6b2ff8317ede652653b557e9e6
---
 doc/source/admin/zuul-from-scratch.rst | 27 +++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/doc/source/admin/zuul-from-scratch.rst b/doc/source/admin/zuul-from-scratch.rst
index 26dd04a641..d0d7dbc61b 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: