From a354bf8c3deff1e9b182ae705787973b8cbfa3d7 Mon Sep 17 00:00:00 2001
From: Steve Sheppard <ssheps@gmail.com>
Date: Thu, 18 Nov 2010 12:57:12 -0500
Subject: [PATCH] more updates to bring into line with a real installation
attempt;
---
1.6/admin/serversideinstallation.xml | 3657 +++++++++++++++++-----------------
1 file changed, 1836 insertions(+), 1821 deletions(-)
diff --git a/1.6/admin/serversideinstallation.xml b/1.6/admin/serversideinstallation.xml
index ab9281de85..074da346c6 100644
--- a/1.6/admin/serversideinstallation.xml
+++ b/1.6/admin/serversideinstallation.xml
@@ -1,1821 +1,1836 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter xml:id="serversideinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
- <info>
- <title>Server-side Installation of Evergreen Software</title>
- <abstract>
- <para>This section describes installation of the Evergreen server-side software and its associated components.
- Installation, configuration, testing and verification
- of the software is straightforward if you follow some simple directions.</para>
- </abstract>
- </info>
- <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
- stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
- installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
- system.</para>
- <para>The current version of the Evergreen server-side software runs as a native application on any of several
- well-known <systemitem class="osname">Linux</systemitem> distributions
- (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
- It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
- operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
- Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
- installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
- <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
- <application>"VirtualBox"</application>, or <application>"VMware"</application>, or
- <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>
- environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
- systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
- <application>"VMware"</application>). More information on virtualized environments can be found in
- <xref linkend="serversideinstallation-virtual"/>.</para>
- <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
- <para>The Evergreen server-side software has dependencies on particular versions of certain major software
- sub-components. Successful installation of Evergreen software requires that software versions agree with those
- listed here:</para>
- <table xml:id="serversideinstall-software-dependencies">
- <title>Evergreen Software Dependencies</title>
- <indexterm>
- <primary>Evergreen software dependencies</primary>
- </indexterm>
- <tgroup align="left" cols="3" colsep="1" rowsep="1">
- <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
- <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
- <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
- <thead>
- <row>
- <entry>Evergreen</entry>
- <entry>OpenSRF</entry>
- <entry>PostgreSQL</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1.6.1.x</entry>
- <entry>1.4.0</entry>
- <entry>8.2 / 8.3</entry>
- </row>
- <row>
- <entry>1.6.0.x</entry>
- <entry>1.2</entry>
- <entry>8.2 / 8.3</entry>
- </row>
- <row>
- <entry>1.4.x</entry>
- <entry>1.0</entry>
- <entry>8.1 / 8.2</entry>
- </row>
- <row>
- <entry>1.2.x</entry>
- <entry>0.9</entry>
- <entry>8.1 / 8.2</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <section xml:id="serversideinstallation-all">
- <title>Installing Server-Side Software</title>
- <para>This section describes the installation of the major components of Evergreen server-side software.</para>
- <para>As far as possible, you should perform the following steps in the exact order given since the
- success of many steps relies on the successful completion of earlier steps. You should make backup
- copies of files and environments when you are instructed to do so. In the event of installation problems
- those copies can allow you to back out of a step gracefully and resume the installation from a known
- state. See <xref linkend="backingup"/> for further information.</para>
- <para>Of course, after you successfully complete and test the entire Evergreen installation you should
- take a final snapshot backup of your system(s). This can be the first in the series of regularly
- scheduled system backups that you should probably also begin.</para>
- <section xml:id="serversideinstallation-opensrf">
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>installation</secondary>
- </indexterm>
- <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or
- <systemitem class="osname">Debian</systemitem></title>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Debian</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Ubuntu</secondary>
- </indexterm>
- <para>This section describes the installation of the latest version of the Open Service Request
- Framework (OpenSRF), a major component of the Evergreen server-side software, on
- <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
- systems. Evergreen software is integrated with and depends on the OpenSRF software
- system.</para>
- <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
- properly installed and configured. Do not continue with any further Evergreen installation steps
- until you have verified that OpenSRF has been successfully installed.</para>
- <note>
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
- platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch
- (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and
- <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>
- <para>In the following instructions, you are asked to perform certain steps as either
- the <systemitem class="username">root</systemitem> user, the
- <systemitem class="username">opensrf</systemitem> user, or the
- <systemitem class="username">postgres</systemitem> user.</para>
- <itemizedlist>
- <listitem>
- <para><systemitem class="osname">Debian</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- <listitem>
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>sudo su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- </itemizedlist>
- <para>To switch from the <systemitem class="username">root</systemitem> user to a
- different user, issue the command <command>su - USERNAME</command>. For example, to
- switch from the <systemitem class="username">root</systemitem> user to the
- <systemitem class="username">opensrf</systemitem> user, issue the command
- <command>su - opensrf</command>. Once you have become a non-root user, to become
- the <systemitem class="username">root</systemitem> user again, simply issue the command
- <command>exit</command>.</para>
- </note>
- <procedure>
- <step>
- <title>Add the OpenSRF User</title>
- <para>As the <systemitem class="username">root</systemitem> user, add the
- opensrf user to the system. The default shell for the new user is automatically
- set to <command>/bin/bash</command> to inherit a reasonable environment:</para>
- <screen>
- <userinput>useradd -m -s /bin/bash opensrf</userinput>
- <userinput>passwd opensrf</userinput>
- </screen>
- </step>
- <step>
- <title>Download and Unpack Latest OpenSRF Version</title>
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>download</secondary>
- </indexterm>
- <para>As the <systemitem class="username">opensrf</systemitem> user, change to
- the directory <filename class="directory">/home/opensrf</filename> then download
- and extract the latest version of OpenSRF. The latest version can be found here:
- <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>
- <screen>
- <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
- <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>
- <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>
- </screen>
- <para>The new directory
- <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>
- </step>
- <step>
- <title>Install Prerequisites to Build OpenSRF</title>
- <para>In this section you will install and configure a set of prerequisites that will be
- used to build OpenSRF. In a following step you will actually build the OpenSRF software
- using the <command>make</command> utility.</para>
- <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
- below to build the prerequisites from the software distribution that you just downloaded
- and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
- example with the keyword corresponding to the name of one of the
- <systemitem class="osname">Linux</systemitem> distributions listed in the following
- distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
- For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
- enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
- <screen>
- <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
- <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
- </screen>
- <table xml:id="serversideinstallation-keywords-opensrf">
- <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colnum="1" colwidth="1.0*"/>
- <colspec colnum="2" colwidth="3.0*"/>
- <thead>
- <row>
- <entry>Keyword</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>debian-etch</entry>
- <entry>for Debian "Etch" (4.0)</entry>
- </row>
- <row>
- <entry>debian-lenny</entry>
- <entry>for Debian "Lenny" (5.0)</entry>
- </row>
- <row>
- <entry>ubuntu-hardy</entry>
- <entry>for Ubuntu "Hardy Heron" (8.04)</entry>
- </row>
- <row>
- <entry>ubuntu-karmic</entry>
- <entry>for Ubuntu "Karmic Koala" (9.10)</entry>
- </row>
- <row>
- <entry>ubuntu-lucid</entry>
- <entry>for Ubuntu "Lucid Lynx" (10.04)</entry>
- </row>
- <row>
- <entry>fedora13</entry>
- <entry>for Fedora "Goddard" (13)</entry>
- </row>
- <row>
- <entry>centos</entry>
- <entry>for Centos</entry>
- </row>
- <row>
- <entry>rhel</entry>
- <entry>for RHEL</entry>
- </row>
- <row>
- <entry>gentoo</entry>
- <entry>for Gentoo</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>This will install a number of packages on the system that are required by OpenSRF,
- including some Perl modules from CPAN. You can say <literal>No</literal> 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 <literal>Yes</literal>.</para>
- </step>
- <step>
- <title>Build OpenSRF</title>
- <para>In this section you will configure and build the OpenSRF
- components that support other Evergreen services.</para>
- <substeps>
- <step>
- <title>Configure OpenSRF</title>
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>configure</secondary>
- </indexterm>
- <para>As the <systemitem class="username">opensrf</systemitem>
- user, return to the OpenSRF build directory and use the
- <command>configure</command> utility to prepare for the next
- step of compiling and linking the software. If you wish to
- include support for Python and Java, add the configuration
- options <option>--enable-python</option> and
- <option>--enable-java</option>, respectively:</para>
- <screen>
- <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
- <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
- <userinput>make</userinput>
- </screen>
- </step>
- <step>
- <title>Compile, Link and Install OpenSRF</title>
- <para>As the <systemitem class="username">root</systemitem>
- user, return to the OpenSRF build directory and use the
- <command>make</command> utility to compile, link and install
- OpenSRF:</para>
- <screen>
- <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
- <userinput>make install</userinput>
- </screen>
- </step>
- <step>
- <title>Update the System Dynamic Library Path</title>
- <para>You must update the system dynamic library path to force
- your system to recognize the newly installed libraries. As the
- <systemitem class="username">root</systemitem> user, do this by
- creating the new file
- <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
- new library path, then run the command
- <command>ldconfig</command> to automatically read the file and
- modify the system dynamic library path:</para>
- <screen>
- <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>
- <userinput>ldconfig</userinput>
- </screen>
- </step>
- <step>
- <title>Define Public and Private OpenSRF Domains</title>
- <para>For security purposes, OpenSRF uses Jabber domains to separate services
- into public and private realms. On a single-server system the easiest way to
- define public and private OpenSRF domains is to define separate host names by
- adding entries to the file <filename>/etc/hosts</filename>.</para>
- <para>In the following steps we will use the example domains
- <systemitem class="domainname">public.localhost</systemitem> for the public
- domain and <systemitem class="domainname">private.localhost</systemitem>
- for the private domain. In an upcoming step, you will configure two special
- <systemitem class="service">ejabberd</systemitem> users
- to handle communications for these two domains.</para>
- <para>As the <systemitem class="username">root</systemitem> user, edit the file
- <filename>/etc/hosts</filename> and add the following example domains:</para>
- <indexterm>
- <primary>Jabber</primary>
- </indexterm>
- <screen>
- <userinput>127.0.1.2 public.localhost public</userinput>
- <userinput>127.0.1.3 private.localhost private</userinput>
- </screen>
- </step>
- <step>
- <title>Change File Ownerships</title>
- <para>Finally, as the <systemitem class="username">root</systemitem>
- user, change the ownership of all files installed in the
- directory <filename class="directory">/openils</filename> to the
- user <systemitem class="username">opensrf</systemitem>:</para>
- <screen>
- <userinput>chown -R opensrf:opensrf /openils</userinput>
- </screen>
- </step>
- </substeps>
- </step>
- <step>
- <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
- <indexterm>
- <primary>ejabberd</primary>
- </indexterm>
- <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
- you must stop that service. As the <systemitem class="username">root</systemitem> user,
- execute the following command to stop the service:</para>
- <screen>
- <userinput>/etc/init.d/ejabberd stop</userinput>
- </screen>
- <para>If <systemitem class="service">ejabberd</systemitem> reports that it
- is already stopped, there may have been a problem when it started back
- in the installation step. If there are any remaining daemon processes such as
- <systemitem class="daemon">beam</systemitem> or
- <systemitem class="daemon">epmd</systemitem>
- you may need to perform the following commands to kill them:</para>
- <screen>
- <userinput>epmd -kill</userinput>
- <userinput>killall beam; killall beam.smp</userinput>
- <userinput>rm /var/lib/ejabberd/*</userinput>
- <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
- </screen>
- </step>
- <step>
- <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
- <para>You must make several configuration changes for the
- <systemitem class="service">ejabberd</systemitem> service before
- it is started again.
- As the <systemitem class="username">root</systemitem> user, edit the file
- <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
- <itemizedlist>
- <listitem>
- <para>Change the line:
- <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>
- to:
- <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>
- </listitem>
- <listitem>
- <para>Change the line:
- <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to:
- <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>
- <para>If the line looks something like this:
- <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>
- then change it to:
- <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>
- </listitem>
- <listitem>
- <para>Change all three occurrences of: <literal>max_stanza_size</literal>
- to: <literal>2000000</literal>.</para>
- </listitem>
- <listitem>
- <para>Change both occurrences of: <literal>maxrate</literal> to:
- <literal>500000</literal>.</para>
- </listitem>
- <listitem>
- <para>Comment out the line <literal>{mod_offline, []}</literal>
- by placing two <literal>%</literal> comment signs in front.</para>
- </listitem>
- </itemizedlist>
- </step>
- <step xml:id="serversideinstallation-opensrf-continued">
- <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
- <para>As the <systemitem class="username">root</systemitem> user, restart the
- <systemitem class="service">ejabberd</systemitem> service to test the
- configuration changes and to register your users:</para>
- <screen>
- <userinput>/etc/init.d/ejabberd start</userinput>
- </screen>
- </step>
- <step>
- <title>Register <systemitem class="username">router</systemitem> and
- <systemitem class="username">ejabberd</systemitem> users</title>
- <para>The two <systemitem class="service">ejabberd</systemitem> users
- <systemitem class="username">router</systemitem> and
- <systemitem class="username">opensrf</systemitem> must be registered
- and configured to manage OpenSRF router service and communications
- for the two domains <literal>public.localhost</literal> and
- <literal>private.localhost</literal>
- that you added to the file <filename>/etc/hosts</filename>
- in a previous step:</para>
- <itemizedlist>
- <listitem>
- <para>the <systemitem class="username">router</systemitem> user,
- to whom all requests to connect to an OpenSRF service will be
- routed;</para>
- </listitem>
- <listitem>
- <para>the <systemitem class="username">opensrf</systemitem> user,
- which clients use to connect to OpenSRF services (you may name
- the user anything you like, but we use
- <literal>opensrf</literal> in these examples)</para>
- </listitem>
- </itemizedlist>
- <para>As the <systemitem class="username">root</systemitem> user, execute the
- <command>ejabberdctl</command> utility as shown below to register and create passwords
- for the two users on each domain. Note that the users correspond to those configured
- in the file <filename>/openils/conf/opensrf_core.xml</filename> in the next steps.</para>
- <programlisting language="xml"><![CDATA[
-# The syntax for registering a user with ejabberdctl is:
-# ejabberdctl register <user> <domain> <password>
-#
-ejabberdctl register router private.localhost <password #1>
-ejabberdctl register router public.localhost <password #1>
-ejabberdctl register opensrf private.localhost <password #2>
-ejabberdctl register opensrf public.localhost <password #2>
-]]></programlisting>
- </step>
- <step>
- <title>Create configuration files</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, execute
- the following commands to create the new configuration files
- <filename>/openils/conf/opensrf_core.xml</filename> and
- <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
- <screen>
- <userinput>cd /openils/conf</userinput>
- <userinput>cp opensrf.xml.example opensrf.xml</userinput>
- <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
- </screen>
- </step>
- <step>
- <title>Change Jabber usernames and passwords</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
- OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
- and update the Jabber usernames and passwords to match the values shown in the
- following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
- shows common XPath syntax to indicate the approximate position within the XML
- file that needs changes. The right-hand side of the table shows the replacement
- values:</para>
- <table xml:id="serversideinstallation-xpath-table-1">
- <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colname="Xpath" colnum="1" colwidth="1.5*"/>
- <colspec colname="Value" colnum="2" colwidth="2.0*"/>
- <thead>
- <row>
- <entry>XPath location</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>/config/opensrf/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/opensrf/passwd </entry>
- <entry>password for
- <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/gateway/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/gateway/passwd</entry>
- <entry>password for
- <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- first entry where transport/server == public.localhost:
- username</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- first entry where transport/server == public.localhost:
- password</entry>
- <entry>password for
- <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">router</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- second entry where transport/server == private.localhost:
- username</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- second entry where transport/server == private.localhost:
- password</entry>
- <entry>password for
- <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">router</systemitem> user
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>You may also need to modify the file to specify the domains from which
- <systemitem class="service">OpenSRF</systemitem> will accept connections,
- and to which it will make connections.
- If you are installing <application>OpenSRF</application> on a single server
- and using the <systemitem class="domainname">private.localhost</systemitem> and
- <systemitem class="domainname">public.localhost</systemitem> domains,
- these will already be set to the correct values. Otherwise, search and replace
- to match values for your own systems.</para>
- </step>
- <step>
- <title>Set location of persistent database</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
- file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the
- element <literal>dbfile</literal> (near the end of the file) to set the
- location of the persistent database:</para>
- <programlisting language="xml"><![CDATA[
-<!-- Example of an app-specific setting override -->
-<opensrf.persist>
- <app_settings>
- <dbfile>/tmp/persist.db</dbfile>
- </app_settings>
-</opensrf.persist>
-]]></programlisting>
- </step>
- <step>
- <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
- <para>In this section you will set up a special configuration file for each user
- who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
- shell</emphasis>) utility.</para>
- <indexterm>
- <primary>srfsh</primary>
- </indexterm>
- <para>The software installation will automatically create
- <command>srfsh</command>. This is a command line diagnostic tool for testing and
- interacting with <application>OpenSRF</application>. It will be used in a future
- step to complete and test the Evergreen installation. See
- <xref linkend="serversideinstallation-testing"/> for further information.</para>
- <para>As the <systemitem class="username">root</systemitem> user, copy the short
- sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
- to the file <filename>.srfsh.xml</filename> (note the leading dot!) in the home
- directory of each user who will use <command>srfsh</command>. Finally, edit each
- file <filename>.srfsh.xml</filename> and make the following changes. When you
- finish, remember to change the owner of the file to match the owner of the home
- directory.</para>
- <itemizedlist>
- <listitem>Modify <literal>domain</literal> to be the router hostname
- (following our domain examples,
- <systemitem class="domainname">private.localhost</systemitem> will give
- <command>srfsh</command> access to all OpenSRF services, while
- <systemitem class="domainname">public.localhost</systemitem> will only
- allow access to those OpenSRF services that are publicly
- exposed).</listitem>
- <listitem>Modify <literal>username</literal> and
- <literal>password</literal> to match the <literal>opensrf</literal>
- Jabber user for the chosen domain</listitem>
- <listitem>Modify <literal>logfile</literal> to be the full path for a
- log file to which the user has write access</listitem>
- <listitem>Modify <literal>loglevel</literal> as needed for testing</listitem>
- </itemizedlist>
- <programlisting language="xml"><![CDATA[
-<?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>
-<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
-<loglevel>4</loglevel>
-</srfsh>
-]]></programlisting>
- </step>
- <step>
- <title>Modify Environmental Variable PATH for
- <systemitem class="username">opensrf</systemitem> User</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
- environmental variable <envar>PATH</envar> by adding a new file path to the
- <systemitem class="username">opensrf</systemitem> user's shell configuration
- file <filename>.bashrc</filename>:</para>
- <screen>
- <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
- </screen>
- </step>
- <step>
- <title>Start OpenSRF</title>
- <para>As the <systemitem class="username">root</systemitem> user, start the
- <systemitem class="service">ejabberd</systemitem> and
- <systemitem class="service">memcached</systemitem> services:</para>
- <screen>
- <userinput>/etc/init.d/ejabberd start</userinput>
- <userinput>/etc/init.d/memcached start</userinput>
- </screen>
- <para>Finally, as the <systemitem class="username">opensrf</systemitem> user,
- start OpenSRF. Use "-l" to force hostname to be "localhost":</para>
- <screen>
- <userinput>osrf_ctl.sh -l -a start_all</userinput>
- </screen>
- <note>
- <para>If you receive the error message <errortext>bash: osrf_ctl.sh:
- command not found</errortext>, then your environment variable
- <envar>PATH</envar> does not include the
- <filename class="directory">/openils/bin</filename> directory;
- this should have been set by <filename>.bashrc</filename> when you
- logged in as the <systemitem class="username">opensrf</systemitem> user,
- but you can manually set it using the following command:</para>
- <screen>
- <userinput>export PATH=$PATH:/openils/bin</userinput>
- </screen>
- </note>
- <para>You can also start Evergreen <emphasis role="bold">without</emphasis> the
- <option>-l</option> flag, but <command>osrf_ctl.sh</command> must know the fully
- qualified domain name for the system on which it will execute. That hostname may
- have been specified in the configuration file <filename>opensrf.xml</filename>,
- which you configured in a previous step.</para>
- </step>
- <step>
- <title>Test connections to OpenSRF</title>
- <para>Once you have installed and started OpenSRF, as the
- <systemitem class="username">root</systemitem> user, test your connection to
- <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
- utility and trying to call the <command>add</command> method on the OpenSRF
- <systemitem class="service">math</systemitem> service:</para>
- <screen>
- <userinput>/openils/bin/srfsh</userinput>
- <computeroutput>
-srfsh#
-request opensrf.math add 2 2
-Received Data: 4
-------------------------------------
-Request Completed Successfully
-Request Time in seconds: 0.007519
-------------------------------------
-
-srfsh#
-</computeroutput>
- </screen>
- <para>For other <command>srfsh</command> commands, type in
- <userinput>help</userinput> at the prompt.</para>
- </step>
- <step>
- <title>Stopping OpenSRF</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, stop OpenSRF:</para>
- <screen>
- <userinput>osrf_ctl.sh -l -a stop_all</userinput>
- </screen>
- </step>
- </procedure>
- </section>
- <section xml:id="serversideinstallation-ubuntudebian">
- <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or
- <systemitem class="osname">Debian</systemitem></title>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Debian</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Ubuntu</secondary>
- </indexterm>
- <para>This section outlines the installation process for the latest stable version of
- Evergreen.</para>
- <para>In this section you will download, unpack, install, configure and test the Evergreen
- system, including the Evergreen server and the PostgreSQL database system. You will make several
- configuration changes and adjustments to the software, including updates to configure the system
- for your own locale, and some updates needed to work around a few known issues.</para>
- <note>
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
- architectures. There may be differences between the Desktop and Server editions of
- <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
- edition.</para>
- <para>In the following instructions, you are asked to perform certain steps as
- either the <systemitem class="username">root</systemitem> user, the
- <systemitem class="username">opensrf</systemitem> user, or the
- <systemitem class="username">postgres</systemitem> user.</para>
- <itemizedlist>
- <listitem>
- <para><systemitem class="osname">Debian</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- <listitem>
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>sudo su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- </itemizedlist>
- <para>To switch from the <systemitem class="username">root</systemitem> user to a
- different user, issue the command <command>su - USERNAME</command>. For example, to
- switch from the <systemitem class="username">root</systemitem> user to the
- <systemitem class="username">opensrf</systemitem> user, issue the command
- <command>su - opensrf</command>. Once you have become a non-root user, to become the
- <systemitem class="username">root</systemitem> user again, simply issue the command
- <command>exit</command>.</para>
- </note>
- <procedure>
- <step>
- <title>Install OpenSRF</title>
- <para>Evergreen software is integrated with and depends on the Open Service
- Request Framework (OpenSRF) software system. For further information on
- installing, configuring and testing OpenSRF, see
- <xref linkend="serversideinstallation-opensrf"/>.</para>
- <para>Follow the steps outlined in that section and run the specified tests to
- ensure that OpenSRF is properly installed and configured. Do not continue with
- any further Evergreen installation steps until you have verified that OpenSRF
- has been successfully installed.</para>
- </step>
- <step>
- <title>Download and Unpack Latest Evergreen Version</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, download
- and extract the latest version of Evergreen. The latest version can be found here:
- <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>
- <screen>
- <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
- <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>
- </screen>
- <para>The new directory
- <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>
- will be created.</para>
- </step>
- <step>
- <title>Install Prerequisites to Build Evergreen</title>
- <para>In this section you will install and configure a set of prerequisites that
- will be used to build Evergreen. In a following step you will actually build the
- Evergreen software using the <command>make</command> utility.</para>
- <para>As the <systemitem class="username">root</systemitem> user, enter the
- commands show below to build the prerequisites from the software distribution
- that you just downloaded and unpacked. Remember to replace
- <emphasis>[DISTRIBUTION]</emphasis> in the following example with the keyword
- corresponding to the name of one of the <systemitem class="osname">Linux</systemitem>
- distributions listed in the following distribution keywords table
- <xref linkend="serversideinstallation-keywords-evergreen"/> .
- For example, to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would
- enter this command: <command>make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic</command> .</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
- </screen>
- <table xml:id="serversideinstallation-keywords-evergreen">
- <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colnum="1" colwidth="1.0*"/>
- <colspec colnum="2" colwidth="3.0*"/>
- <thead>
- <row>
- <entry>Keyword</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>debian-etch</entry>
- <entry>for Debian "Etch" (4.0)</entry>
- </row>
- <row>
- <entry>debian-lenny</entry>
- <entry>for Debian "Lenny" (5.0)</entry>
- </row>
- <row>
- <entry>ubuntu-hardy</entry>
- <entry>for Ubuntu "Hardy Heron" (8.04)</entry>
- </row>
- <row>
- <entry>ubuntu-intrepid</entry>
- <entry>for Ubuntu "Intrepid Ibex" (8.10)</entry>
- </row>
- <row>
- <entry>ubuntu-karmic</entry>
- <entry>for Ubuntu "Karmic Koala" (9.10)</entry>
- </row>
- <row>
- <entry>ubuntu-karmic</entry>
- <entry>for Ubuntu "Lucid Lynx" (10.04)</entry>
- </row>
- <row>
- <entry>centos</entry>
- <entry>for Centos</entry>
- </row>
- <row>
- <entry>rhel</entry>
- <entry>for RHEL</entry>
- </row>
- <row>
- <entry>gentoo</entry>
- <entry>for Gentoo</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </step>
- <step performance="optional" xml:id="serversideinstallation-postgresql-default">
- <title>(OPTIONAL) Install the PostgreSQL Server</title>
- <indexterm>
- <primary>databases</primary>
- <secondary>PostgreSQL</secondary>
- </indexterm>
- <para>Since the PostgreSQL server is usually a standalone server in multi-server
- production systems, the prerequisite installer Makefile in the previous step
- does not automatically install PostgreSQL. You must install the PostgreSQL server
- yourself, either on the same system as Evergreen itself or on another system.
- If your PostgreSQL server is on a different system, just skip this step.</para>
- <para>For further information on manually installing PostgreSQL, visit the official
- <link xl:href="http://www.postgresql.org/">PostgreSQL Site</link>.</para>
- <para>If your PostgreSQL server will be on the same system as your Evergreen
- software, then as the <systemitem class="username">root</systemitem> user
- install the required PostgreSQL server packages:</para>
- <para>For <systemitem class="osname">Debian Lenny</systemitem> and
- <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>
- <screen>
- <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>
- </screen>
- <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and
- <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>
- <screen>
- <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>
- </screen>
- <note>
- <para>PostgreSQL versions 8.3 or 8.4 are the recommended versions to work
- with Evergreen 1.6. If you have an older version of PostgreSQL, you should
- upgrade before installing Evergreen. To find the running version of
- PostgreSQL, as the <systemitem class="username">postgres</systemitem>
- user, run the <command>psql</command>. Then type <userinput>SELECT
- version();</userinput> to get detailed information about your version
- of PostgreSQL.</para>
- </note>
- </step>
- <step performance="optional">
- <title>Install Perl Modules on PostgreSQL Server</title>
- <para>If PostgreSQL is running on the same system as your Evergreen software,
- then the Perl modules will automatically be available. Just skip this step.
- Otherwise, continue if your PostgreSQL server is running on another system.</para>
- <para>You will need to install several Perl modules on the other system. As the
- <systemitem class="username">root</systemitem> user install the following Perl
- modules:</para>
- <screen>
- <userinput># first, ensure the gcc compiler is installed:</userinput>
- <userinput>apt-get install gcc</userinput>
- <userinput># then install the Perl modules:</userinput>
- <userinput>perl -MCPAN -e shell</userinput>
- <prompt>cpan></prompt>
- <userinput>install JSON::XS</userinput>
- <prompt>cpan></prompt>
- <userinput>install MARC::Record</userinput>
- <prompt>cpan></prompt>
- <userinput>install MARC::File::XML</userinput>
- </screen>
- <para>For more information on installing Perl Modules vist the official
- <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
- <indexterm>
- <primary>Perl</primary>
- <secondary>CPAN</secondary>
- </indexterm>
- </step>
- <step>
- <title>Update the System Dynamic Library Path</title>
- <para>You must update the system dynamic library path to force your system to
- recognize the newly installed libraries. As the <systemitem class="username">root</systemitem>
- user, create a file named <filename>/etc/ld.so.conf.d/eg.conf</filename>
- containing these new library paths:</para>
- <programlisting>
-/usr/local/lib
-/usr/local/lib/dbd
-</programlisting>
- <para>Then run the command <command>ldconfig</command> to automatically read the
- file and modify the system dynamic library path:</para>
- <screen>
- <userinput>ldconfig</userinput>
- </screen>
- </step>
- <step performance="optional">
- <title>Restart the PostgreSQL Server</title>
- <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
- the <systemitem class="username">root</systemitem> user you must restart
- PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
- running on another system, you may skip this step. As the <systemitem class="username">opensrf</systemitem>
- user, execute the following command, where
- <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL version
- (e.g. <literal>8.3</literal>):</para>
- <screen>
- <userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>
- </screen>
- </step>
- <step xml:id="serversideinstallation-configure">
- <title>Configure Evergreen</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to
- the Evergreen build directory and use the <command>configure</command> and
- <command>make</command> utilities to configure Evergreen so it can be compiled
- and linked in the next step:</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
- <userinput>make</userinput>
- </screen>
- </step>
- <step>
- <title>Compile, Link and Install Evergreen</title>
- <para>In this step you will actually compile, link and install Evergreen and the
- default Evergreen Staff Client.</para>
- <para>As the <systemitem class="username">root</systemitem> user, return to the
- Evergreen build directory and use the <command>make</command> utility as shown below:</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>
- </screen>
- <para>The Staff Client will also be automatically built, but you must remember
- to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the Staff
- Client you will use to connect to the Evergreen server.</para>
- <para>The above commands will create a new subdirectory
- <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename>
- containing the Staff Client.</para>
- <para>To complete the Staff Client installation,
- as the <systemitem class="username">root</systemitem> user create a symbolic link
- named <emphasis>server</emphasis> in the head of the Staff Client directory
- <filename class="directory">/openils/var/web/xul</filename> that points to the
- subdirectory <filename class="directory">/server</filename> of the new Staff
- Client build:</para>
- <screen>
- <userinput>cd /openils/var/web/xul</userinput>
- <userinput>ln -sf rel_1_6_1_2/server server</userinput>
- </screen>
- </step>
- <step>
- <title>Copy the OpenSRF Configuration Files</title>
- <para>As the <systemitem class="username">root</systemitem> user, execute the
- following commands to copy the example OpenSRF configuration files into place
- after first creating backup copies of the old files for troubleshooting purposes.
- These files replace the configuration files that you set up in a previous step
- when you installed and tested OpenSRF. Finally, change the ownership on
- the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>
- <screen>
- <userinput>cd /openils/conf</userinput>
- <userinput>cp opensrf.xml opensrf.xml.BAK</userinput>
- <userinput>cp opensrf_core.xml opensrf_core.xml.BAK</userinput>
- <userinput>cp opensrf.xml.example opensrf.xml</userinput>
- <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
- <userinput>cp oils_web.xml.example oils_web.xml</userinput>
- <userinput>chown -R opensrf:opensrf /openils/</userinput>
- </screen>
- </step>
- <step>
- <title>Create and Configure PostgreSQL Database</title>
- <indexterm>
- <primary>databases</primary>
- <secondary>PostgreSQL</secondary>
- </indexterm>
- <para>In this step you will create the Evergreen database. In the commands
- below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
- repository to match your PostgreSQL server
- layout. For example, if you built PostgreSQL from source the path would be
- <filename class="directory">/usr/local/share/contrib</filename>; if you
- installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>,
- the path would be
- <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem>.</para>
- <substeps>
- <step>
- <para>
- <emphasis role="bold">Create and configure the database</emphasis>
- </para>
- <para>As the <systemitem class="username">postgres</systemitem>
- user on the PostgreSQL system create the PostgreSQL database,
- then set some internal paths:</para>
- <screen>
- <userinput>createdb evergreen -E UTF8 -T template0</userinput>
- <userinput>createlang plperl evergreen</userinput>
- <userinput>createlang plperlu evergreen</userinput>
- <userinput>createlang plpgsql evergreen</userinput>
- </screen>
- <para>Continue as user <systemitem class="username">postgres</systemitem>
- and execute the SQL scripts as shown below, adjusting the paths as needed, where
- <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL
- version (e.g. <literal>8.3</literal>).</para>
- <screen>
- <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>
- <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql evergreen</userinput>
- <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql evergreen</userinput>
- </screen>
- </step>
- <step>
- <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
- <para>As the <systemitem class="username">postgres</systemitem>
- user on the PostgreSQL system, create a new PostgreSQL user
- named <systemitem class="username">evergreen</systemitem> and
- assign a password:</para>
- <screen>
- <userinput>createuser -P -s evergreen</userinput>
- <prompt>Enter password for new role: <userinput>MYNEWPASSWORD</userinput></prompt>
- <prompt>Enter it again: <userinput>MYNEWPASSWORD</userinput></prompt>
- </screen>
- </step>
- <step>
- <title>Create Database Schema</title>
- <para>As the <systemitem class="username">root</systemitem>
- user, create the database schema and configure your system with
- the corresponding database authentication details for the
- <emphasis>evergreen</emphasis> database user that you created in
- the previous step.</para>
- <para>Enter the following commands and replace
- <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and
- <emphasis>DATABASENAME</emphasis> with appropriate
- values:</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>
- <userinput> --service all --create-schema --create-bootstrap --create-offline \</userinput>
- <userinput> --hostname HOSTNAME --port PORT \</userinput>
- <userinput> --user evergreen --password PASSWORD --database DATABASENAME</userinput>
- </screen>
- <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
- <emphasis role="bold">localhost</emphasis>,
- <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
- Values for <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis>
- will match the values you used in the previous step when you created the
- database and and set a password for the
- <systemitem class="username">evergreen</systemitem> user.
- Adjust the values to match your own systems.</para>
- <para>As the command executes, you may see warnings similar to:
- <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
- you may see one warning per schema) but they can be safely ignored.</para>
- <note>
- <para>If you are entering the above command on a single
- line, do not include the <literal>\</literal>
- (backslash) characters. If you are using the
- <command>bash</command> shell, these should only be used
- at the end of a line at a bash prompt to indicate that
- the command is continued on the next line.</para>
- </note>
- </step>
- <step>
- <title>Configure the Apache web server</title>
- <indexterm>
- <primary>web server</primary>
- <secondary>Apache</secondary>
- </indexterm>
- <para>In this step you will configure the Apache web server to
- support Evergreen software.</para>
- <para>First, you must enable some built-in Apache modules and install
- some additional Apache configuration files. Then you will create a new
- Security Certificate. Finally, you must make several changes to the Apache
- configuration file.</para>
- <substeps>
- <step>
- <title>Enable the required Apache Modules</title>
- <para>As the <systemitem class="username">root</systemitem> user, enable
- some modules in the Apache server, then copy the
- new configuration files to the Apache server
- directories:</para>
- <screen>
- <userinput>a2enmod ssl # enable mod_ssl</userinput>
- <userinput>a2enmod rewrite # enable mod_rewrite</userinput>
- <userinput>a2enmod expires # enable mod_expires</userinput>
- </screen>
- <para>As the commands execute, you may see warnings similar to:
- <literal>Module SOMEMODULE already enabled</literal> but you can safely ignore them.</para>
- </step>
- <step>
- <title>Copy Apache configuration files</title>
- <para>You must copy the Apache configuration
- files from the Evergreen installation directory
- to the Apache directory. As the
- <systemitem class="username">root</systemitem>
- user, perform the following commands:</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
- <userinput>cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/</userinput>
- <userinput>cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/</userinput>
- <userinput>cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
- </screen>
- </step>
- <step>
- <title>Create a Security Certificate</title>
- <para>You must create a new Security Certificate (SSL Key)
- for the Apache server using the <command>openssl</command>
- command. For a public production server you must configure
- or purchase a signed SSL certificate, but for now you can
- just use a self-signed certificate and accept the warnings
- in the Staff Client and browser during testing and
- development. As the
- <systemitem class="username">root</systemitem> user,
- perform the following commands:</para>
- <screen>
- <userinput>mkdir /etc/apache2/ssl</userinput>
- <userinput>cd /etc/apache2/ssl</userinput>
- <userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
- </screen>
- <note>
- <para>This step generates a self-signed SSL
- certificate. You must install a proper SSL
- certificate for a public production system to
- avoid warning messages when users login to their
- account through the OPAC or when staff login
- through the staff client.</para>
- </note>
- </step>
- <step xml:id="serversideinstallation-modify-apache">
- <title>Update Apache configuration file</title>
- <para>You must make several changes to the new Apache
- configuration file
- <filename>/etc/apache2/sites-available/eg.conf</filename>. As
- the <systemitem class="username">root</systemitem> user,
- edit the file and make the following changes:</para>
- <itemizedlist>
- <listitem>
- <para>Comment out the line <literal>Allow
- from 10.0.0.0/8</literal> and uncomment
- the line <literal>Allow from all</literal>.</para>
- <warning>This change allows access to your
- configuration CGI scripts from any workstation on
- any network. This is only a temporary change to
- expedite testing and should be removed after you
- have finished and successfully tested the Evergreen
- installation. See
- <xref linkend="serversideinstallation-postinstallation"/>
- for further details on removing this change after
- the Evergreen installation is complete.
- </warning>
- </listitem>
- <listitem>
- <para>Comment out the line <literal>Listen
- 443</literal>, since it conflicts with the
- same declaration in the configuration file:
- <filename>/etc/apache2/ports.conf</filename>.
- Note that <systemitem class="osname">Debian
- </systemitem> users should not do this
- since the conflict does not apply to that
- operating system.</para>
- </listitem>
- <listitem>
- <para>The following updates are needed to allow
- the logs to function properly, but it may break
- other Apache applications on your server:</para>
- <para>For the <systemitem class="osname">Linux</systemitem>
- distributions <systemitem class="osname">Ubuntu
- Hardy</systemitem> or
- <systemitem class="osname">Debian Etch</systemitem>,
- as the <systemitem class="username">root</systemitem>
- user, edit the Apache configuration file
- <filename>/etc/apache2/apache2.conf</filename> and
- change the line <literal>User www-data</literal>
- to <literal>User opensrf</literal>.</para>
- <para>For the <systemitem class="osname">Linux</systemitem>
- distributions <systemitem class="osname">Ubuntu
- Karmic</systemitem> or
- <systemitem class="osname">Ubuntu Lucid</systemitem>
- or <systemitem class="osname">Debian
- Lenny</systemitem>, as the
- <systemitem class="username">root</systemitem>
- user, edit the Apache configuration file
- <filename>/etc/apache2/envvars</filename> and
- change the line <literal>export
- APACHE_RUN_USER=www-data</literal> to
- <literal>export
- APACHE_RUN_USER=opensrf</literal>.</para>
- </listitem>
- </itemizedlist>
- </step>
- <step>
- <title>Enable the Evergreen web site</title>
- <para>Finally, you must enable the Evergreen web site. As the
- <systemitem class="username">root</systemitem> user, execute
- the following Apache configuration commands to disable the default
- <emphasis>It Works</emphasis> web page and enable the
- Evergreen web site:</para>
- <screen>
- <userinput>a2dissite default</userinput>
- <userinput>a2ensite eg.conf</userinput>
- </screen>
- </step>
- </substeps>
- </step>
- </substeps>
- </step>
- <step xml:id="serversideinstallation-opensrf-config">
- <title>Modify the OpenSRF Configuration File</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
- OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
- to update the Jabber usernames and passwords, and to specify the domain from
- which we will accept and to which we will make connections.</para>
- <para>If you are installing Evergreen on a single server and using the
- <systemitem class="domainname">private.localhost</systemitem> /
- <systemitem class="domainname">public.localhost</systemitem> domains,
- these will already be set to the correct values. Otherwise, search and replace
- to match your customized values.</para>
- <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
- shows common XPath syntax to indicate the approximate position within the XML
- file that needs changes. The right-hand side of the table shows the replacement
- values:</para>
- <table xml:id="serversideinstallation-xpath-table-2">
- <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colname="Xpath" colnum="1" colwidth="1.5*"/>
- <colspec colname="Value" colnum="2" colwidth="2.0*"/>
- <thead>
- <row>
- <entry>XPath location</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>/config/opensrf/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/opensrf/passwd </entry>
- <entry>password for
- <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/gateway/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/gateway/passwd</entry>
- <entry>password for
- <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- first entry where transport/server == public.localhost:
- username</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- first entry where transport/server == public.localhost:
- password</entry>
- <entry>password for
- <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">router</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- second entry where transport/server == private.localhost:
- username</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport,
- second entry where transport/server == private.localhost:
- password</entry>
- <entry>password for
- <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">router</systemitem> user
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </step>
- <step xml:id="serversideinstallation-srfsh">
- <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
- <para>The software installation will automatically create a utility named
- <command>srfsh</command> (surf shell). This is a command line diagnostic tool
- for testing and interacting with the OpenSRF network software. It will be used
- in a future step to complete and test the Evergreen installation. See
- <xref linkend="serversideinstallation-testing"/> for further information.</para>
- <para>In this section you will set up a special configuration file for each user
- who will need to run the utility. Copy the short sample configuration file
- <filename>/openils/conf/srfsh.xml.example</filename> to the file
- <filename>.srfsh.xml</filename> (note the leading dot!) in the home directory of
- each user who will use <command>srfsh</command>. Finally, edit each user's
- <filename>.srfsh.xml</filename> file and make the following changes:</para>
- <substeps>
- <step>
- <para>Modify <emphasis role="bold">domain</emphasis> to be the
- router hostname (following our domain examples,
- <systemitem class="domainname">private.localhost</systemitem>>
- will give <command>srfsh</command> access to all OpenSRF services,
- while <systemitem class="domainname">public.localhost</systemitem>
- will only allow access to those OpenSRF services that are
- publicly exposed).</para>
- </step>
- <step>
- <para>Modify <emphasis role="bold">username</emphasis> and
- <emphasis role="bold">password</emphasis> to match the
- <systemitem class="username">opensrf</systemitem> Jabber user
- for the chosen domain.</para>
- </step>
- <step>
- <para>Modify <emphasis role="bold">logfile</emphasis> to be the
- full path for a log file to which the user has write
- access.</para>
- </step>
- <step>
- <para>Modify <emphasis role="bold">loglevel</emphasis> as needed
- for testing.</para>
- </step>
- </substeps>
- <programlisting language="xml"><![CDATA[
-<?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>evergreen</passwd>
-<port>5222</port>
-<logfile>/tmp/srfsh.log</logfile>
-<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
-<loglevel>4</loglevel>
-</srfsh>
-]]></programlisting>
- </step>
- <step xml:id="serversideinstallation-opensrf-env">
- <title>Modify the OpenSRF Environment</title>
- <para>Modify the shell configuration file <filename>~/.bashrc</filename> for
- user <systemitem class="username">opensrf</systemitem> by adding a Perl environmental
- variable, then execute the shell configuration file to load the new variables into
- your current environment.</para>
- <note>
- <para>
- <emphasis>In a multi-server environment, you must add any
- modifications to <filename>~/.bashrc</filename> to the top of
- the file <emphasis>before</emphasis> the line
- <literal>[ -z "$PS1" ] && return </literal>.
- This will allow headless (scripted) logins to load the correct
- environment.</emphasis>
- </para>
- </note>
- <screen>
- <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>
- <userinput>. ~/.bashrc</userinput>
- </screen>
- </step>
- <step>
- <title>(OPTIONAL) Enable and Disable Language Localizations</title>
- <para>You can load translations such as Armenian (hy-AM), Canadian French
- (fr-CA), and others into the database to complete the translations available in
- the OPAC and staff client. For further information, see <xref linkend="enabling_and_disabling_localization"/>.</para>
- </step>
- </procedure>
- </section>
- <section xml:id="serversideinstallation-starting">
- <title>Starting Evergreen</title>
- <procedure>
- <step>
- <para>As the <systemitem class="username">root</systemitem>
- user, start the <systemitem class="service">ejabberd</systemitem> and
- <systemitem class="service">memcached</systemitem> services
- (if they are not already running):</para>
- <screen>
- <userinput>/etc/init.d/ejabberd start</userinput>
- <userinput>/etc/init.d/memcached start</userinput>
- </screen>
- </step>
- <step>
- <para>As the <systemitem class="username">opensrf</systemitem>
- user, start Evergreen.</para>
- <para>Use the flag <option>-l</option> to force Evergreen to use
- <systemitem class="domainname">localhost</systemitem> (your
- current system) as the hostname. Using the
- <option>start_all</option> option will start the OpenSRF
- <systemitem class="service">router</systemitem> ,
- <systemitem class="service">Perl</systemitem> , and
- <systemitem class="service">C</systemitem> services:</para>
- <screen>
- <userinput>osrf_ctl.sh -l -a start_all</userinput>
- </screen>
- <note>
- <para>
- <emphasis>You can also start Evergreen
- <emphasis role="bold">without</emphasis>
- the <option>-l</option> flag, but the
- <command>osrf_ctl.sh</command> utility must know
- the fully qualified domain name for the system
- on which it will execute. That hostname may have
- been specified in the configuration file
- <filename>opensrf.xml</filename>, which you
- configured in a previous step.</emphasis>
- </para>
- <para>Use the <command>hostname</command> command to
- determine the fully qualified domain name of your
- system.</para>
- </note>
- <itemizedlist>
- <listitem>
- <para>If you receive an error message similar to
- <emphasis>osrf_ctl.sh: command not found</emphasis>,
- then your environment variable
- <envar>PATH</envar> does not include the directory
- <filename class="directory">/openils/bin</filename>.
- As the
- <systemitem class="username">opensrf</systemitem>
- user, edit the configuration file
- <filename>/home/opensrf/.bashrc</filename> and
- add the following line:
- <literal>export PATH=$PATH:/openils/bin</literal></para>
- </listitem>
- <listitem>
- <para>If you receive an error message similar to
- <emphasis>Can't locate OpenSRF/System.pm in
- @INC ... BEGIN failed--compilation
- aborted</emphasis>, then your environment variable
- <emphasis role="bold">PERL5LIB</emphasis> does not
- include the directory
- <filename class="directory">/openils/lib/perl5</filename>.
- As the
- <systemitem class="username">opensrf</systemitem>
- user, edit the configuration file
- <filename>/home/opensrf/.bashrc</filename> and
- add the following line:
- <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
- </listitem>
- </itemizedlist>
- </step>
- <step>
- <para>As the <systemitem class="username">opensrf</systemitem>
- user, generate the Web files needed by the Staff Client and
- catalog, and calculate the proximity of locations in the
- Organizational Unit tree (which allows
- <emphasis>Holds</emphasis> to work properly):</para>
- <screen>
- <userinput>cd /openils/bin</userinput>
- <userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
- <computeroutput>
-Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
-Updating fieldmapper
-</computeroutput>
- </screen>
- <para>You must do this the first time you start Evergreen, and
- after making any changes to the library hierarchy.</para>
- </step>
- <step>
- <para>As the <systemitem class="username">root</systemitem>
- user, restart the Apache Web server:</para>
- <screen>
- <userinput>/etc/init.d/apache2 restart</userinput>
- </screen>
- <note>
- <para>If the Apache Web server was running when you
- started the OpenSRF services, you might not be able to
- successfully log in to the OPAC or Staff Client until
- the Apache Web server is restarted.</para>
- </note>
- </step>
- </procedure>
- </section>
- <section xml:id="serversideinstallation-testing">
- <title>Testing the Installation</title>
- <para>This section describes several simple tests you can perform to verify that the Evergreen
- server-side software has been installed and configured properly and is running as
- expected.</para>
- <simplesect xml:id="serversideinstallation-testing-connections">
- <title>Testing Connections to Evergreen</title>
- <para>Once you have installed and started Evergreen, test your connection to
- Evergreen. As the <systemitem class="username">opensrf</systemitem> user start the
- <command>srfsh</command> application and try logging onto the Evergreen server using the
- default administrator username and password. Following is sample output generated by
- executing <command>srfsh</command> after a successful Evergreen installation.
- For help with <command>srfsh</command> commands, type <userinput>help</userinput>
- at the prompt:</para>
- <screen>
- <userinput>/openils/bin/srfsh</userinput>
- <prompt>srfsh%</prompt>
- <userinput>login admin open-ils</userinput>
- <prompt>Received Data: "250bf1518c7527a03249858687714376"</prompt>
- <prompt>------------------------------------</prompt>
- <prompt>Request Completed Successfully</prompt>
- <prompt>Request Time in seconds: 0.045286</prompt>
- <prompt>------------------------------------</prompt>
- <prompt>Received Data: {</prompt>
- <prompt> "ilsevent":0,</prompt>
- <prompt> "textcode":"SUCCESS",</prompt>
- <prompt> "desc":" ",</prompt>
- <prompt> "pid":21616,</prompt>
- <prompt> "stacktrace":"oils_auth.c:304",</prompt>
- <prompt> "payload":{</prompt>
- <prompt> "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",</prompt>
- <prompt> "authtime":420</prompt>
- <prompt> }</prompt>
- <prompt>}</prompt>
- <prompt>------------------------------------</prompt>
- <prompt>Request Completed Successfully</prompt>
- <prompt>Request Time in seconds: 1.336568</prompt>
- <prompt>------------------------------------</prompt>
- </screen>
- <para>If this does not work, try the following:</para>
- <itemizedlist>
- <listitem>As the <systemitem class="username">opensrf</systemitem> user, run the
- script <filename>Open-ILS/src/support-scripts/settings-tester.pl</filename> to
- see if it finds any system configuration problems. If the output of
- <command>settings-tester.pl</command> does not help you find the problem, please
- do not make any significant changes to your configuration.</listitem>
- <listitem>Follow the steps in the troubleshooting guide in
- <xref linkend="troubleshooting"/>.</listitem>
- <listitem>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 and contact the
- <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
- list for assistance before making any drastic changes to your
- system configuration.</listitem>
- </itemizedlist>
- </simplesect>
- </section>
- <section xml:id="serversideinstallation-postinstallation">
- <title>Post-Installation Chores</title>
- <para>There are several additional steps you may need to complete after Evergreen has been
- successfully installed and tested. Some steps may not be needed (e.g., setting up support for
- Reports).</para>
- <section>
- <title>Remove temporary Apache configuration changes</title>
- <para>You modified the Apache configuration file
- <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
- temporary measure to expedite testing (see
- <xref linkend="serversideinstallation-modify-apache"/> for further information).
- Those changes must now be reversed in order to deny unwanted access to your CGI
- scripts from users on other public networks.</para>
- <warning>
- <para>
- <emphasis>This temporary network update was done to expedite
- testing. You <emphasis role="bold"> must</emphasis> correct
- this for a public production system.</emphasis>
- </para>
- </warning>
- <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
- file again and comment out the line <literal>Allow from all</literal> and uncomment the
- line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
- address scheme.</para>
- </section>
- <section>
- <title>Configure a permanent SSL key</title>
- <para>In a previous step, you used the command <command>openssl</command> to temporarily
- create a new SSL key for the Apache server. This self-signed certificate was adequate
- during testing and development, but will continue to generate warnings in the Staff Client
- and browser. For a public production server you should configure or purchase a signed SSL
- certificate.</para>
- <warning>
- <para>
- <emphasis>The temporary SSL key was only created to expedite
- testing. You should install a proper SSL certificate for a public
- production system.</emphasis>
- </para>
- </warning>
- </section>
- <section>
- <title>Set Up Support For Reports</title>
- <para>Evergreen reports are extremely powerful but require some simple configuration.
- This section describes starting and stopping the Reporter daemon processes.</para>
- <itemizedlist>
- <listitem>
- <para>Starting the Reporter Daemon</para>
- <para>Once the <systemitem class="daemon">open-ils.reporter</systemitem>
- process is running and enabled on the gateway, you can start the
- Reporter daemon. That process periodically checks for requests for new
- or scheduled reports, then starts them as required.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user,
- start the Reporter daemon using the following command:</para>
- <screen>
- <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter</userinput>
- <userinput>./clark-kent.pl --daemon</userinput>
- </screen>
- <para>You can control how the <command>clark-kent.pl</command> utility behaves
- by specifying any of several command-line options:</para>
- <itemizedlist>
- <listitem><option>--sleep=interval</option> : number of seconds
- to sleep between checks for new reports to run; defaults to
- <literal>10</literal></listitem>
- <listitem><option>--lockfile=filename</option> : where to place
- the lockfile for the process; defaults to
- <filename>/tmp/reporter-LOCK</filename></listitem>
- <listitem><option>--concurrency=integer</option> : number of
- Reporter daemon processes to run; defaults to
- <literal>1</literal></listitem>
- <listitem><option>--bootstrap=filename</option> : OpenSRF
- bootstrap configuration file; defaults to
- <filename>/openils/conf/opensrf_core.xml</filename></listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Stopping the Reporter Daemon</para>
- <para>To stop the Reporter daemon, you must kill the process and remove
- the lockfile. The daemon may have just a single associated process or
- there may be several processes if the daemon was started with the optional
- <literal>--concurrency</literal> switch. It will also have a lockfile
- in the default location.</para>
- <para>As the <systemitem class="username">opensrf</systemitem> user,
- execute the following shell commands:</para>
- <screen>
- <userinput># find and kill the process ID number(s)</userinput>
- <userinput>kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`</userinput>
- <userinput># remove the lock file</userinput>
- <userinput>rm /tmp/reporter-LOCK</userinput>
- </screen>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section xml:id="serversideinstallation-virtual">
- <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
- <para>This section describes the installation of Evergreen software in so-called "virtualized"
- software environments. Evergreen software runs as a native application on any of several
- well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>
- distributions including <systemitem class="osname">Ubuntu</systemitem> and
- <systemitem class="osname">Debian</systemitem> but it does not run as a native application
- on the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
- However, it is possible to execute Evergreen on a <systemitem class="osname">Windows</systemitem>
- host system by running it within a virtual Linux-guest installation, which itself executes
- on the <systemitem class="osname">Windows</systemitem> system.
- The <systemitem class="osname">Linux</systemitem> environment is fully emulated and acts
- (within limits) just as if it were executing on a real standalone system.</para>
- <para>This technique of emulating a <systemitem class="osname">Linux</systemitem> environment on
- a <systemitem class="osname">Windows</systemitem> host is a practical way to install and run an
- Evergreen system if it is not possible to dedicate a physical machine solely as a
- <systemitem class="osname">Linux</systemitem> host for Evergreen. This architecture is not
- recommended for large scale systems since there are performance limitations to running Evergreen
- in a virtualized environment. However, it is a reasonable architecture for smaller experimental
- systems, as a proof of concept, or as a conference-room pilot.</para>
- <simplesect>
- <title>Installing Virtualization Software</title>
- <para>As described above, Evergreen can be installed on top of an emulated
- <systemitem class="osname">Linux</systemitem> environment. The
- <systemitem class="osname">Linux</systemitem> environment, in turn, is installed
- on top of a software application such as <application>"VirtualBox"</application>,
- <application>"VMware"</application> or <application>"VirtualPC"</application> which must
- first be installed on the <systemitem class="osname">Windows</systemitem> system. This
- section contains step-by-step examples that show installing popular virtualization
- applications on a <systemitem class="osname">Windows</systemitem> host system. Following
- this section are further descriptions of installing
- <systemitem class="osname">Linux</systemitem> and Evergreen systems using that
- virtualization software.</para>
- <simplesect>
- <title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
- <para>This section reviews installation of the
- <application>"VirtualBox"</application> application on
- <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
- Download the latest edition of <application>VirtualBox</application> from their official website:
- <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link>
- and follow the on screen instructions to install the software.</para>
- </simplesect>
- <simplesect>
- <title>Installing VMware Virtualization Software</title>
- <indexterm>
- <primary>virtualization software</primary>
- <secondary>VMware</secondary>
- </indexterm>
- <para>This section reviews installation of the
- <application>"VMware"</application> application on
- <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
- Find and Download the free virtual machine software of from the VMware
- official website:
- <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink>
- and follow the on-screen instructions.</para>
- </simplesect>
- </simplesect>
- <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">
- <title>Installing <systemitem class="osname">Linux</systemitem> /
- Evergreen on Virtualization Software</title>
- <para>After the virtualization software is installed and running, there are two ways to
- continue with installing <systemitem class="osname">Linux</systemitem> and Evergreen
- software in the new virtualized environment:</para>
- <orderedlist>
- <listitem>
- <para>Download and install a prebuilt software image that contains a
- working <systemitem class="osname">Linux</systemitem> / Evergreen system
- (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
- details)</para>
- </listitem>
- <listitem>
- <para>Manually install a <systemitem class="osname">Linux</systemitem>
- guest system, then manually install Evergreen on it.</para>
- </listitem>
- </orderedlist>
- <para>We review each method in the following sections.</para>
- <simplesect xml:id="serversideinstall-virtual-prebuilt">
- <title>Download and install a prebuilt software image</title>
- <para>You can download a prebuilt software image that, when installed with your
- virtualization software, emulates a
- <systemitem class="osname">Linux</systemitem> guest system containing a running
- Evergreen distribution. The image is essentially a snapshot of a hard disk from
- a fully configured, functional <systemitem class="osname">Linux</systemitem>
- system with Evergreen already installed.</para>
- <para>We recommend this approach if you wish to get Evergreen running quickly
- with minimal attention to configuration. After reviewing only a few
- configuration details you can have a working Evergreen system that integrates
- smoothly with the rest of your network. See
- <xref linkend="serversideinstall-virtual-versions"/> for a list of prebuilt
- software images that are currently available to download and install</para>
- <note>DISCLAIMER: The following virtual images have been contributed by members
- of the Evergreen community for the purposes of testing, evaluation, training,
- and development.</note>
- <table xml:id="serversideinstall-virtual-versions">
- <title>Linux / Evergreen Virtual Images</title>
- <tgroup align="left" cols="4" colsep="1" rowsep="1">
- <colspec colnum="1" colwidth="1.0*"/>
- <colspec colnum="2" colwidth="1.0*"/>
- <colspec colnum="3" colwidth="3.0*"/>
- <colspec colnum="4" colwidth="1.0*"/>
- <thead>
- <row>
- <entry>Linux Version</entry>
- <entry>Evergreen Version</entry>
- <entry>Image</entry>
- <entry>Comments</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Debian lenny (5.0)</entry>
- <entry>1.6.0.1</entry>
- <entry>
- <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip"> download </ulink>
- </entry>
- <entry>VirtualBox image</entry>
- </row>
- <row>
- <entry>Ubuntu karmic koala (9.10)</entry>
- <entry>1.6.0.0</entry>
- <entry>
- <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip"> download </ulink>
- </entry>
- <entry>VirtualBox image</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <procedure>
- <title>VirtualBox Example</title>
- <indexterm>
- <primary>virtualization software</primary>
- <secondary>VirtualBox</secondary>
- </indexterm>
- <step>
- <para>Start VirtualBox for the first time and select
- <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media
- Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>
- to locate the prebuilt software image just downloaded (the
- example shows it was extracted from the original
- <filename class="extension">zip</filename> file into a temporary directory
- <filename class="directory">C:\temp</filename>).</para>
- </step>
- <step>
- <para>After selecting the file, click <guibutton>Open</guibutton> to import it.</para>
- </step>
- <step>
- <para>Then click <guibutton>OK</guibutton> to save the selection
- and return to the VirtualBox Media Manager</para>
- </step>
- <step>
- <para>Click <guibutton>New</guibutton>, then <guibutton>Next</guibutton> to continue
- and create a new virtual machine (VM).</para>
- </step>
- <step>
- <para>Create a new name for the VM and set the operating system
- type, then click <guibutton>Next</guibutton>.</para>
- </step>
- <step>
- <para>Set the memory size (at least 512Mb),
- then click <guibutton>Next</guibutton>.</para>
- </step>
- <step>
- <para>Edit the Virtual Hard Disk configuration settings; click
- the radio boxes <guilabel>Boot Hard Disk</guilabel> and
- <guilabel>Use existing hard disk</guilabel>
- and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel>
- is selected. Click <guibutton>Finish</guibutton> to finish the
- setup.</para>
- </step>
- <step>
- <para>Install the <application>VirtualBox Guest
- Additions</application> (really a required upgrade to
- VirtualBox)</para>
- </step>
- <step>
- <para>Return to VirtualBox and see the summary of the VM just
- created. Click <guibutton>Start</guibutton> to boot the new VM.</para>
- </step>
- <step>
- <para>See the start of the <systemitem class="osname">Linux</systemitem>
- boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel
- 2.6.26-2-686</guimenuitem> from the startup menu and click
- <guibutton>Enter</guibutton> to start
- <systemitem class="osname">Linux</systemitem> and Evergreen.
- After some delay you should see the command line prompt
- <prompt>debian-lenny login:</prompt>. Log in with username
- <userinput>root</userinput> and password <userinput>evergreen</userinput>
- to continue.</para>
- </step>
- </procedure>
- </simplesect>
- </simplesect>
- </section>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xml:id="serversideinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
+ <info>
+ <title>Server-side Installation of Evergreen Software</title>
+ <abstract>
+ <para>This section describes installation of the Evergreen server-side software and its associated components.
+ Installation, configuration, testing and verification
+ of the software is straightforward if you follow some simple directions.</para>
+ </abstract>
+ </info>
+ <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
+ stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
+ installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
+ system.</para>
+ <para>The current version of the Evergreen server-side software runs as a native application on any of several
+ well-known <systemitem class="osname">Linux</systemitem> distributions
+ (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
+ It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
+ operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
+ Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
+ installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
+ <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
+ <application>"VirtualBox"</application>, or <application>"VMware"</application>, or
+ <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>
+ environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
+ systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
+ <application>"VMware"</application>). More information on virtualized environments can be found in
+ <xref linkend="serversideinstallation-virtual"/>.</para>
+ <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
+ <para>The Evergreen server-side software has dependencies on particular versions of certain major software
+ sub-components. Successful installation of Evergreen software requires that software versions agree with those
+ listed here:</para>
+ <table xml:id="serversideinstall-software-dependencies">
+ <title>Evergreen Software Dependencies</title>
+ <indexterm>
+ <primary>Evergreen software dependencies</primary>
+ </indexterm>
+ <tgroup align="left" cols="3" colsep="1" rowsep="1">
+ <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
+ <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
+ <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
+ <thead>
+ <row>
+ <entry>Evergreen</entry>
+ <entry>OpenSRF</entry>
+ <entry>PostgreSQL</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.6.1.x</entry>
+ <entry>1.4.0</entry>
+ <entry>8.2 / 8.3</entry>
+ </row>
+ <row>
+ <entry>1.6.0.x</entry>
+ <entry>1.2</entry>
+ <entry>8.2 / 8.3</entry>
+ </row>
+ <row>
+ <entry>1.4.x</entry>
+ <entry>1.0</entry>
+ <entry>8.1 / 8.2</entry>
+ </row>
+ <row>
+ <entry>1.2.x</entry>
+ <entry>0.9</entry>
+ <entry>8.1 / 8.2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section xml:id="serversideinstallation-all">
+ <title>Installing Server-Side Software</title>
+ <para>This section describes the installation of the major components of Evergreen server-side software.</para>
+ <para>As far as possible, you should perform the following steps in the exact order given since the
+ success of many steps relies on the successful completion of earlier steps. You should make backup
+ copies of files and environments when you are instructed to do so. In the event of installation problems
+ those copies can allow you to back out of a step gracefully and resume the installation from a known
+ state. See <xref linkend="backingup"/> for further information.</para>
+ <para>Of course, after you successfully complete and test the entire Evergreen installation you should
+ take a final snapshot backup of your system(s). This can be the first in the series of regularly
+ scheduled system backups that you should probably also begin.</para>
+ <section xml:id="serversideinstallation-opensrf">
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>installation</secondary>
+ </indexterm>
+ <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or
+ <systemitem class="osname">Debian</systemitem></title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Debian</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Ubuntu</secondary>
+ </indexterm>
+ <para>This section describes the installation of the latest version of the Open Service Request
+ Framework (OpenSRF), a major component of the Evergreen server-side software, on
+ <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
+ systems. Evergreen software is integrated with and depends on the OpenSRF software
+ system.</para>
+ <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
+ properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
+ continue with any further Evergreen installation steps
+ until you have verified that OpenSRF has been successfully installed and tested.</para>
+ <note>
+ <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
+ platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch
+ (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and
+ <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>
+ <para>In the following instructions, you are asked to perform certain steps as either
+ the <systemitem class="username">root</systemitem> user, the
+ <systemitem class="username">opensrf</systemitem> user, or the
+ <systemitem class="username">postgres</systemitem> user.</para>
+ <itemizedlist>
+ <listitem>
+ <para><systemitem class="osname">Debian</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ <listitem>
+ <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>sudo su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ </itemizedlist>
+ <para>To switch from the <systemitem class="username">root</systemitem> user to a
+ different user, issue the command <command>su - USERNAME</command>. For example, to
+ switch from the <systemitem class="username">root</systemitem> user to the
+ <systemitem class="username">opensrf</systemitem> user, issue the command
+ <command>su - opensrf</command>. Once you have become a non-root user, to become
+ the <systemitem class="username">root</systemitem> user again, simply issue the command
+ <command>exit</command>.</para>
+ </note>
+ <procedure>
+ <step>
+ <title>Add the OpenSRF User</title>
+ <para>As the <systemitem class="username">root</systemitem> user, add the
+ opensrf user to the system. The default shell for the new user is automatically
+ set to <command>/bin/bash</command> to inherit a reasonable environment:</para>
+ <screen>
+ <userinput>useradd -m -s /bin/bash opensrf</userinput>
+ <userinput>passwd opensrf</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Download and Unpack Latest OpenSRF Version</title>
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>download</secondary>
+ </indexterm>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, change to
+ the directory <filename class="directory">/home/opensrf</filename> then download
+ and extract the latest version of OpenSRF. The latest version can be found here:
+ <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>
+ <screen>
+ <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
+ <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>
+ <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>
+ </screen>
+ <para>The new directory
+ <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>
+ </step>
+ <step>
+ <title>Install Prerequisites to Build OpenSRF</title>
+ <para>In this section you will install and configure a set of prerequisites that will be
+ used to build OpenSRF. In a following step you will actually build the OpenSRF software
+ using the <command>make</command> utility.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
+ below to build the prerequisites from the software distribution that you just downloaded
+ and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
+ example with the keyword corresponding to the name of one of the
+ <systemitem class="osname">Linux</systemitem> distributions listed in the following
+ distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
+ For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
+ enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
+ <screen>
+ <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
+ <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
+ </screen>
+ <table xml:id="serversideinstallation-keywords-opensrf">
+ <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colnum="1" colwidth="1.0*"/>
+ <colspec colnum="2" colwidth="3.0*"/>
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+ <entry>Linux Version</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>debian-etch</entry>
+ <entry>Debian "Etch" (4.0)</entry>
+ </row>
+ <row>
+ <entry>debian-lenny</entry>
+ <entry>Debian "Lenny" (5.0)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-hardy</entry>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-lucid</entry>
+ <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
+ </row>
+ <row>
+ <entry>fedora13</entry>
+ <entry>Fedora "Goddard" (13)</entry>
+ </row>
+ <row>
+ <entry>centos</entry>
+ <entry>Centos</entry>
+ </row>
+ <row>
+ <entry>rhel</entry>
+ <entry>RHEL</entry>
+ </row>
+ <row>
+ <entry>gentoo</entry>
+ <entry>Gentoo</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>This will install a number of packages on the system that are required by OpenSRF,
+ including some Perl modules from CPAN. You can say <literal>No</literal> 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 <literal>Yes</literal>.</para>
+ </step>
+ <step>
+ <title>Build OpenSRF</title>
+ <para>In this section you will configure, build and install the OpenSRF
+ components that support other Evergreen services.</para>
+ <substeps>
+ <step>
+ <title>Configure OpenSRF</title>
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>configure</secondary>
+ </indexterm>
+ <para>As the <systemitem class="username">opensrf</systemitem>
+ user, return to the OpenSRF build directory and use the
+ <command>configure</command> utility to prepare for the next
+ step of compiling and linking the software. If you wish to
+ include support for Python and Java, add the configuration
+ options <option>--enable-python</option> and
+ <option>--enable-java</option>, respectively:</para>
+ <screen>
+ <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
+ <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
+ <userinput>make</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Compile, Link and Install OpenSRF</title>
+ <para>As the <systemitem class="username">root</systemitem>
+ user, return to the OpenSRF build directory and use the
+ <command>make</command> utility to compile, link and install
+ OpenSRF:</para>
+ <screen>
+ <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
+ <userinput>make install</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Update the System Dynamic Library Path</title>
+ <para>You must update the system dynamic library path to force
+ your system to recognize the newly installed libraries. As the
+ <systemitem class="username">root</systemitem> user, do this by
+ creating the new file
+ <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
+ new library path, then run the command
+ <command>ldconfig</command> to automatically read the file and
+ modify the system dynamic library path:</para>
+ <screen>
+ <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>
+ <userinput>ldconfig</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Define Public and Private OpenSRF Domains</title>
+ <para>For security purposes, OpenSRF uses Jabber domains to separate services
+ into public and private realms. On a single-server system the easiest way to
+ define public and private OpenSRF domains is to define separate host names by
+ adding entries to the file <filename>/etc/hosts</filename>.</para>
+ <para>In the following steps we will use the example domains
+ <systemitem class="domainname">public.localhost</systemitem> for the public
+ domain and <systemitem class="domainname">private.localhost</systemitem>
+ for the private domain. In an upcoming step, you will configure two special
+ <systemitem class="service">ejabberd</systemitem> users
+ to handle communications for these two domains.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, edit the file
+ <filename>/etc/hosts</filename> and add the following example domains:</para>
+ <indexterm>
+ <primary>Jabber</primary>
+ </indexterm>
+ <screen>
+ <userinput>127.0.1.2 public.localhost public</userinput>
+ <userinput>127.0.1.3 private.localhost private</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Change File Ownerships</title>
+ <para>Finally, as the <systemitem class="username">root</systemitem>
+ user, change the ownership of all files installed in the
+ directory <filename class="directory">/openils</filename> to the
+ user <systemitem class="username">opensrf</systemitem>:</para>
+ <screen>
+ <userinput>chown -R opensrf:opensrf /openils</userinput>
+ </screen>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
+ <indexterm>
+ <primary>ejabberd</primary>
+ </indexterm>
+ <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
+ you must stop that service. As the <systemitem class="username">root</systemitem> user,
+ execute the following command to stop the service:</para>
+ <screen>
+ <userinput>/etc/init.d/ejabberd stop</userinput>
+ </screen>
+ <para>If <systemitem class="service">ejabberd</systemitem> reports that it
+ is already stopped, there may have been a problem when it started back
+ in the installation step. If there are any remaining daemon processes such as
+ <systemitem class="daemon">beam</systemitem> or
+ <systemitem class="daemon">epmd</systemitem>
+ you may need to perform the following commands to kill them:</para>
+ <screen>
+ <userinput>epmd -kill</userinput>
+ <userinput>killall beam; killall beam.smp</userinput>
+ <userinput>rm /var/lib/ejabberd/*</userinput>
+ <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
+ <para>You must make several configuration changes for the
+ <systemitem class="service">ejabberd</systemitem> service before
+ it is started again.
+ As the <systemitem class="username">root</systemitem> user, edit the file
+ <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Change the line:
+ <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>
+ to:
+ <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>
+ </listitem>
+ <listitem>
+ <para>Change the line:
+ <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to:
+ <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>
+ <para>If the line looks something like this:
+ <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>
+ then change it to:
+ <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>
+ </listitem>
+ <listitem>
+ <para>Change all three occurrences of: <literal>max_stanza_size</literal>
+ to: <literal>2000000</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Change both occurrences of: <literal>maxrate</literal> to:
+ <literal>500000</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Comment out the line <literal>{mod_offline, []}</literal>
+ by placing two <literal>%</literal> comment signs in front.</para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step xml:id="serversideinstallation-opensrf-continued">
+ <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
+ <para>As the <systemitem class="username">root</systemitem> user, restart the
+ <systemitem class="service">ejabberd</systemitem> service to test the
+ configuration changes and to register your users:</para>
+ <screen>
+ <userinput>/etc/init.d/ejabberd start</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Register <systemitem class="username">router</systemitem> and
+ <systemitem class="username">ejabberd</systemitem> users</title>
+ <para>The two <systemitem class="service">ejabberd</systemitem> users
+ <systemitem class="username">router</systemitem> and
+ <systemitem class="username">opensrf</systemitem> must be registered
+ and configured to manage OpenSRF router service and communications
+ for the two domains <literal>public.localhost</literal> and
+ <literal>private.localhost</literal>
+ that you added to the file <filename>/etc/hosts</filename>
+ in a previous step:</para>
+ <itemizedlist>
+ <listitem>
+ <para>the <systemitem class="username">router</systemitem> user,
+ to whom all requests to connect to an OpenSRF service will be
+ routed;</para>
+ </listitem>
+ <listitem>
+ <para>the <systemitem class="username">opensrf</systemitem> user,
+ which clients use to connect to OpenSRF services (you may name
+ the user anything you like, but we use
+ <literal>opensrf</literal> in these examples)</para>
+ </listitem>
+ </itemizedlist>
+ <para>As the <systemitem class="username">root</systemitem> user, execute the
+ <command>ejabberdctl</command> utility as shown below to register and create passwords
+ for the users <systemitem class="username">router</systemitem> and
+ <systemitem class="username">opensrf</systemitem> on each domain:</para>
+ <screen>
+ <prompt># The syntax for registering a user with ejabberdctl is:</prompt>
+ <prompt># ejabberdctl register USER DOMAIN PASSWORD</prompt>
+ <userinput>ejabberdctl register router private.localhost NEWPASSWORD</userinput>
+ <userinput>ejabberdctl register router public.localhost NEWPASSWORD</userinput>
+ <userinput>ejabberdctl register opensrf private.localhost NEWPASSWORD</userinput>
+ <userinput>ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
+ </screen>
+ <para>Note that the users <systemitem class="username">router</systemitem> and
+ <systemitem class="username">opensrf</systemitem> and their respective passwords
+ will be used again in the file <filename>/openils/conf/opensrf_core.xml</filename>
+ in the next steps.</para>
+ </step>
+ <step>
+ <title>Create OpenSRF configuration files</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following commands to create the new configuration files
+ <filename>/openils/conf/opensrf_core.xml</filename> and
+ <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
+ <screen>
+ <userinput>cd /openils/conf</userinput>
+ <userinput>cp opensrf.xml.example opensrf.xml</userinput>
+ <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Update usernames and passwords in the OpenSRF configuration file</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
+ OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
+ and update the usernames and passwords to match the values shown in the
+ following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
+ shows common XPath syntax to indicate the approximate position within the XML
+ file that needs changes. The right-hand side of the table shows the replacement
+ values:</para>
+ <table xml:id="serversideinstallation-xpath-table-1">
+ <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
+ <colspec colname="Value" colnum="2" colwidth="2.0*"/>
+ <thead>
+ <row>
+ <entry>XPath location</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>/config/opensrf/username</entry>
+ <entry>
+ <systemitem class="username">opensrf</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/opensrf/passwd </entry>
+ <entry><systemitem class="domainname">private.localhost</systemitem>
+ password for
+ <systemitem class="username">opensrf</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/gateway/username</entry>
+ <entry>
+ <systemitem class="username">opensrf</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/gateway/passwd</entry>
+ <entry><systemitem class="domainname">public.localhost</systemitem>
+ password for
+ <systemitem class="username">opensrf</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/username,
+ first entry where server == public.localhost</entry>
+ <entry>
+ <systemitem class="username">router</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/password,
+ first entry where server == public.localhost</entry>
+ <entry><systemitem class="domainname">public.localhost</systemitem>
+ password for
+ <systemitem class="username">router</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/username,
+ second entry where server == private.localhost</entry>
+ <entry>
+ <systemitem class="username">router</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/password,
+ second entry where server == private.localhost</entry>
+ <entry><systemitem class="domainname">private.localhost</systemitem>
+ password for
+ <systemitem class="username">router</systemitem> user
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>You may also need to modify the file to specify the domains from which
+ <systemitem class="service">OpenSRF</systemitem> will accept connections,
+ and to which it will make connections.
+ If you are installing <application>OpenSRF</application> on a single server
+ and using the <systemitem class="domainname">private.localhost</systemitem> and
+ <systemitem class="domainname">public.localhost</systemitem> domains,
+ these will already be set to the correct values. Otherwise, search and replace
+ to match values for your own systems.</para>
+ </step>
+ <step>
+ <title>Set location of the persistent database</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
+ file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the
+ element <literal>dbfile</literal> (near the end of the file) to set the
+ location of the persistent database:</para>
+ <programlisting language="xml"><![CDATA[
+<!-- Example of an app-specific setting override -->
+<opensrf.persist>
+ <app_settings>
+ <dbfile>/tmp/persist.db</dbfile>
+ </app_settings>
+</opensrf.persist>
+]]></programlisting>
+ </step>
+ <step xml:id="serversideinstallation-srfsh">
+ <title>Create configuration files for users needing <command>srfsh</command></title>
+ <para>In this section you will set up a special configuration file for each user
+ who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
+ shell</emphasis>) utility.</para>
+ <indexterm>
+ <primary>srfsh</primary>
+ </indexterm>
+ <para>The software installation will automatically create a utility named
+ <command>srfsh</command> (surf shell). This is a command line diagnostic tool for testing
+ and interacting with <application>OpenSRF</application>. It will be used in a future
+ step to complete and test the Evergreen installation.
+ See <xref linkend="serversideinstallation-testing"/> for further information.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, copy the short
+ sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
+ to <filename>~/.srfsh.xml</filename> (note the leading dot!), the home
+ directory of each user who will use <command>srfsh</command>. Finally, edit each
+ file <filename>~/.srfsh.xml</filename> and make the following changes; when you
+ finish, remember to change the owner of the file to match the owner of the home
+ directory:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Modify <literal>domain</literal> to be the router hostname
+ (following our domain examples,
+ <systemitem class="domainname">private.localhost</systemitem> will give
+ <command>srfsh</command> access to all OpenSRF services, while
+ <systemitem class="domainname">public.localhost</systemitem>
+ will only allow access to those OpenSRF services that are
+ publicly exposed).</para>
+ </listitem>
+ <listitem>
+ <para>Modify <literal>username</literal> and
+ <literal>password</literal> to match the
+ <literal>opensrf</literal> Jabber user for the chosen
+ domain</para>
+ </listitem>
+ <listitem>
+ <para>Modify <literal>logfile</literal> to be the full path for
+ a log file to which the user has write access</para>
+ </listitem>
+ <listitem>
+ <para>Modify <literal>loglevel</literal> as needed for testing</para>
+ </listitem>
+ </itemizedlist>
+ <programlisting language="xml"><![CDATA[
+<?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>SOMEPASSWORD</passwd>
+<port>5222</port>
+<logfile>/tmp/srfsh.log</logfile>
+<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
+<loglevel>4</loglevel>
+</srfsh>
+]]></programlisting>
+ </step>
+ <step>
+ <title>Modify the environmental variable <envar>PATH</envar> for the
+ <systemitem class="username">opensrf</systemitem> user</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
+ environmental variable <envar>PATH</envar> by adding a new file path to the
+ <systemitem class="username">opensrf</systemitem> user's shell configuration
+ file <filename>~/.bashrc</filename>:</para>
+ <screen>
+ <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Start OpenSRF</title>
+ <para>As the <systemitem class="username">root</systemitem> user, start the
+ <systemitem class="service">ejabberd</systemitem> and
+ <systemitem class="service">memcached</systemitem> services:</para>
+ <screen>
+ <userinput>/etc/init.d/ejabberd start</userinput>
+ <userinput>/etc/init.d/memcached start</userinput>
+ </screen>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ start OpenSRF as follows:</para>
+ <screen>
+ <userinput>osrf_ctl.sh -l -a start_all</userinput>
+ </screen>
+ <para>The flag <option>-l</option> forces Evergreen to use
+ <systemitem class="domainname">localhost</systemitem> (your current system)
+ as the hostname. The flag <option>-a start_all</option> starts the other
+ OpenSRF <systemitem class="service">router</systemitem> ,
+ <systemitem class="service">Perl</systemitem> , and
+ <systemitem class="service">C</systemitem> services.</para>
+ <itemizedlist>
+ <listitem>
+ <para>You can also start Evergreen without the
+ <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
+ utility must know the fully qualified domain name for the system
+ on which it will execute. That hostname was probably specified
+ in the configuration file <filename>opensrf.xml</filename> which
+ you configured in a previous step.</para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to
+ <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
+ environment variable <envar>PATH</envar> does not include the
+ directory <filename class="directory">/openils/bin</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PATH=$PATH:/openils/bin</literal></para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <title>Test connections to OpenSRF</title>
+ <para>Once you have installed and started OpenSRF, as the
+ <systemitem class="username">root</systemitem> user, test your connection to
+ <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
+ utility and trying to call the <command>add</command> method on the OpenSRF
+ <systemitem class="service">math</systemitem> service:</para>
+ <screen>
+ <userinput>/openils/bin/srfsh</userinput>
+ <computeroutput>srfsh#</computeroutput>
+ <computeroutput>request opensrf.math add 2 2</computeroutput>
+ <computeroutput>Received Data: 4</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ <computeroutput>Request Completed Successfully</computeroutput>
+ <computeroutput>Request Time in seconds: 0.007519</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ <computeroutput>srfsh#</computeroutput>
+ </screen>
+ <para>For other <command>srfsh</command> commands, type in
+ <userinput>help</userinput> at the prompt.</para>
+ </step>
+ <step>
+ <title>Stop OpenSRF</title>
+ <para>After OpenSRF has started, you can stop it at any time by using the
+ <command>osrf_ctl.sh</command> again. As the
+ <systemitem class="username">opensrf</systemitem>
+ user, stop OpenSRF as follows:</para>
+ <screen>
+ <userinput>osrf_ctl.sh -l -a stop_all</userinput>
+ </screen>
+ </step>
+ </procedure>
+ </section>
+ <section xml:id="serversideinstallation-ubuntudebian">
+ <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or
+ <systemitem class="osname">Debian</systemitem></title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Debian</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Ubuntu</secondary>
+ </indexterm>
+ <para>This section outlines the installation process for the latest stable version of
+ Evergreen.</para>
+ <para>In this section you will download, unpack, install, configure and test the Evergreen
+ system, including the Evergreen server and the PostgreSQL database system. You will make several
+ configuration changes and adjustments to the software, including updates to configure the system
+ for your own locale, and some updates needed to work around a few known issues.</para>
+ <note>
+ <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
+ architectures. There may be differences between the Desktop and Server editions of
+ <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
+ edition.</para>
+ <para>In the following instructions, you are asked to perform certain steps as
+ either the <systemitem class="username">root</systemitem> user, the
+ <systemitem class="username">opensrf</systemitem> user, or the
+ <systemitem class="username">postgres</systemitem> user.</para>
+ <itemizedlist>
+ <listitem>
+ <para><systemitem class="osname">Debian</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ <listitem>
+ <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>sudo su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ </itemizedlist>
+ <para>To switch from the <systemitem class="username">root</systemitem> user to a
+ different user, issue the command <command>su - USERNAME</command>. For example, to
+ switch from the <systemitem class="username">root</systemitem> user to the
+ <systemitem class="username">opensrf</systemitem> user, issue the command
+ <command>su - opensrf</command>. Once you have become a non-root user, to become the
+ <systemitem class="username">root</systemitem> user again, simply issue the command
+ <command>exit</command>.</para>
+ </note>
+ <procedure>
+ <step>
+ <title>Install OpenSRF</title>
+ <para>Evergreen software is integrated with and depends on the Open Service
+ Request Framework (OpenSRF) software system. For further information on
+ installing, configuring and testing OpenSRF, see
+ <xref linkend="serversideinstallation-opensrf"/>.</para>
+ <para>Follow the steps outlined in that section and run the specified tests to
+ ensure that OpenSRF is properly installed and configured. Do
+ <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
+ any further Evergreen installation steps until you have verified that OpenSRF
+ has been successfully installed and tested.</para>
+ </step>
+ <step>
+ <title>Download and Unpack Latest Evergreen Version</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, download
+ and extract the latest version of Evergreen. The latest version can be found here:
+ <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>
+ <screen>
+ <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
+ <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>
+ </screen>
+ <para>The new directory
+ <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>
+ will be created.</para>
+ </step>
+ <step>
+ <title>Install Prerequisites to Build Evergreen</title>
+ <para>In this section you will install and configure a set of prerequisites that
+ will be used to build Evergreen. In a following step you will actually build the
+ Evergreen software using the <command>make</command> utility.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
+ below to build the prerequisites from the software distribution that you just downloaded
+ and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
+ example with the keyword corresponding to the name of one of the
+ <systemitem class="osname">Linux</systemitem> distributions listed in the following distribution
+ keywords table <xref linkend="serversideinstallation-keywords-evergreen"/> . For example,
+ to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would enter this
+ command: <command>make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic</command>.</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
+ </screen>
+ <table xml:id="serversideinstallation-keywords-evergreen">
+ <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colnum="1" colwidth="1.0*"/>
+ <colspec colnum="2" colwidth="3.0*"/>
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+ <entry>Linux Version</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>debian-etch</entry>
+ <entry>Debian "Etch" (4.0)</entry>
+ </row>
+ <row>
+ <entry>debian-lenny</entry>
+ <entry>Debian "Lenny" (5.0)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-hardy</entry>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-intrepid</entry>
+ <entry>Ubuntu "Intrepid Ibex" (8.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
+ </row>
+ <row>
+ <entry>centos</entry>
+ <entry>Centos</entry>
+ </row>
+ <row>
+ <entry>rhel</entry>
+ <entry>RHEL</entry>
+ </row>
+ <row>
+ <entry>gentoo</entry>
+ <entry>Gentoo</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </step>
+ <step performance="optional" xml:id="serversideinstallation-postgresql-default">
+ <title>(OPTIONAL) Install the PostgreSQL Server</title>
+ <indexterm>
+ <primary>databases</primary>
+ <secondary>PostgreSQL</secondary>
+ </indexterm>
+ <para>Since the PostgreSQL server is usually a standalone server in multi-server
+ production systems, the prerequisite installer Makefile in the previous step
+ does not automatically install PostgreSQL. You must install the PostgreSQL server
+ yourself, either on the same system as Evergreen itself or on another system.
+ If your PostgreSQL server is on a different system, just skip this step.</para>
+ <para>For further information on manually installing PostgreSQL, visit the official
+ <link xl:href="http://www.postgresql.org/">PostgreSQL Site</link>.</para>
+ <para>If your PostgreSQL server will be on the same system as your Evergreen
+ software, then as the <systemitem class="username">root</systemitem> user
+ install the required PostgreSQL server packages:</para>
+ <para>For <systemitem class="osname">Debian Lenny</systemitem> and
+ <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>
+ <screen>
+ <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>
+ </screen>
+ <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and
+ <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>
+ <screen>
+ <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>
+ </screen>
+ <note>
+ <para>PostgreSQL versions 8.3 or 8.4 are the recommended versions to work
+ with Evergreen 1.6. If you have an older version of PostgreSQL, you should
+ upgrade before installing Evergreen. To find the running version of
+ PostgreSQL, as the <systemitem class="username">postgres</systemitem>
+ user, run the <command>psql</command>. Then type <userinput>SELECT
+ version();</userinput> to get detailed information about your version
+ of PostgreSQL.</para>
+ </note>
+ </step>
+ <step performance="optional">
+ <title>Install Perl Modules on PostgreSQL Server</title>
+ <para>If PostgreSQL is running on the same system as your Evergreen software,
+ then the Perl modules will automatically be available. Just skip this step.
+ Otherwise, continue if your PostgreSQL server is running on another system.</para>
+ <para>You will need to install several Perl modules on the other system. As the
+ <systemitem class="username">root</systemitem> user install the following Perl
+ modules:</para>
+ <screen>
+ <prompt># first, ensure the gcc compiler is installed:</prompt>
+ <userinput>apt-get install gcc</userinput>
+ <prompt># then install the Perl modules:</prompt>
+ <userinput>perl -MCPAN -e shell</userinput>
+ <computeroutput>cpan></computeroutput>
+ <userinput>install JSON::XS</userinput>
+ <computeroutput>cpan></computeroutput>
+ <userinput>install MARC::Record</userinput>
+ <computeroutput>cpan></computeroutput>
+ <userinput>install MARC::File::XML</userinput>
+ </screen>
+ <para>For more information on installing Perl Modules vist the official
+ <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
+ <indexterm>
+ <primary>Perl</primary>
+ <secondary>CPAN</secondary>
+ </indexterm>
+ </step>
+ <step>
+ <title>Update the System Dynamic Library Path</title>
+ <para>You must update the system dynamic library path to force your system to recognize
+ the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
+ do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
+ containing a new library path, then run the command <command>ldconfig</command> to
+ automatically read the file and modify the system dynamic library path:</para>
+ <screen>
+ <userinput>echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf</userinput>
+ <userinput>echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf</userinput>
+ <userinput>ldconfig</userinput>
+ </screen>
+ </step>
+ <step performance="optional">
+ <title>Restart the PostgreSQL Server</title>
+ <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
+ the <systemitem class="username">root</systemitem> user you must restart
+ PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
+ running on another system, you may skip this step.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following command, where
+ <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL version
+ (e.g. <literal>8.3</literal>):</para>
+ <screen>
+ <userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>
+ </screen>
+ </step>
+ <step xml:id="serversideinstallation-configure">
+ <title>Configure Evergreen</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, return to
+ the Evergreen build directory and use the <command>configure</command> and
+ <command>make</command> utilities to configure Evergreen so it can be compiled
+ and linked in the next step:</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
+ <userinput>make</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Compile, Link and Install Evergreen</title>
+ <para>In this step you will actually compile, link and install Evergreen and the
+ default Evergreen Staff Client.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, return to the
+ Evergreen build directory and use the <command>make</command> utility as shown below:</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>
+ </screen>
+ <para>The Staff Client will also be automatically built, but you must remember
+ to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the Staff
+ Client you will use to connect to the Evergreen server. For further information on manually
+ building the Staff Client, see
+ <xref linkend="staffclientinstallation-building-staffclient"/>.</para>
+ <para>The above commands will create a new subdirectory
+ <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename>
+ containing the Staff Client.</para>
+ <para>To complete the Staff Client installation,
+ as the <systemitem class="username">root</systemitem> user create a symbolic link
+ named <emphasis>server</emphasis> in the head of the Staff Client directory
+ <filename class="directory">/openils/var/web/xul</filename> that points to the
+ subdirectory <filename class="directory">/server</filename> of the new Staff
+ Client build:</para>
+ <screen>
+ <userinput>cd /openils/var/web/xul</userinput>
+ <userinput>ln -sf rel_1_6_1_2/server server</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Copy the OpenSRF Configuration Files</title>
+ <para>As the <systemitem class="username">root</systemitem> user, execute the
+ following commands to copy the example OpenSRF configuration files into place
+ after first creating backup copies of the old files for troubleshooting purposes.
+ These files replace the configuration files that you set up in a previous step
+ when you installed and tested OpenSRF. Finally, change the ownership on
+ the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>
+ <screen>
+ <userinput>cd /openils/conf</userinput>
+ <userinput>cp opensrf.xml opensrf.xml.BAK</userinput>
+ <userinput>cp opensrf_core.xml opensrf_core.xml.BAK</userinput>
+ <userinput>cp opensrf.xml.example opensrf.xml</userinput>
+ <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
+ <userinput>cp oils_web.xml.example oils_web.xml</userinput>
+ <userinput>chown -R opensrf:opensrf /openils/</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Create and Configure PostgreSQL Database</title>
+ <indexterm>
+ <primary>databases</primary>
+ <secondary>PostgreSQL</secondary>
+ </indexterm>
+ <para>In this step you will create the Evergreen database. In the commands
+ below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
+ repository to match your PostgreSQL server
+ layout. For example, if you built PostgreSQL from source the path would be
+ <filename class="directory">/usr/local/share/contrib</filename>; if you
+ installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>,
+ the path would be
+ <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem>.</para>
+ <substeps>
+ <step>
+ <para>
+ <emphasis role="bold">Create and configure the database</emphasis>
+ </para>
+ <para>As the <systemitem class="username">postgres</systemitem>
+ user on the PostgreSQL system create the PostgreSQL database,
+ then set some internal paths:</para>
+ <screen>
+ <userinput>createdb evergreen -E UTF8 -T template0</userinput>
+ <userinput>createlang plperl evergreen</userinput>
+ <userinput>createlang plperlu evergreen</userinput>
+ <userinput>createlang plpgsql evergreen</userinput>
+ </screen>
+ <para>Continue as user <systemitem class="username">postgres</systemitem>
+ and execute the SQL scripts as shown below, adjusting the paths as needed, where
+ <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL
+ version (e.g. <literal>8.3</literal>).</para>
+ <screen>
+ <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>
+ <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql evergreen</userinput>
+ <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql evergreen</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
+ <para>As the <systemitem class="username">postgres</systemitem>
+ user on the PostgreSQL system, create a new PostgreSQL user
+ named <systemitem class="username">evergreen</systemitem> and
+ assign a password:</para>
+ <screen>
+ <userinput>createuser -P -s evergreen</userinput>
+ <computeroutput>Enter password for new role: <userinput>MYNEWPASSWORD</userinput></computeroutput>
+ <computeroutput>Enter it again: <userinput>MYNEWPASSWORD</userinput></computeroutput>
+ </screen>
+ </step>
+ <step>
+ <title>Create database schema</title>
+ <para>As the <systemitem class="username">root</systemitem>
+ user, create the database schema and configure your system with
+ the corresponding database authentication details for the
+ <emphasis>evergreen</emphasis> database user that you created in
+ the previous step.</para>
+ <para>Enter the following commands and replace
+ <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and
+ <emphasis>DATABASENAME</emphasis> with appropriate
+ values:</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>
+ <userinput> --service all --create-schema --create-bootstrap --create-offline \</userinput>
+ <userinput> --hostname HOSTNAME --port PORT \</userinput>
+ <userinput> --user evergreen --password PASSWORD --database DATABASENAME</userinput>
+ </screen>
+ <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
+ <emphasis role="bold">localhost</emphasis> and
+ <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
+ Of course, values for <emphasis>PASSWORD</emphasis> and
+ <emphasis>DATABASENAME</emphasis> must match the values you used in the
+ previous step when you created the database and and set a password for the
+ <systemitem class="username">evergreen</systemitem> user.</para>
+ <para>As the command executes, you may see warnings similar to:
+ <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
+ you may see one warning per schema) but they can be safely ignored.</para>
+ <note>
+ <para>If you are entering the above command on a single
+ line, do not include the <literal>\</literal>
+ (backslash) characters. If you are using the
+ <command>bash</command> shell, these should only be used
+ at the end of a line at a bash prompt to indicate that
+ the command is continued on the next line.</para>
+ </note>
+ </step>
+ <step>
+ <title>Configure the Apache web server</title>
+ <indexterm>
+ <primary>web server</primary>
+ <secondary>Apache</secondary>
+ </indexterm>
+ <para>In this step you will configure the Apache web server to
+ support Evergreen software.</para>
+ <para>First, you must enable some built-in Apache modules and install
+ some additional Apache configuration files. Then you will create a new
+ Security Certificate. Finally, you must make several changes to the Apache
+ configuration file.</para>
+ <substeps>
+ <step>
+ <title>Enable the required Apache Modules</title>
+ <para>As the <systemitem class="username">root</systemitem>
+ user, enable some modules in the Apache server, then
+ copy the new configuration files to the Apache server
+ directories:</para>
+ <screen>
+ <userinput>a2enmod ssl # enable mod_ssl</userinput>
+ <userinput>a2enmod rewrite # enable mod_rewrite</userinput>
+ <userinput>a2enmod expires # enable mod_expires</userinput>
+ </screen>
+ <para>As the commands execute, you may see warnings similar to:
+ <literal>Module SOMEMODULE already enabled</literal>
+ but you can safely ignore them.</para>
+ </step>
+ <step>
+ <title>Copy Apache configuration files</title>
+ <para>You must copy the Apache configuration
+ files from the Evergreen installation directory
+ to the Apache directory. As the
+ <systemitem class="username">root</systemitem>
+ user, perform the following commands:</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
+ <userinput>cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/</userinput>
+ <userinput>cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/</userinput>
+ <userinput>cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Create a Security Certificate</title>
+ <para>You must create a new Security Certificate (SSL Key)
+ for the Apache server using the <command>openssl</command>
+ command. For a public production server you must configure
+ or purchase a signed SSL certificate, but for now you can
+ just use a self-signed certificate and accept the warnings
+ in the Staff Client and browser during testing and
+ development. As the
+ <systemitem class="username">root</systemitem> user,
+ perform the following commands:</para>
+ <screen>
+ <userinput>mkdir /etc/apache2/ssl</userinput>
+ <userinput>cd /etc/apache2/ssl</userinput>
+ <userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
+ </screen>
+ <note>
+ <para>This step generates a self-signed SSL
+ certificate. You must install a proper SSL
+ certificate for a public production system to
+ avoid warning messages when users login to their
+ account through the OPAC or when staff login
+ through the Staff Client.</para>
+ <para>For further information on getting a proper
+ SSL certificate, see
+ <xref linkend="serversideinstallation-ssl"/>.</para>
+ </note>
+ </step>
+ <step xml:id="serversideinstallation-modify-apache">
+ <title>Update Apache configuration file</title>
+ <para>You must make several changes to the new Apache
+ configuration file
+ <filename>/etc/apache2/sites-available/eg.conf</filename> .
+ As the <systemitem class="username">root</systemitem> user,
+ edit the file and make the following changes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>In the section
+ <literal><Directory "/openils/var/cgi-bin"></literal>
+ replace this line:
+ <literal>Allow from 10.0.0.0/8</literal>
+ with this line: <literal>Allow from all</literal>.</para>
+ <warning>This change allows access to your
+ configuration CGI scripts from any workstation on
+ any network. This is only a temporary change to
+ expedite testing and should be removed after you
+ have finished and successfully tested the Evergreen
+ installation. See
+ <xref linkend="serversideinstallation-postinstallation"/>
+ for further details on removing this change after
+ the Evergreen installation is complete.
+ </warning>
+ </listitem>
+ <listitem>
+ <para>Comment out the line <literal>Listen
+ 443</literal>, since it conflicts with the
+ same declaration in the configuration file:
+ <filename>/etc/apache2/ports.conf</filename>.
+ Note that <systemitem class="osname">Debian
+ </systemitem> users should not do this
+ since the conflict does not apply to that
+ operating system.</para>
+ </listitem>
+ <listitem>
+ <para>The following updates are needed to allow
+ the logs to function properly, but it may break
+ other Apache applications on your server:</para>
+ <para>For the <systemitem class="osname">Linux</systemitem>
+ distributions <systemitem class="osname">Ubuntu
+ Hardy</systemitem> or
+ <systemitem class="osname">Debian Etch</systemitem>,
+ as the <systemitem class="username">root</systemitem>
+ user, edit the Apache configuration file
+ <filename>/etc/apache2/apache2.conf</filename> and
+ change the line <literal>User www-data</literal>
+ to <literal>User opensrf</literal>.</para>
+ <para>For the <systemitem class="osname">Linux</systemitem>
+ distributions <systemitem class="osname">Ubuntu
+ Karmic</systemitem>,
+ <systemitem class="osname">Ubuntu Lucid</systemitem>
+ or <systemitem class="osname">Debian Lenny</systemitem>,
+ as the <systemitem class="username">root</systemitem>
+ user, edit the Apache configuration file
+ and change these lines:</para>
+ <screen>
+ <userinput>export APACHE_RUN_USER=www-data</userinput>
+ <userinput>export APACHE_RUN_GROUP=www-data</userinput>
+ </screen>
+ <para>to instead read:</para>
+ <screen>
+ <userinput>export APACHE_RUN_USER=opensrf</userinput>
+ <userinput>export APACHE_RUN_GROUP=opensrf</userinput>
+ </screen>
+ </listitem>
+ <listitem>
+ <para>As the
+ <systemitem class="username">root</systemitem> user,
+ edit the Apache configuration file
+ <filename>/etc/apache2/apache2.conf</filename> and
+ modify the values for <literal>KeepAliveTimeout</literal>
+ and <literal>MaxKeepAliveRequests</literal> to match
+ the following:</para>
+ <screen>
+ <userinput>KeepAliveTimeout 1</userinput>
+ <userinput>MaxKeepAliveRequests 100</userinput>
+ </screen>
+ </listitem>
+ <listitem>
+ <para>Further configuration changes to
+ Apache may be necessary for busy systems. These
+ changes increase the number of Apache server
+ processes that are started to support additional
+ browser connections.</para>
+ <para>As the <systemitem
+ class="username">root</systemitem> user, edit the
+ Apache configuration file
+ <filename>/etc/apache2/apache2.conf</filename>,
+ locate and modify the section related to
+ <emphasis>prefork configuration</emphasis> to suit
+ the load on your system:</para>
+ <programlisting language="xml"><![CDATA[
+<IfModule mpm_prefork_module>
+ StartServers 20
+ MinSpareServers 5
+ MaxSpareServers 15
+ MaxClients 150
+ MaxRequestsPerChild 10000
+</IfModule>
+]]></programlisting>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <title>Enable the Evergreen web site</title>
+ <para>Finally, you must enable the Evergreen web site. As the
+ <systemitem class="username">root</systemitem> user, execute
+ the following Apache configuration commands to disable the default
+ <emphasis>It Works</emphasis> web page and enable the
+ Evergreen web site, and then restart the Apache server:</para>
+ <screen>
+ <prompt># disable/enable web sites</prompt>
+ <userinput>a2dissite default</userinput>
+ <userinput>a2ensite eg.conf</userinput>
+ <prompt># restart the server</prompt>
+ <userinput>/etc/init.d/apache2 reload</userinput>
+ </screen>
+ </step>
+ </substeps>
+ </step>
+ </substeps>
+ </step>
+ <step xml:id="serversideinstallation-opensrf-config">
+ <title>Update the OpenSRF Configuration File</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
+ OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
+ to update the Jabber usernames and passwords, and to specify the domain from
+ which we will accept and to which we will make connections.</para>
+ <para>If you are installing Evergreen on a single server and using the
+ <systemitem class="domainname">private.localhost</systemitem> /
+ <systemitem class="domainname">public.localhost</systemitem> domains,
+ these will already be set to the correct values. Otherwise, search and replace
+ to match your customized values.</para>
+ <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
+ shows common XPath syntax to indicate the approximate position within the XML
+ file that needs changes. The right-hand side of the table shows the replacement
+ values:</para>
+ <table xml:id="serversideinstallation-xpath-table-2">
+ <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
+ <colspec colname="Value" colnum="2" colwidth="2.0*"/>
+ <thead>
+ <row>
+ <entry>XPath location</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>/config/opensrf/username</entry>
+ <entry>
+ <systemitem class="username">opensrf</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/opensrf/passwd </entry>
+ <entry><systemitem class="domainname">private.localhost</systemitem>
+ password for
+ <systemitem class="username">opensrf</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/gateway/username</entry>
+ <entry>
+ <systemitem class="username">opensrf</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/gateway/passwd</entry>
+ <entry><systemitem class="domainname">public.localhost</systemitem>
+ password for
+ <systemitem class="username">opensrf</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/username,
+ first entry where server == public.localhost</entry>
+ <entry>
+ <systemitem class="username">router</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/password,
+ first entry where server == public.localhost</entry>
+ <entry><systemitem class="domainname">public.localhost</systemitem>
+ password for
+ <systemitem class="username">router</systemitem> user
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/username,
+ second entry where server == private.localhost</entry>
+ <entry>
+ <systemitem class="username">router</systemitem>
+ </entry>
+ </row>
+ <row>
+ <entry>/config/routers/router/transport/password,
+ second entry where server == private.localhost</entry>
+ <entry><systemitem class="domainname">private.localhost</systemitem>
+ password for
+ <systemitem class="username">router</systemitem> user
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </step>
+ <step>
+ <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
+ <para>When OpenSRF was installed in a previous step (see
+ <xref linkend="serversideinstallation-opensrf"/> for further information),
+ the software installation automatically created a utility named
+ <command>srfsh</command> (surf shell). This is a command line diagnostic tool
+ for testing and interacting with <application>OpenSRF</application> It will be used
+ in a future step to complete and test the Evergreen installation. See
+ <xref linkend="serversideinstallation-testing"/> for further information.</para>
+ </step>
+ <step xml:id="serversideinstallation-opensrf-env">
+ <title>Modify the OpenSRF Environment</title>
+ <para>Modify the shell configuration file <filename>~/.bashrc</filename> for
+ user <systemitem class="username">opensrf</systemitem> by adding a Perl environmental
+ variable, then execute the shell configuration file to load the new variables into
+ your current environment.</para>
+ <note>
+ <para>
+ <emphasis>In a multi-server environment, you must add any
+ modifications to <filename>~/.bashrc</filename> to the top of
+ the file <emphasis>before</emphasis> the line
+ <literal>[ -z "$PS1" ] && return </literal>.
+ This will allow headless (scripted) logins to load the correct
+ environment.</emphasis>
+ </para>
+ </note>
+ <screen>
+ <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>
+ <userinput>. ~/.bashrc</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>(OPTIONAL) Enable and Disable Language Localizations</title>
+ <para>You can load translations such as Armenian (hy-AM), Canadian French
+ (fr-CA), and others into the database to complete the translations available in
+ the OPAC and Staff Client. For further information, see <xref linkend="enabling_and_disabling_localization"/>.</para>
+ </step>
+ </procedure>
+ </section>
+ <section xml:id="serversideinstallation-starting">
+ <title>Starting Evergreen</title>
+ <procedure>
+ <step>
+ <para>As the <systemitem class="username">root</systemitem>
+ user, start the <systemitem class="service">ejabberd</systemitem> and
+ <systemitem class="service">memcached</systemitem> services as follows:</para>
+ <screen>
+ <userinput>/etc/init.d/ejabberd start</userinput>
+ <userinput>/etc/init.d/memcached start</userinput>
+ </screen>
+ </step>
+ <step>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ start Evergreen as follows:</para>
+ <screen>
+ <userinput>osrf_ctl.sh -l -a start_all</userinput>
+ </screen>
+ <para>The flag <option>-l</option> forces Evergreen to use
+ <systemitem class="domainname">localhost</systemitem> (your current system)
+ as the hostname. The flag <option>-a start_all</option> starts the other
+ OpenSRF <systemitem class="service">router</systemitem> ,
+ <systemitem class="service">Perl</systemitem> , and
+ <systemitem class="service">C</systemitem> services.</para>
+ <itemizedlist>
+ <listitem>
+ <para>You can also start Evergreen without the
+ <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
+ utility must know the fully qualified domain name for the system
+ on which it will execute. That hostname was probably specified
+ in the configuration file <filename>opensrf.xml</filename> which
+ you configured in a previous step.</para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to
+ <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
+ environment variable <envar>PATH</envar> does not include the
+ directory <filename class="directory">/openils/bin</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PATH=$PATH:/openils/bin</literal></para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to <emphasis>Can't
+ locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
+ aborted</emphasis>, then your environment variable
+ <emphasis role="bold">PERL5LIB</emphasis> does not include the
+ directory <filename class="directory">/openils/lib/perl5</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <para>In this step you will generate the Web files needed by the Staff Client
+ and catalog, and calculate the proximity of locations in the Organizational Unit
+ tree (which allows <emphasis>Holds</emphasis> to work properly). You must do
+ this the first time you start Evergreen and after making any changes to the
+ library hierarchy. As the <systemitem class="username">opensrf</systemitem>
+ user, execute the following commands:</para>
+ <screen>
+ <userinput>cd /openils/bin</userinput>
+ <userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
+ <computeroutput>Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'</computeroutput>
+ <computeroutput>Updating fieldmapper</computeroutput>
+ </screen>
+ </step>
+ <step>
+ <para>As the <systemitem class="username">root</systemitem> user, restart the
+ Apache Web server:</para>
+ <screen>
+ <userinput>/etc/init.d/apache2 restart</userinput>
+ </screen>
+ <note>
+ <para>If the Apache Web server was running when you started the OpenSRF
+ services, you might not be able to successfully log into the OPAC or
+ Staff Client until the Apache Web server has been restarted.</para>
+ </note>
+ </step>
+ </procedure>
+ </section>
+ <section xml:id="serversideinstallation-testing">
+ <title>Testing Your Evergreen Installation</title>
+ <para>This section describes several simple tests you can perform to verify that the Evergreen
+ server-side software has been installed and configured properly and is running as
+ expected.</para>
+ <simplesect xml:id="serversideinstallation-testing-connections">
+ <title>Testing Connections to Evergreen</title>
+
+ <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
+ <command>srfsh</command> application and try logging onto the Evergreen server using the default
+ administrator username and password. Following is sample output generated by executing
+ <command>srfsh</command> after a successful Evergreen installation. For help with
+ <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
+ Execute the following commands to test your Evergreen connection:</para>
+ <screen>
+ <userinput>/openils/bin/srfsh</userinput>
+ <computeroutput>srfsh%</computeroutput>
+ <userinput>login admin open-ils</userinput>
+ <computeroutput>Received Data: "250bf1518c7527a03249858687714376"</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ <computeroutput>Request Completed Successfully</computeroutput>
+ <computeroutput>Request Time in seconds: 0.045286</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ <computeroutput>Received Data: {</computeroutput>
+ <computeroutput> "ilsevent":0,</computeroutput>
+ <computeroutput> "textcode":"SUCCESS",</computeroutput>
+ <computeroutput> "desc":" ",</computeroutput>
+ <computeroutput> "pid":21616,</computeroutput>
+ <computeroutput> "stacktrace":"oils_auth.c:304",</computeroutput>
+ <computeroutput> "payload":{</computeroutput>
+ <computeroutput> "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",</computeroutput>
+ <computeroutput> "authtime":420</computeroutput>
+ <computeroutput> }</computeroutput>
+ <computeroutput>}</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ <computeroutput>Request Completed Successfully</computeroutput>
+ <computeroutput>Request Time in seconds: 1.336568</computeroutput>
+ <computeroutput>------------------------------------</computeroutput>
+ </screen>
+ <para>If this does not work, try the following:</para>
+ <itemizedlist>
+ <listitem>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run the
+ <filename>settings-tester.pl</filename> utility to review your Evergreen
+ installation for any system configuration problems:</para>
+ <screen>
+ <userinput>cd /home/opensrf</userinput>
+ <userinput>./Evergreen-ILS-1.6.1.2/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
+ </screen>
+ <para>If the output of <command>settings-tester.pl</command> does not help you
+ find the problem, please do not make any significant changes to your
+ configuration.</para>
+ </listitem>
+ <listitem>
+ <para>Follow the steps in the troubleshooting guide in
+ <xref linkend="troubleshooting"/>.</para>
+ </listitem>
+ <listitem>
+ <para>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 and contact the
+ <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
+ list for assistance before making any drastic changes to your system
+ configuration.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ </section>
+ <section xml:id="serversideinstallation-postinstallation">
+ <title>Post-Installation Chores</title>
+ <para>There are several additional steps you may need to complete after Evergreen has been
+ successfully installed and tested. Some steps may not be needed (e.g., setting up support for
+ Reports).</para>
+ <section>
+ <title>Remove temporary Apache configuration changes</title>
+ <para>You modified the Apache configuration file
+ <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
+ temporary measure to expedite testing (see
+ <xref linkend="serversideinstallation-modify-apache"/> for further information).
+ Those changes must now be reversed in order to deny unwanted access to your CGI
+ scripts from users on other public networks.</para>
+ <warning>
+ <para>
+ <emphasis>This temporary network update was done to expedite
+ testing. You <emphasis role="bold"> must</emphasis> correct
+ this for a public production system.</emphasis>
+ </para>
+ </warning>
+ <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
+ file again and comment out the line <literal>Allow from all</literal> and uncomment the
+ line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
+ address scheme.</para>
+ </section>
+ <section>
+ <title>Configure a permanent SSL key</title>
+ <para>In a previous step, you used the command <command>openssl</command> to temporarily
+ create a new SSL key for the Apache server. This self-signed certificate was adequate
+ during testing and development, but will continue to generate warnings in the Staff Client
+ and browser. For a public production server you should configure or purchase a signed SSL
+ certificate.</para>
+ <warning>
+ <para>
+ <emphasis>The temporary SSL key was only created to expedite
+ testing. You should install a proper SSL certificate for a public
+ production system.</emphasis>
+ </para>
+ </warning>
+ </section>
+ <section>
+ <title>Set Up Support For Reports</title>
+ <para>Evergreen reports are extremely powerful but require some simple configuration.
+ This section describes starting and stopping the Reporter daemon processes.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Starting the Reporter Daemon</para>
+ <para>Once the <systemitem class="daemon">open-ils.reporter</systemitem>
+ process is running and enabled on the gateway, you can start the
+ Reporter daemon. That process periodically checks for requests for new
+ or scheduled reports, then starts them as required.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ start the Reporter daemon using the following command:</para>
+ <screen>
+ <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter</userinput>
+ <userinput>./clark-kent.pl --daemon</userinput>
+ </screen>
+ <para>You can control how the <command>clark-kent.pl</command> utility behaves
+ by specifying any of several command-line options:</para>
+ <itemizedlist>
+ <listitem><option>--sleep=interval</option> : number of seconds
+ to sleep between checks for new reports to run; defaults to
+ <literal>10</literal></listitem>
+ <listitem><option>--lockfile=filename</option> : where to place
+ the lockfile for the process; defaults to
+ <filename>/tmp/reporter-LOCK</filename></listitem>
+ <listitem><option>--concurrency=integer</option> : number of
+ Reporter daemon processes to run; defaults to
+ <literal>1</literal></listitem>
+ <listitem><option>--bootstrap=filename</option> : OpenSRF
+ bootstrap configuration file; defaults to
+ <filename>/openils/conf/opensrf_core.xml</filename></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Stopping the Reporter Daemon</para>
+ <para>To stop the Reporter daemon, you must kill the process and remove
+ the lockfile. The daemon may have just a single associated process or
+ there may be several processes if the daemon was started with the optional
+ <literal>--concurrency</literal> switch. It will also have a lockfile
+ in the default location.</para>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ execute the following shell commands:</para>
+ <screen>
+ <prompt># find and kill the process ID number(s)</prompt>
+ <userinput>kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`</userinput>
+ <prompt># remove the lock file</prompt>
+ <userinput>rm /tmp/reporter-LOCK</userinput>
+ </screen>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section xml:id="serversideinstallation-virtual">
+ <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
+ <para>This section describes the installation of Evergreen software in so-called "virtualized"
+ software environments. Evergreen software runs as a native application on any of several
+ well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>
+ distributions including <systemitem class="osname">Ubuntu</systemitem> and
+ <systemitem class="osname">Debian</systemitem> but it does not run as a native application
+ on the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
+ However, it is possible to execute Evergreen on a <systemitem class="osname">Windows</systemitem>
+ host system by running it within a virtual Linux-guest installation, which itself executes
+ on the <systemitem class="osname">Windows</systemitem> system.
+ The <systemitem class="osname">Linux</systemitem> environment is fully emulated and acts
+ (within limits) just as if it were executing on a real standalone system.</para>
+ <para>This technique of emulating a <systemitem class="osname">Linux</systemitem> environment on
+ a <systemitem class="osname">Windows</systemitem> host is a practical way to install and run an
+ Evergreen system if it is not possible to dedicate a physical machine solely as a
+ <systemitem class="osname">Linux</systemitem> host for Evergreen. This architecture is not
+ recommended for large scale systems since there are performance limitations to running Evergreen
+ in a virtualized environment. However, it is a reasonable architecture for smaller experimental
+ systems, as a proof of concept, or as a conference-room pilot.</para>
+ <simplesect>
+ <title>Installing Virtualization Software</title>
+ <para>As described above, Evergreen can be installed on top of an emulated
+ <systemitem class="osname">Linux</systemitem> environment. The
+ <systemitem class="osname">Linux</systemitem> environment, in turn, is installed
+ on top of a software application such as <application>"VirtualBox"</application>,
+ <application>"VMware"</application> or <application>"VirtualPC"</application> which must
+ first be installed on the <systemitem class="osname">Windows</systemitem> system. This
+ section contains step-by-step examples that show installing popular virtualization
+ applications on a <systemitem class="osname">Windows</systemitem> host system. Following
+ this section are further descriptions of installing
+ <systemitem class="osname">Linux</systemitem> and Evergreen systems using that
+ virtualization software.</para>
+ <simplesect>
+ <title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
+ <para>This section reviews installation of the
+ <application>"VirtualBox"</application> application on
+ <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
+ Download the latest edition of <application>VirtualBox</application> from their official website:
+ <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link>
+ and follow the on screen instructions to install the software.</para>
+ </simplesect>
+ <simplesect>
+ <title>Installing VMware Virtualization Software</title>
+ <indexterm>
+ <primary>virtualization software</primary>
+ <secondary>VMware</secondary>
+ </indexterm>
+ <para>This section reviews installation of the
+ <application>"VMware"</application> application on
+ <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
+ Find and Download the free virtual machine software of from the VMware
+ official website:
+ <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink>
+ and follow the on-screen instructions.</para>
+ </simplesect>
+ </simplesect>
+ <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">
+ <title>Installing <systemitem class="osname">Linux</systemitem> /
+ Evergreen on Virtualization Software</title>
+ <para>After the virtualization software is installed and running, there are two ways to
+ continue with installing <systemitem class="osname">Linux</systemitem> and Evergreen
+ software in the new virtualized environment:</para>
+ <orderedlist>
+ <listitem>
+ <para>Download and install a prebuilt software image that contains a
+ working <systemitem class="osname">Linux</systemitem> / Evergreen system
+ (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
+ details)</para>
+ </listitem>
+ <listitem>
+ <para>Manually install a <systemitem class="osname">Linux</systemitem>
+ guest system, then manually install Evergreen on it.</para>
+ </listitem>
+ </orderedlist>
+ <para>We review each method in the following sections.</para>
+ <simplesect xml:id="serversideinstall-virtual-prebuilt">
+ <title>Download and install a prebuilt software image</title>
+ <para>You can download a prebuilt software image that, when installed with your
+ virtualization software, emulates a
+ <systemitem class="osname">Linux</systemitem> guest system containing a running
+ Evergreen distribution. The image is essentially a snapshot of a hard disk from
+ a fully configured, functional <systemitem class="osname">Linux</systemitem>
+ system with Evergreen already installed.</para>
+ <para>We recommend this approach if you wish to get Evergreen running quickly
+ with minimal attention to configuration. After reviewing only a few
+ configuration details you can have a working Evergreen system that integrates
+ smoothly with the rest of your network. See
+ <xref linkend="serversideinstall-virtual-versions"/> for a list of prebuilt
+ software images that are currently available to download and install</para>
+ <note>DISCLAIMER: The following virtual images have been contributed by members
+ of the Evergreen community for the purposes of testing, evaluation, training,
+ and development.</note>
+ <table xml:id="serversideinstall-virtual-versions">
+ <title>Linux / Evergreen Virtual Images</title>
+ <tgroup align="left" cols="4" colsep="1" rowsep="1">
+ <colspec colnum="1" colwidth="1.0*"/>
+ <colspec colnum="2" colwidth="1.0*"/>
+ <colspec colnum="3" colwidth="3.0*"/>
+ <colspec colnum="4" colwidth="1.0*"/>
+ <thead>
+ <row>
+ <entry>Linux Version</entry>
+ <entry>Evergreen Version</entry>
+ <entry>Image</entry>
+ <entry>Comments</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Debian lenny (5.0)</entry>
+ <entry>1.6.0.1</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip"> download </ulink>
+ </entry>
+ <entry>VirtualBox image</entry>
+ </row>
+ <row>
+ <entry>Ubuntu karmic koala (9.10)</entry>
+ <entry>1.6.0.0</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip"> download </ulink>
+ </entry>
+ <entry>VirtualBox image</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <procedure>
+ <title>VirtualBox Example</title>
+ <indexterm>
+ <primary>virtualization software</primary>
+ <secondary>VirtualBox</secondary>
+ </indexterm>
+ <step>
+ <para>Start VirtualBox for the first time and select
+ <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media
+ Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>
+ to locate the prebuilt software image just downloaded (the
+ example shows it was extracted from the original
+ <filename class="extension">zip</filename> file into a temporary directory
+ <filename class="directory">C:\temp</filename>).</para>
+ </step>
+ <step>
+ <para>After selecting the file, click <guibutton>Open</guibutton> to import it.</para>
+ </step>
+ <step>
+ <para>Then click <guibutton>OK</guibutton> to save the selection
+ and return to the VirtualBox Media Manager</para>
+ </step>
+ <step>
+ <para>Click <guibutton>New</guibutton>, then <guibutton>Next</guibutton> to continue
+ and create a new virtual machine (VM).</para>
+ </step>
+ <step>
+ <para>Create a new name for the VM and set the operating system
+ type, then click <guibutton>Next</guibutton>.</para>
+ </step>
+ <step>
+ <para>Set the memory size (at least 512Mb),
+ then click <guibutton>Next</guibutton>.</para>
+ </step>
+ <step>
+ <para>Edit the Virtual Hard Disk configuration settings; click
+ the radio boxes <guilabel>Boot Hard Disk</guilabel> and
+ <guilabel>Use existing hard disk</guilabel>
+ and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel>
+ is selected. Click <guibutton>Finish</guibutton> to finish the
+ setup.</para>
+ </step>
+ <step>
+ <para>Install the <application>VirtualBox Guest
+ Additions</application> (really a required upgrade to
+ VirtualBox)</para>
+ </step>
+ <step>
+ <para>Return to VirtualBox and see the summary of the VM just
+ created. Click <guibutton>Start</guibutton> to boot the new VM.</para>
+ </step>
+ <step>
+ <para>See the start of the <systemitem class="osname">Linux</systemitem>
+ boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel
+ 2.6.26-2-686</guimenuitem> from the startup menu and click
+ <guibutton>Enter</guibutton> to start
+ <systemitem class="osname">Linux</systemitem> and Evergreen.
+ After some delay you should see the command line prompt
+ <prompt>debian-lenny login:</prompt>. Log in with username
+ <userinput>root</userinput> and password <userinput>evergreen</userinput>
+ to continue.</para>
+ </step>
+ </procedure>
+ </simplesect>
+ </simplesect>
+ </section>
+ </section>
+</chapter>
--
2.11.0