Various minor INSTALL files changes

5 files changed, 72 insertions, 51 deletions

diff --git a/INSTALL b/INSTALL
index 3476de0..94b73cf 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,7 +1,8 @@
-This guide shows how to install and configure brep on a "deployment" machine as
-opposed to a "development" one (see INSTALL-DEV for the latter). Here we assume
-you are using a systemd-based distribution. If not, then you will need to
-replace systemctl commands with the equivalent init.d ones.
+This guide describes how to install and configure brep on a "deployment"
+machine as opposed to a "development" one (see INSTALL-DEV for the
+latter). Here we assume you are using a systemd-based distribution. If not,
+then you will need to replace systemctl commands with the equivalent init.d
+ones.
 
 The below instructions include steps for setting up brep as the build2 build
 bot controller, package submission, and CI request services. All these
@@ -233,6 +234,61 @@ $ psql -d brep_build -c 'SELECT DISTINCT name FROM build_package'
 $ cp install/share/brep/etc/brep-module.conf config/
 $ edit config/brep-module.conf # Adjust default values if required.
 
+See the following sub-sections for details on configuring various optional
+brep functionality.
+
+Once the brep module configuration is ready, the next step is to enable
+it in the Apache2 configuration file. Here we assume you have setup an
+appropriate Apache2 virtual server. Open the corresponding Apache2 .conf
+file and add the contents of brep/etc/brep-apache2.conf into the
+<VirtualHost> section.
+
+The output content types of the brep module are application/xhtml+xml,
+text/manifest and text/plain. If you would like to make sure they get
+compressed (along with linked CSS), also add the following lines:
+
+        # Compress brep output (xhtml+xml) and CSS.
+        #
+        AddOutputFilterByType DEFLATE application/xhtml+xml
+        AddOutputFilterByType DEFLATE text/manifest
+        AddOutputFilterByType DEFLATE text/plain
+        AddOutputFilterByType DEFLATE text/css
+
+Then restart Apache2:
+
+$ sudo systemctl restart apache2
+
+To verify, visit the repository root. To troubleshoot, see Apache logs.
+
+Now that Apache2 loads the brep module which requires PostgreSQL, it is a good
+idea to make the Apache2 service depend on PostgreSQL so that they are started
+in proper order. Here is how we can do it with systemd (with newer versions
+you can use 'systemctl edit' instead of mkdir and cat):
+
+# mkdir -p /etc/systemd/system/apache2.service.d/
+# cat >/etc/systemd/system/apache2.service.d/postgresql.conf
+[Unit]
+Requires=postgresql.service
+After=postgresql.service
+^D
+
+# mkdir -p /etc/systemd/system/postgresql.service.d/
+# cat >/etc/systemd/system/postgresql.service.d/apache2.conf
+[Unit]
+Wants=apache2.service
+^D
+
+# systemctl daemon-reload
+# systemctl cat apache2       # Verify override is listed.
+# systemctl cat postgresql    # Verify override is listed.
+# systemctl stop postgresql
+# systemctl status apache2    # Verify stopped.
+# systemctl start postgresql
+# systemctl status apache2    # Verify started.
+
+
+6.1 Enabling build bot controller functionality
+
 To enable the build2 build bot controller functionality you will need to set
 the build-config option in brep-module.conf. To also enable the build
 artifacts upload functionality you will need to specify the upload-data
@@ -250,6 +306,9 @@ $ setfacl -m g:www-data:rwx /home/brep/bindist-data
 
 For sample upload handler implementations see brep/handler/upload/.
 
+
+6.2 Enabling package submission functionality
+
 To enable the package submission functionality you will need to specify the
 submit-data and submit-temp directories in brep-module.conf. Note that these
 directories must exist and have read, write, and execute permissions granted
@@ -272,6 +331,9 @@ $ edit config/submit.xhtml # Add custom form fields, adjust CSS style, etc.
 
 For sample submission handler implementations see brep/handler/submit/.
 
+
+6.3 Enabling CI request functionality
+
 To enable the CI request functionality you will need to specify the ci-data
 directory in brep-module.conf. Note that this directory must exist and have
 read, write, and execute permissions granted to the www-data user. This, for
