README

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