LP#1369169: Add websockets section to the OpenSRF README

Remove the separate README.websockets and move the contents into the primary
OpenSRF README document so that all steps are in one place.

Additional edits to the websockets instructions to detail differences made
between Ubuntu 14.04 Trusty and Debian / Ubuntu 12.04 Precise. More edits
may be necessary for Debian Jessie later?

Also, create a separate config file for Apache 2.4 that is copied into place
for Ubuntu Trusty and potentially other systems that will need it.

Signed-off-by: Ben Shum <bshum@biblio.org>
Signed-off-by: Bill Erickson <berickxx@gmail.com>

diff --git a/README b/README
index 3b2532f..4159dfa 100644 (file)
--- a/README
+++ b/README
@@ -335,6 +335,99 @@ srfsh# request opensrf.math add 2,2
 +
 You should receive the value `4`.
 
+Optional: Websockets installation instructions
+----------------------------------------------
+Websockets are new to OpenSRF 2.4+ and are required for operating the new web-based
+staff client for Evergreen.  Complete the following steps as the *root* Linux 
+account:
+
+1. Install git if not already present:
++
+[source,bash]
+---------------------------------------------------------------------------
+apt-get install git-core
+---------------------------------------------------------------------------
++
+2. Install the apache-websocket module:
++
+[source,bash]
+---------------------------------------------------------------------------
+# Use a temporary directory
+cd /tmp
+git clone https://github.com/disconnect/apache-websocket
+cd apache-websocket
+apxs2 -i -a -c mod_websocket.c
+---------------------------------------------------------------------------
++
+3. Create the websocket Apache instance (more information about this in 
+   /usr/share/doc/apache2/README.multiple-instances)
++
+.(Debian / Ubuntu Precise)
+[source,bash]
+---------------------------------------------------------------------------
+sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
+---------------------------------------------------------------------------
++
+.(Ubuntu Trusty)
+[source,bash]
+---------------------------------------------------------------------------
+sh /usr/share/doc/apache2/examples/setup-instance websockets
+---------------------------------------------------------------------------
++
+4. Remove from the main apache instance
++
+[source,bash]
+---------------------------------------------------------------------------
+a2dismod websocket
+---------------------------------------------------------------------------
++
+5. Copy into place the config files
++
+.(Debian / Ubuntu Precise)
+[source,bash]
+---------------------------------------------------------------------------
+cp /home/opensrf/OpenSRF/examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
+---------------------------------------------------------------------------
++
+.(Ubuntu Trusty)
+[source,bash]
+---------------------------------------------------------------------------
+cp /home/opensrf/OpenSRF/examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
+---------------------------------------------------------------------------
++
+6. OPTIONAL: add these configuration variables to /etc/apache2-websockets/envvars
+   and adjust as needed.
++
+---------------------------------------------------------------------------
+export OSRF_WEBSOCKET_IDLE_TIMEOUT=120
+export OSRF_WEBSOCKET_IDLE_CHECK_INTERVAL=5
+export OSRF_WEBSOCKET_CONFIG_FILE=/openils/conf/opensrf_core.xml
+export OSRF_WEBSOCKET_CONFIG_CTXT=gateway
+export OSRF_WEBSOCKET_MAX_REQUEST_WAIT_TIME=600
+---------------------------------------------------------------------------
++
+  * IDLE_TIMEOUT specifies how long we will allow a client to stay connected
+    while idle.  A longer timeout means less network traffic (from fewer
+    websocket CONNECT calls), but it also means more Apache processes are
+    tied up doing nothing.
+  * IDLE_CHECK_INTERVAL specifies how often we wake to check the idle status
+    of the connected client.
+  * MAX_REQUEST_WAIT_TIME is the maximum amount of time the gateway will
+    wait before declaring a client as idle when there is a long-running
+    outstanding request, yet no other activity is occurring.  This is
+    primarily a fail-safe to allow idle timeouts when one or more requests
+    died on the server, and thus no response was ever delivered to the gateway.
+  * CONFIG_FILE / CTXT are the standard opensrf core config options.
+
+7. After OpenSRF is up and running (or after any re-install),
+   fire up the secondary Apache instance. Errors will appear in
+   `/var/log/apache2-websockets/error.log`. Start apache2-websockets with:
++
+[source,bash]
+---------------------------------------------------------------------------
+/etc/init.d/apache2-websockets start
+---------------------------------------------------------------------------
+
 Troubleshooting note for Python users
 -------------------------------------
 

diff --git a/README.websockets b/README.websockets
deleted file mode 100644 (file)
index 15f38b1..0000000
--- a/README.websockets
+++ /dev/null
@@ -1,53 +0,0 @@
-Websockets installation instructions for Debian
-
-# TODO: Most of this can be scripted.
-
-# ! as root !
-# Perform these steps after installing OpenSRF.
-
-# install the apache-websocket module
-% cd tmp # or wherever
-% git clone https://github.com/disconnect/apache-websocket
-% cd apache-websocket
-% apxs2 -i -a -c mod_websocket.c
-
-# create the websocket Apache instance
-# see also /usr/share/doc/apache2/README.multiple-instances
-% sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
-
-# remove from the main apache instance
-% a2dismod websocket
-
-# update configs
-% cp /path/to/OpenSRF/examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
-
-# OPTIONAL: add these configuration variables to
-# /etc/apache2-websockets/envvars and adjust as needed.
-# export OSRF_WEBSOCKET_IDLE_TIMEOUT=120
-# export OSRF_WEBSOCKET_IDLE_CHECK_INTERVAL=5
-# export OSRF_WEBSOCKET_CONFIG_FILE=/openils/conf/opensrf_core.xml
-# export OSRF_WEBSOCKET_CONFIG_CTXT=gateway
-# export OSRF_WEBSOCKET_MAX_REQUEST_WAIT_TIME=600
-#
-# IDLE_TIMEOUT specifies how long we will allow a client to stay connected
-# while idle.  A longer timeout means less network traffic (from fewer
-# websocket CONNECT calls), but it also means more Apache processes are
-# tied up doing nothing.
-#
-# IDLE_CHECK_INTERVAL specifies how often we wake to check the idle status
-# of the connected client.
-#
-# MAX_REQUEST_WAIT_TIME is the maximum amount of time the gateway will
-# wait before declaring a client as idle when there is a long-running
-# outstanding request, yet no other activity is occurring.  This is
-# primarily a fail-safe to allow idle timeouts when one or more requests
-# died on the server, and thus no response was ever delivered to the gateway.
-#
-# Both specified in seconds
-#
-# CONFIG_FILE / CTXT are the standard opensrf core config options.
-
-# After OpenSRF is up and running (or after any re-install),
-# fire up the secondary Apache instance. Errors will appear in
-# /var/log/apache2-websockets/error.log
-% /etc/init.d/apache2-websockets start