@@ -291,52 +353,10 @@ $ edit config/ci.xhtml # Add custom form fields, adjust CSS style, etc.
 
 For sample CI request handler implementations see brep/handler/ci/.
 
-Here we assume you have setup an appropriate Apache2 virtual server. Open the
-corresponding Apache2 .conf file and add the contents of
-brep/etc/brep-apache2.conf into the <VirtualHost> section.
 
-The output content types of the brep module are application/xhtml+xml,
-text/manifest and text/plain. If you would like to make sure they get
-compressed (along with linked CSS), also add the following lines:
+6.4 Enabling GitHub CI integration
 
-        # Compress brep output (xhtml+xml) and CSS.
-        #
-        AddOutputFilterByType DEFLATE application/xhtml+xml
-        AddOutputFilterByType DEFLATE text/manifest
-        AddOutputFilterByType DEFLATE text/plain
-        AddOutputFilterByType DEFLATE text/css
-
-Restart Apache2:
-
-$ sudo systemctl restart apache2
-
-To verify, visit the repository root. To troubleshoot, see Apache logs.
-
-Now that Apache2 loads the brep module which requires PostgreSQL, it is a good
-idea to make the Apache2 service depend on PostgreSQL so that they are started
-in proper order. Here is how we can do it with systemd (with newer versions
-you can use 'systemctl edit' instead of mkdir and cat):
-
-# mkdir -p /etc/systemd/system/apache2.service.d/
-# cat >/etc/systemd/system/apache2.service.d/postgresql.conf
-[Unit]
-Requires=postgresql.service
-After=postgresql.service
-^D
-
-# mkdir -p /etc/systemd/system/postgresql.service.d/
-# cat >/etc/systemd/system/postgresql.service.d/apache2.conf
-[Unit]
-Wants=apache2.service
-^D
-
-# systemctl daemon-reload
-# systemctl cat apache2       # Verify override is listed.
-# systemctl cat postgresql    # Verify override is listed.
-# systemctl stop postgresql
-# systemctl status apache2    # Verify stopped.
-# systemctl start postgresql
-# systemctl status apache2    # Verify started.
+@@ TODO
 
 
 7. Optimize CSS
diff --git a/INSTALL-CI-DEV b/INSTALL-CI-DEV
index b8502d8..c1bd8ec 100644
--- a/INSTALL-CI-DEV
+++ b/INSTALL-CI-DEV
@@ -1,4 +1,4 @@
-This guide shows how to configure the brep module for serving the CI and
+This guide describes how to configure the brep module for serving the CI and
 build2 build bot requests and how to smoke-test it.
 
 Note that during the testing both the user and CI submission handler (executed
diff --git a/INSTALL-DEV b/INSTALL-DEV
index f023962..c197b7b 100644
--- a/INSTALL-DEV
+++ b/INSTALL-DEV
@@ -1,6 +1,7 @@
 The goal of this setup is to run the brep Apache2 modules from the development
 build while still being as close to the real deployment as possible. To this
 end, we use default, system-wide installations of both Apache2 and Postgres.
+See also INSTALL-CI-DEV and INSTALL-GITHUB-DEV.
 
 In the below instructions replace <user> with your login and www-data with the
 user under which Apache2 is running (See the "User" directive in the Apache2
diff --git a/INSTALL-GITHUB-DEV b/INSTALL-GITHUB-DEV
index 722fd8d..602b65d 100644
--- a/INSTALL-GITHUB-DEV
+++ b/INSTALL-GITHUB-DEV
@@ -1,4 +1,4 @@
-This document explains how to get GitHub webhooks (a notification that an
+This guide describes how to get GitHub webhooks (a notification that an
 event such as a push has occurred on a repository) delivered to a
 locally-running instance of brep (currently to initiate a CI job).
 
diff --git a/INSTALL-PROXY b/INSTALL-PROXY
index 418846a..2a3f3f4 100644
--- a/INSTALL-PROXY
+++ b/INSTALL-PROXY
@@ -1,4 +1,4 @@
-This guide shows how to configure the Apache2-based HTTP proxy server for
+This guide describes how to configure the Apache2-based HTTP proxy server for
 proxying HTTP(S) requests and caching the responses.
 
 Note that for security reasons most clients (curl, wget, etc) perform HTTPS