README

   1 README for OpenSRF 2.0.0
   2 ============================
   3
   4 Installing prerequisites:
   5 -------------------------
   6
   7 OpenSRF has a number of prerequisite packages that must be installed
   8 before you can successfully configure, compile, and install OpenSRF.
   9 On Debian and Ubuntu, the easiest way to install these prerequisites
  10 is to use the Makefile.install prerequisite installer for Evergreen.
  11
  12 Issue the following commands as the root user to install prerequisites
  13 using the Makefile.install prerequisite installer, substituting your
  14 operating system identifier for <osname> below:
  15
  16 ---------------------------------------------------------------------------
  17 aptitude install make
  18 make -f src/extras/Makefile.install <osname>
  19 ---------------------------------------------------------------------------
  20
  21 Well-tested values for <osname> include:
  22
  23   * `debian-lenny` for Debian 5.0
  24   * `debian-squeeze` for Debian 6.0.0
  25   * `ubuntu-hardy` for Ubuntu 8.04
  26   * `ubuntu-lucid` for Ubuntu 10.04
  27   * `fedora15` for Fedora 15
  28
  29 Less-tested values for <osname> include:
  30
  31   * `centos` for CentOS 5
  32   * `rhel` for Red Hat Enterprise Linux 5
  33
  34 Patches and suggestions for improvement from users of these distributions,
  35 or others, are welcome!
  36
  37 When the prerequisite installer reaches the Perl module stage, you may
  38 be prompted for configuration of Comprehensive Perl Archive Network (CPAN)
  39 on your server. You can generally accept the defaults by pressing <return>
  40 for all of the prompts, except for the country configuration.
  41
  42 [NOTE]
  43 If you are installing this using a copy of the source code that was
  44 checked out directly from the OpenSRF Subversion repository rather
  45 than from a downloaded release of the source code, there are a few
  46 additional prerequisite tools and steps that you will need to follow.
  47 See "Developer instructions" at the bottom of the file.
  48
  49 Configuration and compilation instructions:
  50 -------------------------------------------
  51
  52 Use the `configure` command to configure OpenSRF, and the `make` command to
  53 build OpenSRF. The default installation prefix (PREFIX) for OpenSRF is
  54 `/opensrf/`.
  55
  56 If you are building OpenSRF for Evergreen, pass the `--prefix` and
  57 `--sysconfdir` options as follows:
  58
  59 ---------------------------------------------------------------------------
  60 ./configure --prefix=/openils --sysconfdir=/openils/conf
  61 make
  62 ---------------------------------------------------------------------------
  63
  64 By default, OpenSRF includes C, Perl, and JavaScript support.
  65 You can add the `--enable-python` option to the configure command
  66 to build Python support, and `--enable-java` for Java support.
  67
  68 Installation instructions:
  69 --------------------------
  70
  71 Once you have configured and compiled OpenSRF, issue the following
  72 command as the root user to install OpenSRF:
  73
  74 ---------------------------------------------------------------------------
  75 make install
  76 ---------------------------------------------------------------------------
  77
  78 This will install OpenSRF in the prefix directory that you specified in the
  79 configuration step. This will also install example configuration files that
  80 you can use as templates for your own configuration files.
  81
  82 Create and set up the opensrf Unix user environment:
  83 ----------------------------------------------------
  84
  85 This user is used to start and stop all OpenSRF processes, and must own all
  86 files contained in the PREFIX directory hierarchy. Issue the following
  87 commands as root to create the `opensrf` user and set up its environment,
  88 substituting <PREFIX> with the value you passed to `--prefix` in your
  89 configure command:
  90
  91 ---------------------------------------------------------------------------
  92 # useradd -m -s /bin/bash opensrf
  93 # echo "export PATH=\$PATH:/<PREFIX>/bin" >> /home/opensrf/.bashrc
  94 # passwd opensrf
  95 # chown -R opensrf:opensrf /<PREFIX>
  96 ---------------------------------------------------------------------------
  97
  98 Define your public and private OpenSRF domains:
  99 -----------------------------------------------
 100
 101 For security purposes, OpenSRF uses Jabber domains to separate services
 102 into public and private realms. Throughout these instructions, we will use
 103 the example domains `public.localhost` and `private.localhost`.
 104
 105 On a single-server system, the easiest way to define public and private
 106 domains is to define separate hostnames by adding entries to the `/etc/hosts`
 107 file. Here are entries that you could make to a stock `/etc/hosts` file for our
 108 example domains:
 109
 110 ---------------------------------------------------------------------------
 111 127.0.1.2       public.localhost        public
 112 127.0.1.3       private.localhost       private
 113 ---------------------------------------------------------------------------
 114
 115 Adjust the system dynamic library path:
 116 ---------------------------------------
 117
 118 Add `<PREFIX>/lib/` to the system's dynamic library path, and then run
 119 `ldconfig` as root.
 120
 121 On Debian and Ubuntu systems, run the following commands as root:
 122
 123 ---------------------------------------------------------------------------
 124 # echo <PREFIX>/lib > /etc/ld.so.conf.d/opensrf.conf
 125 # ldconfig
 126 ---------------------------------------------------------------------------
 127
 128 On most other systems, you can add these entries to `/etc/ld.so.conf`, or
 129 create a file within the `/etc/ld.so.conf.d/` directory, and then run
 130 `ldconfig` as root.
 131
 132 Configure the ejabberd server:
 133 ------------------------------
 134
 135 OpenSRF requires an XMPP (Jabber) server. For performance reasons, ejabberd is
 136 the Jabber server of choice for the OpenSRF project. In most cases, you only
 137 have to make a few changes to the default `ejabberd.cfg` file to make ejabberd
 138 work for OpenSRF.
 139
 140 1. Stop ejabberd before making any changes to its configuration by issuing the
 141 following command as root:
 142 +
 143 ---------------------------------------------------------------------------
 144 # /etc/init.d/ejabberd stop
 145 ---------------------------------------------------------------------------
 146 +
 147 2. Open `/etc/ejabberd/ejabberd.cfg` and make the following
 148 changes:
 149   a. Define your public and private domains in the `hosts` directive. For
 150    example:
 151 +
 152 ---------------------------------------------------------------------------
 153 {hosts, ["private.localhost", "public.localhost"]}
 154 ---------------------------------------------------------------------------
 155 +
 156   b. Comment out the `mod_offline` directive
 157   c. Increase the `max_user_sessions` value to 1000
 158   d. Change all `max_stanza_size` values to 2000000
 159   e. Change all `maxrate` values to 500000
 160 +
 161 3. Restart the ejabberd server to make the changes take effect:
 162 ---------------------------------------------------------------------------
 163 # /etc/init.d/ejabberd start
 164 ---------------------------------------------------------------------------
 165
 166 Create the OpenSRF Jabber users:
 167 --------------------------------
 168
 169 On each domain, you need two Jabber users to manage the OpenSRF communications:
 170
 171   * a `router` user, to whom all requests to connect to an OpenSRF service
 172     will be routed; this Jabber user must be named `router`
 173   * an `opensrf` user, which clients use to connect to OpenSRF services; this
 174     user can be named anything you like
 175
 176 Create the Jabber users by issuing the following commands as root. Substitute
 177 <password> for your chosen passwords for each user respectively:
 178
 179 ---------------------------------------------------------------------------
 180 # ejabberdctl register router private.localhost <password>
 181 # ejabberdctl register opensrf private.localhost <password>
 182 # ejabberdctl register router public.localhost <password>
 183 # ejabberdctl register opensrf public.localhost <password>
 184 ---------------------------------------------------------------------------
 185
 186 Update the OpenSRF configuration files:
 187 ---------------------------------------
 188
 189 There are two critical files that you must update to make OpenSRF work.
 190 SYSCONFDIR is `/opensrf/etc` by default, or the value that you passed to
 191 `--sysconfdir` during the configuration phase:
 192
 193   * `SYSCONFDIR/opensrf.xml` - this file lists the services that this
 194     OpenSRF installation supports; if you create a new OpenSRF service,
 195     you need to add it to this file.
 196       * The `<hosts>` element at the bottom of the file lists the services
 197         that should be started for each hostname. You can force the system
 198         to use `localhost`, so in most cases you will leave this section
 199         as-is.
 200
 201   * `SYSCONFDIR/opensrf_core.xml` - this file lists the Jabber connection
 202     information that will be used for the system, as well as determining
 203     logging verbosity and defining which services will be exposed on the
 204     HTTP gateway. There are four username/password pairs to update in this
 205     file:
 206       1. `<config><opensrf>` = use the private Jabber `opensrf` user
 207       2. `<config><gateway>` = use the public Jabber `opensrf` user
 208       3. `<config><routers><router>` = use the public Jabber `router` user
 209       4. `<config><routers><router>` = use the private Jabber `router` user
 210
 211 You should also create a `.srfsh.xml` file in the home directory of each user
 212 that you want to enable to use the srfsh to communicate with OpenSRF services.
 213
 214 Copy `SYSCONFDIR/srfsh.xml.example` to `~/.srfsh.xml` and update the password
 215 to match the one for your Jabber `opensrf` user with the private.localhost
 216 domain.
 217
 218 Starting and stopping OpenSRF services:
 219 ---------------------------------------
 220
 221 To start all OpenSRF services with a hostname of `localhost`, issue the
 222 following command as the opensrf user:
 223
 224 ---------------------------------------------------------------------------
 225 $ osrf_ctl.sh -l -a start_all
 226 ---------------------------------------------------------------------------
 227
 228 To stop all OpenSRF services with a hostname of `localhost`, issue the
 229 following command as the opensrf user:
 230
 231 [source,bash]
 232 ---------------------------------------------------------------------------
 233 $ osrf_ctl.sh -l -a stop_all
 234 ---------------------------------------------------------------------------
 235
 236 Testing the default OpenSRF services:
 237 -------------------------------------
 238
 239 By default, OpenSRF ships with an `opensrf.math` service that performs basic
 240 calculations involving two integers. Once you have started the OpenSRF
 241 services, start srfsh and issue the following request:
 242
 243 ---------------------------------------------------------------------------
 244 srfsh# request opensrf.math add 2,2
 245 ---------------------------------------------------------------------------
 246
 247 You should receive the value `4`.
 248
 249 Troubleshooting note for Python users:
 250 --------------------------------------
 251
 252 If you are running a Python client and trying to connect to OpenSRF running on
 253 localhost rather than a hostname that can be resolved via DNS, you will
 254 probably receive exceptions about `dns.resolver.NXDOMAIN`. If this happens,
 255 you need to install the `dnsmasq` package, configure it to serve up a DNS
 256 entry for localhost, and point your local DNS resolver to `dnsmasq`. For example,
 257 on Ubuntu you can issue the following commands as root:
 258
 259 ---------------------------------------------------------------------------
 260 # aptitude install dnsmasq
 261 # /etc/init.d/dnsmasq restart
 262 ---------------------------------------------------------------------------
 263
 264 Then edit `/etc/resolv.conf` and ensure that `nameserver 127.0.0.1` is the
 265 first entry in the file.
 266
 267 Developer instructions:
 268 -----------------------
 269
 270 Developers working directly with the source code from the Subversion
 271 repository will also need to install some extra packages and perform
 272 one more step before they can proceed with the `./configure` step.
 273
 274 Install the following packages:
 275
 276   * autoconf
 277   * automake
 278   * libtool
 279
 280 Run the following command in the source directory to generate the configure
 281 script and Makefiles:
 282
 283 ---------------------------------------------------------------------------
 284 $ ./autogen.sh
 285 ---------------------------------------------------------------------------
 286
 287 Getting help:
 288 -------------
 289
 290 Need help installing or using OpenSRF? Join the mailing lists at
 291 http://evergreen-ils.org/listserv.php or contact us on the Freenode
 292 IRC network on the #evergreen channel.