X-Git-Url: http://git.equinoxoli.org/?p=opensrf-equinox.git;a=blobdiff_plain;f=README;fp=README;h=69df0f60f27ff08cbc7c81a243d8d7fdf8d37866;hp=f2ae00bd49fba3814433664f36a641fe9b72a00a;hb=404154e0c23a7f8c8d0ab6cd0e550c8196e0320b;hpb=d3cbc373bfc5c849a4953e8066a1b61c74fb05e2 diff --git a/README b/README index f2ae00b..69df0f6 100644 --- a/README +++ b/README @@ -415,96 +415,8 @@ srfsh# request opensrf.math add 2,2 + You should receive the value `4`. -Websockets installation instructions: Option #1 Apache -------------------------------------------------------- -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`) -+ -[source, bash] ---------------------------------------------------------------------------- -sh /usr/share/doc/apache2/examples/setup-instance websockets ---------------------------------------------------------------------------- -+ -4. Remove from the main apache instance -+ -[source, bash] ---------------------------------------------------------------------------- -a2dismod websocket ---------------------------------------------------------------------------- -+ -5. Change to the directory into which you unpacked OpenSRF, then copy into - place the config files -+ -[source, bash] ---------------------------------------------------------------------------- -cd /path/to/opensrf-OSRFVERSION -cp examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/ ---------------------------------------------------------------------------- -+ -6. OPTIONAL: add these configuration variables to `/etc/apache2-websockets/envvars` - and adjust as needed. -+ -[source, bash] ---------------------------------------------------------------------------- -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. Before you can start websockets, you must install a valid SSL certificate - in `/etc/apache2/ssl/`. It is possible, but not recommended, to generate a - self-signed SSL certificate. For example, if you need to test with a self-signed - certicate on Chrome or Chromimum browsers, one workaround is to start the browser - with `--ignore-certificate-errors`. - -8. 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 ---------------------------------------------------------------------------- - -Websockets installation instructions: Option #2 Websocketd ----------------------------------------------------------- +Websockets installation instructions +------------------------------------ 1. Install websocketd (latest stable release from http://websocketd.com/) + @@ -521,6 +433,16 @@ sudo cp websocketd /usr/local/bin/ + Choose option a or b, below. + +[NOTE] +=========================================================================== +websocketd does not offer a configurable inactivity timeout, meaning +websocket client connections will persist until each client disconnects +or the service is restarted. However, a timeout can be achieved with +the use of a proxy (option 'a' below). A proxy also allows websocketd +to be exposed to web clients on port 443 instead of its internal port, +which may simplify firewall configuration. +=========================================================================== ++ a. Run websocketd as 'opensrf' + [NOTE] @@ -565,8 +487,28 @@ sudo a2enmod remoteip --------------------------------------------------------------------------- + 2. Enable remote IP settings by uncommenting and modifying as needed the -Apache configuration variables starting with RemoteIP* in the sample Apache -configuration file opensrf.conf. + Apache configuration variables starting with RemoteIP* in the sample Apache + configuration file opensrf.conf. ++ +3. Configure Apache to listen on port 7080 for HTTP and port 7443 for HTTPS + and ensure that it is not listening on ports 80 and 443, then restart Apache. ++ +4. If you didn't run `configure` with the `--with-websockets-port=443` option, + edit `/javascript/opensrf_ws.js` and `/javascript/opensrf_ws_shared.js` + and change ++ +[source, javascript] +--------------------------------------------------------------------------- +var WEBSOCKET_PORT_SSL = 7682; +--------------------------------------------------------------------------- ++ +to ++ +[source, javascript] +--------------------------------------------------------------------------- +var WEBSOCKET_PORT_SSL = 443; +--------------------------------------------------------------------------- + Optional: Using NGINX as a proxy -------------------------------- @@ -582,18 +524,14 @@ administration and network tasks. The steps should be run as the *root* Linux account, and assume that you already followed the instructions for installing WebSockets support. -1. Configure the main Apache instance to listen on port 7080 for HTTP and - port 7443 for HTTPS and ensure that it is not listening on ports 80 - and 443, then restart Apache. -+ -2. Install NGINX if not already present: +1. Install NGINX if not already present: + [source, bash] --------------------------------------------------------------------------- apt-get install nginx --------------------------------------------------------------------------- + -3. Copy the example NGINX configuration file into place and remove default. +2. Copy the example NGINX configuration file into place and remove default. + [source, bash] --------------------------------------------------------------------------- @@ -603,9 +541,9 @@ ln -s /etc/nginx/sites-available/osrf-ws-http-proxy /etc/nginx/sites-enabled/osr rm /etc/nginx/sites-enabled/default --------------------------------------------------------------------------- + -4. Edit `/etc/nginx/sites-available/osrf-ws-http-proxy` to set the location +3. Edit `/etc/nginx/sites-available/osrf-ws-http-proxy` to set the location of the SSL certificate and private key. -5. Generate a dhparam file in the directory specified in the nginx config. +4. Generate a dhparam file in the directory specified in the nginx config. + [source, bash] --------------------------------------------------------------------------- @@ -613,28 +551,12 @@ rm /etc/nginx/sites-enabled/default openssl dhparam -out /etc/apache2/ssl/dhparam.pem 2048 --------------------------------------------------------------------------- + -6. Start NGINX +5. Start NGINX + [source, bash] --------------------------------------------------------------------------- /etc/init.d/nginx start --------------------------------------------------------------------------- -+ -7. If you didn't run `configure` with the `--with-websockets-port=443` option, -edit `/javascript/opensrf_ws.js` and `/javascript/opensrf_ws_shared.js` - and change -+ -[source, javascript] ---------------------------------------------------------------------------- -var WEBSOCKET_PORT_SSL = 7682; ---------------------------------------------------------------------------- -+ -to -+ -[source, javascript] ---------------------------------------------------------------------------- -var WEBSOCKET_PORT_SSL = 443; ---------------------------------------------------------------------------- Optional: Using HAProxy as a proxy ---------------------------------- @@ -654,10 +576,7 @@ for installing WebSockets support. apt-get install haproxy --------------------------------------------------------------------------- + -2. Configure the main Apache instance to listen on port 7080 for HTTP and - port 7443 for HTTPS and ensure that it is not listening on ports 80 - and 443, then restart Apache. -3. Append the example HAProxy to `haproxy.cfg`. +2. Append the example HAProxy to `haproxy.cfg`. + [source, bash] --------------------------------------------------------------------------- @@ -665,29 +584,14 @@ cd /path/to/opensrf-OSRFVERSION cat examples/haproxy/osrf-ws-http-proxy >> /etc/haproxy/haproxy.cfg --------------------------------------------------------------------------- + -4. Edit `/etc/haproxy/haproxy.cfg` to set the location +3. Edit `/etc/haproxy/haproxy.cfg` to set the location of the PEM file containing the SSL certificate and private key. -5. Start HAProxy. +4. Start HAProxy. + [source, bash] --------------------------------------------------------------------------- /etc/init.d/haproxy start --------------------------------------------------------------------------- -+ -6. Edit `/javascript/opensrf_ws.js` and `/javascript/opensrf_ws_shared.js` - and change -+ -[source, javascript] ---------------------------------------------------------------------------- -var WEBSOCKET_PORT_SSL = 7682; ---------------------------------------------------------------------------- -+ -to -+ -[source, javascript] ---------------------------------------------------------------------------- -var WEBSOCKET_PORT_SSL = 443; ---------------------------------------------------------------------------- Troubleshooting note for Python users -------------------------------------