======Installing OpenSRF 1.0.7======
The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) platforms. OpenSRF 1.0.7 has been tested on Debian Etch (4.0), Debian Lenny, Ubuntu Hardy Heron (8.04), and Ubuntu Intrepid Ibex (8.10).

----

In the following instructions, you are asked to perform certain steps as either the **root** user or the **opensrf** user. 

  * **Debian** To become the **root** user, issue the ''su -'' command and enter the password of the root user.
  * **Ubuntu** To become the **root** user, issue the ''sudo su -'' command and enter the password of your current user.

To switch from the **root** user to a different user, issue the ''su - <username>'' command; for example, ''su - opensrf''. Once you have become a non-root user, to become the **root** user again simply issue the ''exit'' command.

Also, in the following instructions, **/path/to/OpenSRF/** represents the path to the OpenSRF source directory.

  - As the **root** user, add the opensrf user. We set the default shell for the new user to ''/bin/bash'' to inherit a reasonable environment:<code bash>
useradd -m -s /bin/bash opensrf
passwd opensrf</code>
  - As the **opensrf** user, download and extract the source files for OpenSRF 1.0.7:<code bash>
wget http://open-ils.org/downloads/OpenSRF-1.0.7.tar.gz
tar xzf OpenSRF-1.0.7.tar.gz
</code> A new directory ''OpenSRF-1.0.7'' is created.
  - As the **root** user, install the software prerequisites using the automatic prerequisite installer. Replace //<distribution>// below with the following value for your distribution:
    * ''debian-etch'' for Debian Etch (4.0)
    * ''debian-lenny'' for Debian Lenny
    * ''ubuntu-hardy'' for Ubuntu Hardy Heron (8.04)
    * ''ubuntu-intrepid'' for Ubuntu Intrepid Ibex (8.10)<code bash>
aptitude install make
cd /path/to/OpenSRF
make -f src/extras/Makefile.install <distribution>
</code> This will install a number of packages required by OpenSRF on your system, including some Perl modules from CPAN. You can say "no" to the initial CPAN configuration prompt to allow it to automatically configure itself to download and install Perl modules from CPAN. The CPAN installer will ask you a number of times whether it should install prerequisite modules - say "yes".
  - Build OpenSRF:
    - As the **opensrf** user, configure and compile OpenSRF. You can include the ''--enable-python'' and ''--enable-java'' configure options if you want to include support for Python and Java, respectively:<code bash>
cd /path/to/OpenSRF
./configure --prefix=/openils --sysconfdir=/openils/conf
make</code>
    - As the **root** user, return to your OpenSRF build directory and install OpenSRF:<code bash>
cd /path/to/OpenSRF
make install
</code>
    - As the **root** user, add ''/openils/lib'' to the system dynamic library path and make your system recognize the newly installed libraries. For example, on Ubuntu or Debian you would perform the following steps:
      - Create a file named ''/etc/ld.so.conf.d/osrf.conf'' containing the following line:<code>
/openils/lib</code>
      - Run the following command:<code bash>
ldconfig</code>
    - Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains ''public.localhost'' for the public domain and ''private.localhost'' for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the ''/etc/hosts'' file. Here are the entries to add as root to a stock ''/etc/hosts'' file for our example domains: <code>127.0.1.2	public.localhost	public
127.0.1.3	private.localhost	private</code>
    - As the **root** user, change the ownership of the installed files to the opensrf user:<code bash>
chown -R opensrf:opensrf /openils</code>
  - As the **root** user, stop the ejabberd service:<code bash>
/etc/init.d/ejabberd stop</code> 
    * If ejabberd reports that it is already stopped, it may have run into a problem starting back at the installation stage. One possible fix is to kill any remaining ''beam'' and ''epmd'' processes, then edit ''/etc/default/ejabberd'' to hardcode a domain:<code bash>
epmd -kill
killall beam; killall beam.smp
rm /var/lib/ejabberd/*
echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd
</code>
  - As the **root** user, edit ''/etc/ejabberd/ejabberd.cfg'':
    * Change <code>{hosts, ["localhost"]}.</code> to <code>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</code>
    * Change ''{max_user_sessions, 10}.'' to ''{max_user_sessions, 1000}.''  If you see something like this instead: ''{access, max_user_sessions, [{10, all}]}.'', then change it to ''{access, max_user_sessions, [{1000, all}]}.''
    * Change all three occurrences of ''max_stanza_size'' to ''2000000''.
    * Change both occurrences of ''maxrate'' to ''500000''.
    * Comment out the ''{mod_offline'' line by placing two ''%'' signs in front.
  - As the **root** user, restart the ejabberd service to test the configuration changes and to register your users:<code bash>
/etc/init.d/ejabberd start</code>
  - On each domain, you need two Jabber users to manage the OpenSRF communications:
    * a "router" user, to whom all requests to connect to an OpenSRF service will be routed; this Jabber user must be named "router"
    * an "opensrf" user, which clients use to connect to OpenSRF services; this user can be named anything you like, but we will use "opensrf" in our examples
   - As the **root** user, register your "router" and "opensrf" ejabber users for the OpenSRF router service on each domain. The users should have different passwords on each domain. These users will correspond to your configuration in ''opensrf_core.xml'':<code bash>
# Syntax for registering a user with ejabberdctl
# ejabberdctl register <user> <domain> <password>
ejabberdctl register router private.localhost <password>
ejabberdctl register opensrf private.localhost <password>
ejabberdctl register router public.localhost <password>
ejabberdctl register opensrf public.localhost <password></code>
  - As the **opensrf** user, create the ''/openils/conf/opensrf_core.xml'' and ''/openils/conf/opensrf.xml'' configuration files from the example templates:<code bash>
cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
</code>
    - Edit ''/openils/conf/opensrf_core.xml'' to change the Jabber usernames and passwords as follows. I'm using XPath syntax on the left-hand side to indicate the position in the XML file:
      * ''/config/opensrf/username'' = opensrf
      * ''/config/opensrf/passwd'' = password for **private.localhost** opensrf user
      * ''/config/gateway/username'' = opensrf
      * ''/config/gateway/passwd'' = password for **public.localhost** opensrf user
      * ''/config/routers/router/transport'' - first entry, where ''transport/server'' == **public.localhost** :
        * ''username'' = router
        * ''password'' = password for **public.localhost** router user
      * ''/config/routers/router/transport'' - second entry, where ''transport/server'' == **private.localhost** :
        * ''username'' = router
        * ''password'' = password for **private.localhost** router user
    - We also need to specify the domains from which we'll accept and to which we'll make connections. If you are installing OpenSRF on a single server and using the "private.localhost" / "public.localhost" domains, these will already be set to the correct values. Otherwise, search and replace to match your values.
  - Edit ''/openils/conf/opensrf.xml'' to set the location of the persistent database in the ''<dbfile>'' element near the end of the file:<code bash>
<!-- Example of an app-specific setting override -->
<opensrf.persist>
  <app_settings>
    <dbfile>/tmp/persist.db</dbfile>
  </app_settings>
</opensrf.persist></code>
  - Copy ''/openils/conf/srfsh.xml.example'' to ''.srfsh.xml'' in the home directory of each user you want to use to run the srfsh command line client for testing OpenSRF, and edit ''.srfsh.xml'' as follows:
    * ''domain'' is the router hostname (following our domain examples, ''private.localhost'' will give your srfsh access to all OpenSRF services, while ''public.localhost'' will only give you access to those OpenSRF services that are publicly exposed)
    * ''username'' and ''password'' must match your ''opensrf'' ejabber user for the chosen domain
    * ''logfile'' is the full path for a log file to which that user has write access<code xml>
<?xml version="1.0"?>
<!-- This file follows the standard bootstrap config file layout found in opensrf_core.xml -->
<srfsh>
  <router_name>router</router_name>
  <domain>private.localhost</domain>
  <username>opensrf</username>
  <passwd>privsrf</passwd>
  <port>5222</port>
  <logfile>/tmp/srfsh.log</logfile>
  <loglevel>3</loglevel>
</srfsh>
</code>
  - As the **opensrf** user, set the path of the opensrf user's ''.bashrc'' file:<code>
echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc
exit</code>

=====Starting OpenSRF=====
Before starting OpenSRF, ensure that your Jabber and memcached daemons are running. As the **root** user:<code bash>
/etc/init.d/ejabberd start
/etc/init.d/memcached start</code>

Starting OpenSRF with the ''start_all'' option starts the OpenSRF router, Perl services, and C services. As the **opensrf** user, start OpenSRF:<code bash>
osrf_ctl.sh -l -a start_all</code>
    * If you receive the error message **bash: osrf_ctl.sh: command not found**, then your environment variable **PATH** does not include the ''/openils/bin'' directory; this should have been set by ''.bashrc'' when you logged in as the ''opensrf'' user, but you can manually set it using the following command:<code bash>export PATH=$PATH:/openils/bin
</code>

=====Testing connections to OpenSRF =====
Once you have installed and started OpenSRF, test your connection to OpenSRF via ''srfsh'':
  - Start ''srfsh'' and try calling the ''add'' method on the OpenSRF math service:<code>
/openils/bin/srfsh
srfsh#  request opensrf.math add 2 2
</code> You should see a result like:<code>
Received Data: 4

------------------------------------
Request Completed Successfully
Request Time in seconds: 0.007519
------------------------------------
srfsh# </code> If this does not work, it's time to do some troubleshooting. Please do not make any significant changes to your configuration. If you have followed the entire set of installation steps listed here closely, you are probably extremely close to a working system. Gather your configuration files and log files in ''/openils/var/log'' and contact the [[http://open-ils.org/listserv.php|Evergreen development mailing list]] for assistance before making any drastic changes to your system configuration.

=====Stopping OpenSRF=====
  - As the **opensrf** user, stop OpenSRF:<code>
osrf_ctl.sh -l -a stop_all
</code>