README

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