LP#1369169: Add websockets section to the OpenSRF README

[opensrf-equinox.git] / README

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
 -------------------------------------