** The *user* Linux account is the account that you use to log onto the
Linux system as a regular user.
** The *root* Linux account is an account that has system administrator
- privileges. On Debian and Fedora you can switch to this account from
+ privileges. On Debian you can switch to this account from
your *user* account by issuing the `su -` command and entering the
password for the *root* account when prompted. On Ubuntu you can switch
to this account from your *user* account using the `sudo su -` command
of installing OpenSRF. You can switch to this account from the *root*
account by issuing the `su - opensrf` command.
+Download and unpack the code
+----------------------------
+
+Issue the following commands as the *user* Linux account.
+
+1. Acquire a stable release tarball from https://evergreen-ils.org/opensrf-downloads/
++
+[source, bash]
+------------------------------------------------------------------------------
+wget https://evergreen-ils.org/downloads/opensrf-OSRFVERSION.tar.gz
+------------------------------------------------------------------------------
++
+[NOTE]
+Developers can find the full source code at the OpenSRF Git repository:
+http://git.evergreen-ils.org/?p=OpenSRF.git
++
+2. Unpack the tarball, and move into that directory:
++
+[source, bash]
+------------------------------------------------------------------------------
+tar -xvf opensrf-OSRFVERSION.tar.gz
+cd opensrf-OSRFVERSION/
+------------------------------------------------------------------------------
+
Installing prerequisites
------------------------
* `debian-jessie` for Debian 8.0
* `debian-wheezy` for Debian 7.0
- * `ubuntu-precise` for Ubuntu 12.04
* `ubuntu-trusty` for Ubuntu 14.04
* `ubuntu-xenial` for Ubuntu 16.04
- * `fedora` for Fedora 17 and later
Patches and suggestions for improvement from users of these distributions,
or others, are welcome!
[NOTE]
Skip this section if you are using an official release tarball downloaded
-from http://evergreen-ils.org/downloads
+from https://evergreen-ils.org/opensrf-downloads/
Developers working directly with the source code from the Git repository,
rather than an official release tarball, must install some extra packages
You can add the `--enable-python` option to the configure command
to build Python support and `--enable-java` for Java support.
+If you are planning on proxying WebSockets traffic (see below), you
+can add `--with-websockets-port=443` to specify that WebSockets traffic
+will be going through port 443. Without that option, the default port
+is 7682.
+
Installation instructions
-------------------------
Add `<PREFIX>/lib/` to the system's dynamic library path, and then run
`ldconfig` as the *root* Linux account.
-On Debian, Ubuntu, and Fedora systems, run the following commands as the *root*
+On Debian and Ubuntu systems, run the following commands as the *root*
Linux account:
.Adjusting the system dynamic library path
1. Stop ejabberd before making any changes to its configuration by issuing the
following command as the *root* Linux account:
+
-.(Debian / Ubuntu 14.04) Stopping ejabberd
+.(Debian / Ubuntu Trusty) Stopping ejabberd
[source, bash]
---------------------------------------------------------------------------
/etc/init.d/ejabberd stop
---------------------------------------------------------------------------
+
-.(Fedora / Ubuntu 16.04) Stopping ejabberd
+.(Ubuntu Xenial) Stopping ejabberd
[source, bash]
---------------------------------------------------------------------------
systemctl stop ejabberd.service
+
2. Edit the ejabberd config file.
+
-(Debian Wheezy / Ubuntu 14.04) Ejabberd 2.x.x::
+(Debian Wheezy / Ubuntu Trusty) Ejabberd 2.x.x::
Open `/etc/ejabberd/ejabberd.cfg` and make the following
changes:
a. Define your public and private domains in the `hosts` directive. For
{hosts, ["localhost", "private.localhost", "public.localhost"]}.
---------------------------------------------------------------------------
+
- b. Change all `max_stanza_size` values to 2000000
- c. Change all `maxrate` values to 500000
- d. Increase the `max_user_sessions` value to 10000
- e. Comment out the `mod_offline` directive
+ b. Change all `maxrate` values to 500000
+ c. Increase the `max_user_sessions` value to 10000
+ d. Comment out the `mod_offline` directive
+
(Debian Jessie) Ejabberd 13.x and 14.x::
Open `/etc/ejabberd/ejabberd.yml` and make the following
- "public.localhost"
---------------------------------------------------------------------------
+
- b. Change all `max_stanza_size` values to 2000000
- c. Change `shaper:` `normal` and `fast` values to 500000
- d. Increase the `max_user_sessions:` `all:` value to 10000
- e. Comment out the `mod_offline` directive
+ b. Change `shaper:` `normal` and `fast` values to 500000
+ c. Increase the `max_user_sessions:` `all:` value to 10000
+ d. Comment out the `mod_offline` directive
+
-----------------------
##mod_offline:
##access_max_user_messages: max_user_offline_messages
-----------------------
+
-(Ubuntu 16.04) Ejabberd 16.x::
+(Ubuntu Xenial) Ejabberd 16.x::
Open `/etc/ejabberd/ejabberd.yml` and make the following
changes:
a. Define your public and private domains in the `hosts` directive. For
- "public.localhost"
---------------------------------------------------------------------------
+
- b. Change all `max_stanza_size` values to 2000000
- c. Change `auth_password_format` to plain
- d. Change `shaper:` `normal` and `fast` values to 500000
- e. Increase the `max_user_sessions:` `all:` value to 10000
- f. Comment out the `mod_offline` directive
+ b. Change `auth_password_format` to plain
+ c. Change `shaper:` `normal` and `fast` values to 500000
+ d. Increase the `max_user_sessions:` `all:` value to 10000
+ e. Comment out the `mod_offline` directive
+
-----------------------
##mod_offline:
+
3. Restart the ejabberd server to make the changes take effect:
+
-.(Debian / Ubuntu 14.04) Starting ejabberd
+.(Debian / Ubuntu Trusty) Starting ejabberd
[source, bash]
---------------------------------------------------------------------------
/etc/init.d/ejabberd start
---------------------------------------------------------------------------
+
-.(Fedora / Ubuntu 16.04) Starting ejabberd
+.(Ubuntu Xenial) Starting ejabberd
[source, bash]
---------------------------------------------------------------------------
systemctl start ejabberd.service
3. Create the websocket Apache instance (more information about this in
`/usr/share/doc/apache2/README.multiple-instances`)
+
-.(Debian / Ubuntu Precise)
+.(Debian Wheezy)
[source, bash]
---------------------------------------------------------------------------
sh /usr/share/doc/apache2.2-common/examples/setup-instance websockets
---------------------------------------------------------------------------
+
-.(Ubuntu Trusty)
+.(Debian Jessie / Ubuntu Trusty / Xenial)
[source, bash]
---------------------------------------------------------------------------
sh /usr/share/doc/apache2/examples/setup-instance websockets
a2dismod websocket
---------------------------------------------------------------------------
+
-5. Copy into place the config files
+5. Change to the directory into which you unpacked OpenSRF, then copy into
+ place the config files
+
-.(Debian / Ubuntu Precise)
+.(Debian Wheezy)
[source, bash]
---------------------------------------------------------------------------
+cd /path/to/opensrf-OSRFVERSION
cp examples/apache2/websockets/apache2.conf /etc/apache2-websockets/
---------------------------------------------------------------------------
+
-.(Ubuntu Trusty)
+.(Debian Jessie / Ubuntu Trusty / Xenial)
[source, bash]
---------------------------------------------------------------------------
+cd /path/to/opensrf-OSRFVERSION
cp examples/apache_24/websockets/apache2.conf /etc/apache2-websockets/
---------------------------------------------------------------------------
+
/etc/init.d/apache2-websockets start
---------------------------------------------------------------------------
+Optional: Using NGINX as a proxy
+--------------------------------
+NGINX can be used to proxy HTTP, HTTPS, and WebSockets traffic. Among other
+reasons, this can be useful for Evergreen setups that want to have both
+HTTPS and secure WebSockets traffic both go through port 443 while using
+two Apache instances (one for the WebSockets gateway and one for the more
+memory-intensive TPAC pages).
+
+The following instructions are a guide for setting this up on Debian
+and Ubuntu systems, but expect general familiarity with various system
+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:
++
+[source, bash]
+---------------------------------------------------------------------------
+apt-get install nginx
+---------------------------------------------------------------------------
++
+3. Copy the example NGINX configuration file into place and remove default.
++
+[source, bash]
+---------------------------------------------------------------------------
+cd /path/to/opensrf-OSRFVERSION
+cp examples/nginx/osrf-ws-http-proxy /etc/nginx/sites-available/
+ln -s /etc/nginx/sites-available/osrf-ws-http-proxy /etc/nginx/sites-enabled/osrf-ws-http-proxy
+rm /etc/nginx/sites-enabled/default
+---------------------------------------------------------------------------
++
+4. Edit `/etc/nginx/sites-available/osrf-ws-http-proxy` to set the location
+ of the SSL certificate and private key.
+5. Start NGINX
++
+[source, bash]
+---------------------------------------------------------------------------
+/etc/init.d/nginx start
+---------------------------------------------------------------------------
++
+6. If you didn't run `configure` with the `--with-websockets-port=443` option,
+edit `<PREFIX>/javascript/opensrf_ws.js` and `<PREFIX>/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
+----------------------------------
+HAProxy can also be used to proxy HTTP, HTTPS, and WebSockets traffic
+as an alternative to NGINX.
+
+The following instructions are a guide for setting this up on Debian
+and Ubuntu systems, but expect general familiarity with various system
+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. Install HAProxy if not already present:
++
+[source, bash]
+---------------------------------------------------------------------------
+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`.
++
+[source, bash]
+---------------------------------------------------------------------------
+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
+ of the PEM file containing the SSL certificate and private key.
+5. Start HAProxy.
++
+[source, bash]
+---------------------------------------------------------------------------
+/etc/init.d/haproxy start
+---------------------------------------------------------------------------
++
+6. Edit `<PREFIX>/javascript/opensrf_ws.js` and `<PREFIX>/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
-------------------------------------
projects / opensrf-equinox.git / blobdiff