[working/Evergreen.git] / 2.0 / admin / serversideinstallation_2.0.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="serversideinstallation" xml:lang="EN" 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>
        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">
                <?dbfo keep-together="always" ?>
                <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>2.0</entry>
                                        <entry>1.6.3</entry>
                                        <entry>8.4</entry>
                                </row>
                                <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-2.0.0">
                        <indexterm>
                                <primary>OpenSRF</primary>
                                <secondary>installation</secondary>
                        </indexterm>
                        <title>Installing OpenSRF 2.0.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) architecture of
                                <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
                                <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
                                <systemitem class="osname">Fedora 13</systemitem> and
                                <systemitem class="osname">Fedora 14</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 New <systemitem class="username">opensrf</systemitem> User</title>
                                        <para>As the <systemitem class="username">root</systemitem> user, add the
                                        <systemitem class="username">opensrf</systemitem> user to the system.
                                        In the following example, the default shell for the 
                                        <systemitem class="username">opensrf</systemitem> user is automatically set
                                        to <command>/bin/bash</command> to inherit a reasonable environment:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        useradd -m -s /bin/bash opensrf
        passwd opensrf</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <title>Download and Unpack Latest OpenSRF Version</title>
                                        <indexterm>
                                                <primary>OpenSRF</primary>
                                                <secondary>download</secondary>
                                        </indexterm>
                                        <para>The latest version of OpenSRF can be found here:
                                        <ulink url="http://evergreen-ils.org/downloads/opensrf-2.0.0.tar.gz"></ulink> .
                                        As the <systemitem class="username">opensrf</systemitem> user, change to
                                        the directory <filename class="directory">/home/opensrf</filename> then download
                                        and extract OpenSRF. The new subdirectory
                                        <filename class="directory">/home/opensrf/opensrf-2.0.0</filename> will be created:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /home/opensrf
        wget http://evergreen-ils.org/downloads/opensrf-2.0.0.tar.gz
        tar zxf opensrf-2.0.0.tar.gz</userinput>
                                        </screen>
                                </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
                                        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>
        # as the root user:
        cd /home/opensrf/opensrf-2.0.0
        make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
                                        </screen>
                                        <table xml:id="serversideinstallation-keywords-opensrf">
                                                <?dbfo keep-together="always" ?>
                                                <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
                                                <tgroup align="left" cols="2" colsep="1" rowsep="1">
                                                        <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
                                                        <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
                                                        <thead>
                                                                <row>
                                                                        <entry>Keyword</entry>
                                                                        <entry>Linux Version</entry>
                                                                </row>
                                                        </thead>
                                                        <tbody>
                                                                <row>
                                                                        <entry>debian-squeeze</entry>
                                                                        <entry>Debian "Squeeze" (6.0)</entry>
                                                                </row>
                                                                <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>fedora13</entry>
                                                                        <entry>Fedora "Laughlin" (14)</entry>
                                                                </row>
                                                                <row>
                                                                        <entry>centos</entry>
                                                                        <entry>CentOS 5</entry>
                                                                </row>
                                                                <row>
                                                                        <entry>rhel</entry>
                                                                        <entry>Red Hat Enterprise Linux 5</entry>
                                                                </row>
                                                                <row>
                                                                        <entry>gentoo</entry>
                                                                        <entry>Gentoo</entry>
                                                                </row>
                                                        </tbody>
                                                </tgroup>
                                        </table>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>Debian</secondary>
                                        </indexterm>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>Fedora</secondary>
                                        </indexterm>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>Ubuntu</secondary>
                                        </indexterm>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>CentOS</secondary>
                                        </indexterm>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>Red Hat</secondary>
                                        </indexterm>
                                        <indexterm>
                                                <primary>Linux</primary>
                                                <secondary>Gentoo</secondary>
                                        </indexterm>
                                        <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 new 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>
        # as the opensrf user:
        cd /home/opensrf/opensrf-2.0.0
        ./configure --prefix=/openils --sysconfdir=/openils/conf
        make</userinput>
                                                        </screen>
                                                        <para>This step will take several minutes to complete.</para>
                                                </step>
                                                <step>
                                                        <title>Compile, Link and Install OpenSRF</title>
                                                        <para>As the <systemitem class="username">root</systemitem>
                                                        user, return to the new OpenSRF build directory and use the
                                                        <command>make</command> utility to compile, link and install
                                                        OpenSRF:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        cd /home/opensrf/opensrf-2.0.0
        make install</userinput>
                                                        </screen>
                                                        <para>This step will take several minutes to complete.</para>
                                                </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 two
                                                        new library paths, then execute the command
                                                        <command>ldconfig</command> to automatically read the file and
                                                        modify the system dynamic library path:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        echo "/openils/lib"   > /etc/ld.so.conf.d/osrf.conf
        echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
        ldconfig</userinput>
                                                        </screen>
                                                </step>
                                                <step xml:id="serversideinstallation-definedomains">
                                                        <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>
        # as the root user:
        127.0.1.2  public.localhost   public
        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>
        # as the root user:
        chown -R opensrf:opensrf /openils</userinput>
                                                        </screen>
                                                </step>
                                        </substeps>
                                </step>
                                <step xml:id="stop-ejabberd-service">
                                        <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>
        # as the root user:
        /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>
        # as the root user:
        epmd -kill
        killall beam; killall beam.smp
        rm /var/lib/ejabberd/*
        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>
                                        <substeps>
                                                <step>
                                                        <para>Change the line:</para>
                                                        <literal>{hosts, ["localhost"]}.</literal>
                                                        <para>to instead read:</para>
                                                        <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
                                                        <para/>
                                                </step>
                                                <step>
                                                        <para>Change the line for older versions of
                                                        <systemitem class="service">ejabberd</systemitem>:</para>
                                                        <literal>{max_user_sessions, 10}</literal>
                                                        <para>to instead read:</para>
                                                        <literal>{max_user_sessions, 10000}</literal>
                                                        <para/>
                                                        <para>Change the line for newer versions of
                                                        <systemitem class="service">ejabberd</systemitem>:</para>
                                                        <literal>{access, max_user_sessions, [{10, all}]}</literal>
                                                        <para>to instead read:</para>
                                                        <literal>{access, max_user_sessions, [{10000, all}]}</literal>
                                                </step>
                                                <step>
                                                        <para>Change all three occurrences of:</para>
                                                        <literal>max_stanza_size</literal>
                                                        <para>to instead read:</para>
                                                        <literal>2000000</literal>
                                                </step>
                                                <step>
                                                        <para>Change both occurrences of:</para>
                                                        <literal>maxrate</literal>
                                                        <para>to instead read:</para>
                                                        <literal>500000</literal>
                                                </step>
                                                <step>
                                                        <para>Comment out the line:</para>
                                                        <literal>{mod_offline, []}</literal>
                                                        <para>by placing two <literal>%</literal> comment signs in front
                                                        so it instead reads:</para>
                                                        <literal>%%{mod_offline, []}</literal>
                                                </step>
                                        </substeps>
                                </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>
        # as the root user:
        /etc/init.d/ejabberd start</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <title>Register <systemitem class="username">router</systemitem> and
                                                <systemitem class="username">opensrf</systemitem> as
                                                <systemitem class="service">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
                                        (see <xref linkend="serversideinstallation-definedomains"/>).
                                        The users include:</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 (remember to replace
                                        <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        # Note: the syntax for registering a user with ejabberdctl is:
        #    ejabberdctl register USER DOMAIN PASSWORD
        ejabberdctl register router  private.localhost NEWPASSWORD
        ejabberdctl register router  public.localhost  NEWPASSWORD
        ejabberdctl register opensrf private.localhost NEWPASSWORD
        ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>
                                        </screen>
                                        <para>The users <systemitem class="username">router</systemitem> and
                                        <systemitem class="username">opensrf</systemitem> and their respective passwords 
                                        will be used again in <xref linkend="serversideinstallation-passwords"/> when
                                        we modify the OpenSRF configuration file
                                        <filename>/openils/conf/opensrf_core.xml</filename> .</para>
                                        <note>
                                                <para>
                                                There appears to be a problem with <command>ejabberdctl</command> in
                                                that it does not escape input correctly, so a password like
                                                <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
                                                A bug against ejabberd has been filed. To register a password using
                                                <command>ejabberdctl</command> with special shell characters until such
                                                time as that bug is resolved, the workaround is to specify a
                                                double-escaped character at the command line, for example,
                                                <literal>'0P3N\\\\$RF'</literal> .</para>
                                        </note>
                                </step>
                                <step xml:id="serversideinstallation-opensrf-createconfig">
                                        <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>
        # as the opensrf user:
        cd /openils/conf
        cp opensrf.xml.example      opensrf.xml
        cp opensrf_core.xml.example opensrf_core.xml</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-passwords">
                                        <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">
                                                <?dbfo keep-together="always" ?>
                                                <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 the 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 verify that
                                        the element <literal>dbfile</literal> (near the end of the file) is set to the 
                                        location of the persistent database. If necessary, change the default line:</para>
                                        <literal>/openils/var/persist.db</literal>
                                        <para>to instead read:</para>
                                        <literal>/tmp/persist.db</literal>
                                        <para>Following is a sample modification of that portion of the file:</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 the utility
                                        <command>srfsh</command>, 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
                                        sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
                                        to the home directory of each user who will use <command>srfsh</command>. 
                                        For instance, do the following for the 
                                        <systemitem class="username">opensrf</systemitem> user:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        cp /openils/conf/srfsh.xml.example  /home/opensrf/.srfsh.xml</userinput>
                                        </screen>
                                        <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
                                        following changes:</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>
                                                <listitem>
                                                        <para>Change the owner of the file to match the owner of the
                                                        home directory</para>
                                                </listitem>
                                        </itemizedlist>
                                        <para>Following is a sample of the file:</para>
                                        <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>
        # as the opensrf user:
        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>
        # as the root user:
        /etc/init.d/ejabberd start
        /etc/init.d/memcached start</userinput>
                                        </screen>
                                        <para>Then as the <systemitem class="username">opensrf</systemitem> user,
                                        start OpenSRF as follows:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        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
                                        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> with the <command>srfsh</command> 
                                        utility and try to call the <command>add</command> method on the OpenSRF 
                                        <systemitem class="service">math</systemitem> service:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        /openils/bin/srfsh</userinput>
                                                <computeroutput>
        srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
                                                <computeroutput>
        Received Data: 4
        ------------------------------------
        Request Completed Successfully
        Request Time in seconds: 0.007519
        ------------------------------------</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>
        # as the opensrf user:
        osrf_ctl.sh -l -a stop_all</userinput>
                                        </screen>
                                </step>
                        </procedure>
                </section>
                <section xml:id="serversideinstallation-ubuntudebian">
                        <title>Installing Evergreen 2.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 on <systemitem class="osname">Ubuntu</systemitem> or 
                        <systemitem class="osname">Debian</systemitem> systems.  See 
                        <xref linkend="serversideinstallation-fedora"/> for description of a similar 
                        installation on a <systemitem class="osname">Fedora 14</systemitem> system.</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-2.0.0"/>.</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>The latest version of Evergreen can be found here:
                                        <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz"></ulink> .
                                        As the <systemitem class="username">opensrf</systemitem> user, change to
                                        the directory <filename class="directory">/home/opensrf</filename> then download
                                        and extract Evergreen. The new subdirectory
                                        <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.7</filename>
                                        will be created:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /home/opensrf
        wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz
        tar zxf Evergreen-ILS-2.0.7.tar.gz</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-installprereq">
                                        <title>Install Prerequisites to Build Evergreen</title>
                                        <para>In this section you will install and configure a set of prerequisites that will be
                                        used later in <xref linkend="serversideinstallation-configure"/> and 
                                        <xref linkend="serversideinstallation-compile"/> to 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 list.
                                        For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
                                        enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
                                        ubuntu-lucid</command>.</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
                                        </screen>
                                </step>
                                <step performance="optional">
                                        <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 section
                                        (see <xref linkend="serversideinstallation-installprereq"/>)
                                        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.
                                        If your PostgreSQL server will be on the same system as your Evergreen
                                        software, you can install the required PostgreSQL server packages as described
                                        in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official 
                                        web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
                                        for more information.</para>
                                        <note>
                                                <para>PostgreSQL version 8.4 is the minimum supported version to work 
                                                with Evergreen 2.0. If you have an older version of PostgreSQL, 
                                                you should upgrade before installing Evergreen. To find your current version 
                                                of PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
                                                user execute the command <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
                                        and install several Perl modules there. As the 
                                        <systemitem class="username">root</systemitem> user, ensure the gcc compiler
                                        is installed, then install the following Perl modules:</para>
                                        <screen>
                                                <userinput>
        aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
        perl -MCPAN -e shell
                <prompt>cpan></prompt> Business::ISBN
                <prompt>cpan></prompt> install JSON::XS
                <prompt>cpan></prompt> Library::CallNumber::LC
                <prompt>cpan></prompt> install MARC::Record
                <prompt>cpan></prompt> install MARC::File::XML
                <prompt>cpan></prompt> cpan UUID::Tiny</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 two new library paths, then run the command <command>ldconfig</command> to
                                        automatically read the file and modify the system dynamic library path:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        echo "/usr/local/lib"      > /etc/ld.so.conf.d/osrf.conf
        echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
        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 (remember to replace
                                        <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
                                        for example <literal>8.4</literal>):</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-configure">
                                        <title>Configure Evergreen</title>
                                        <para>In this step you will use the <command>configure</command> and
                                        <command>make</command> utilities to configure Evergreen so it can be compiled
                                        and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, return to
                                        the Evergreen build directory and execute these commands:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        ./configure --prefix=/openils --sysconfdir=/openils/conf
        make</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-compile">
                                        <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>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        make STAFF_CLIENT_BUILD_ID=rel_2_0_7 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_2_0_7</filename> 
                                        containing the Staff Client.</para>
                                        <para>To complete the Staff Client installation, as the
                                        <systemitem class="username">root</systemitem> user execute the following commands to
                                        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>
        # as the root user:
        cd /openils/var/web/xul
        ln -sf rel_2_0_7/server server</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <title>Copy the OpenSRF Configuration Files</title>
                                        <para>In this step you will replace some OpenSRF configuration files that you set up in
                                        <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
                                        tested OpenSRF.</para>
                                        <para>You must copy several example OpenSRF configuration files into place after first
                                        creating backup copies for troubleshooting purposes, then change all the file ownerships
                                        to <systemitem class="username">opensrf</systemitem>.
                                        As the <systemitem class="username">root</systemitem> user, execute the following
                                        commands:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        cd /openils/conf
        cp opensrf.xml        opensrf.xml.BAK
        cp opensrf_core.xml      opensrf_core.xml.BAK
        cp opensrf.xml.example      opensrf.xml
        cp opensrf_core.xml.example opensrf_core.xml
        cp oils_web.xml.example     oils_web.xml
        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> , and if you
                                        installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
                                        the path would be 
                                        <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
                                        <substeps>
                                                <step>
                                                        <title>Create and configure the database</title>
                                                        <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>
        # as the postgres user:
        createdb evergreen -E UTF8 -T template0
        createlang plperl   evergreen
        createlang plperlu  evergreen
        createlang plpgsql  evergreen</userinput>
                                                        </screen>
                                                        <para>Continue as the <systemitem class="username">postgres</systemitem> 
                                                        user and execute the SQL scripts as shown below (remember to adjust the
                                                        paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
                                                        your installed PostgreSQL version, for example
                                                        <literal>"8.4"</literal>).</para>
                                                        <screen>
                                                                <userinput>
        # as the postgres user:
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
                                                        </screen>
                                                </step>
                                                <step xml:id="serversideinstallation-postgresqlcreateuser">
                                                        <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 (remember to replace <emphasis>NEWPASSWORD</emphasis>
                                                        with an appropriate new password):</para>
                                                        <screen>
                                                                <userinput>
        # as the postgres user:
        createuser -P -s evergreen</userinput>
                                                                <computeroutput>
        Enter password for new role: <userinput>NEWPASSWORD</userinput>
        Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
                                                        </screen>
                                                </step>
                                                <step>
                                                        <title>Create database schema</title>
                                                        <para>In this step you will create the database schema and configure your
                                                        system with the corresponding database authentication details for the
                                                        <emphasis>evergreen</emphasis> database user that you just created in
                                                        <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
                                                        <para>As the <systemitem class="username">root</systemitem> user, enter
                                                        the following commands and replace <emphasis>HOSTNAME, PORT,
                                                        PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
                                                        values:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
        --service all --create-schema --create-offline \
        --hostname HOSTNAME --port PORT \
        --user evergreen --password PASSWORD \
        --database DATABASENAME --admin-user ADMIN-USER \ 
        --admin-pass ADMIN-PASSWORD </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 
                                                        <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
                                                        The <option>admin-user</option> and <option>admin-pass</option> options will 
                                                        specify the Evergreen administrator account's username and password. This was 
                                                        changed for security reasons, it was previously admin/open-ils</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>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 <command>bash</command> prompt to indicate that the command is
                                                        continued on the next line.</note>
                                                </step>
                                        </substeps>
                                </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>
                                                        <indexterm>
                                                                <primary>Apache modules</primary>
                                                        </indexterm>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        a2enmod ssl     # enable mod_ssl
        a2enmod rewrite # enable mod_rewrite
        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>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/
        cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/
        cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>
                                                        </screen>
                                                </step>
                                                <step xml:id="serversideinstallation-createsslcertificate">
                                                        <title>Create a Security Certificate</title>
                                                        <para>In this step you will 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>
        # as the root user:
        mkdir /etc/apache2/ssl
        cd /etc/apache2/ssl
        openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
                                                        </screen>
                                                        <para>You will be prompted for several items of information; enter
                                                        the appropriate information for each item. The new files
                                                        <filename>server.crt</filename> and <filename>server.key</filename> will
                                                        be created in the directory 
                                                        <filename class="directory">/etc/apache2/ssl</filename> .</para>
                                                        <note>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. For further information on
                                                        installing a proper SSL certificate, see 
                                                        <xref linkend="serversideinstallation-ssl"/>.</note>
                                                </step>
                                                <step xml:id="serversideinstallation-modify-apache">
                                                        <title>Update Apache configuration files</title>
                                                        <para>You must make several changes to an Apache configuration file.</para>
                                                        <para>As the <systemitem class="username">root</systemitem> user
                                                        edit the file <filename>/etc/apache2/sites-available/eg.conf</filename> 
                                                        and make the following changes:</para>
                                                        <itemizedlist>
                                                                <listitem>
                                                                        <para>In the section
                                                                        <literal>&lt;Directory "/openils/var/cgi-bin"></literal>
                                                                        replace the line:</para>
                                                                        <literal>Allow from 10.0.0.0/8</literal>
                                                                        <para>with the line:</para>
                                                                        <literal>Allow from all</literal>
                                                                        <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:</para>
                                                                        <literal>Listen 443</literal>
                                                                        <para>since it conflicts with the same declaration in 
                                                                        the configuration file:</para>
                                                                        <para><filename>/etc/apache2/ports.conf</filename>.</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>Edit the Apache configuration file and
                                                                        change the 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
        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 value for <literal>KeepAliveTimeout</literal>
                                                                        and <literal>MaxKeepAliveRequests</literal> to match
                                                                        the following:</para>
                                                                        <screen>
                                                                                <userinput>
        KeepAliveTimeout       1
        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>
                                                                <userinput>
        # as the root user:
        # disable/enable web sites
        a2dissite default
        a2ensite eg.conf
        # restart the server
        /etc/init.d/apache2 reload</userinput>
                                                        </screen>
                                                </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">
                                                <?dbfo keep-together="always" ?>
                                                <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 performance="optional">
                                        <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
                                        <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, 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
                                        OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
                                        Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration 
                                        file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
                                        See <xref linkend="serversideinstallation-testing"/> for further information.</para>
                                </step>
                                <step xml:id="serversideinstallation-opensrf-env">
                                        <title>Modify the OpenSRF Environment</title>
                                        <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
                                        <itemizedlist>
                                                <listitem>
                                                        <para>As the <systemitem class="username">opensrf</systemitem> user,
                                                        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>
                                                        <screen>
                                                                <userinput>
        # as the opensrf user:
        echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
        . ~/.bashrc</userinput>
                                                        </screen>
                                                        <note>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" ] &amp;&amp;
                                                        return </literal>. This will allow headless (scripted) logins to load the
                                                        correct environment.</note>
                                                </listitem>
                                        </itemizedlist>
                                </step>
                                <step performance="optional">
                                        <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="languagesandlocalization"/>.</para>
                                </step>
                        </procedure>
                </section>
                <section xml:id="serversideinstallation-fedora">
                        <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
                                <systemitem class="osname">Fedora 14</systemitem></title>
                        <indexterm>
                                <primary>Linux</primary>
                                <secondary>Fedora</secondary>
                        </indexterm>
                        <para>This section outlines the installation process for the latest stable version of
                        Evergreen on a <systemitem class="osname">Fedora 14</systemitem> system.  
                        See <xref linkend="serversideinstallation-ubuntudebian"/> for description of a 
                        similar installation on <systemitem class="osname">Ubuntu</systemitem> or 
                        <systemitem class="osname">Debian</systemitem> systems.</para>
                        <para>In the following 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) architecture of a <systemitem class="osname">Fedora 14</systemitem>
                                image as of 2011-01-27.</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">Fedora</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>
                                </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 xml:id="serversideinstallation-opensrf-2.0">
                                        <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-2.0.0"/>.</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>The latest version of Evergreen can be found here:
                                        <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz"></ulink> .
                                        As the <systemitem class="username">opensrf</systemitem> user, change to
                                        the directory <filename class="directory">/home/opensrf</filename> then 
                                        download and extract Evergreen. The new subdirectory
                                        <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.7</filename> 
                                        will be created:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /home/opensrf
        wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz
        tar zxf Evergreen-ILS-2.0.7.tar.gz</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-installprereq-2.0">
                                        <title>Install Prerequisites to Build Evergreen</title>
                                        <para>In this section you will install and configure a set of prerequisites that will be
                                        used later in <xref linkend="serversideinstallation-configure-2.0"/> and 
                                        <xref linkend="serversideinstallation-compile-2.0"/> to 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 list. For example, to install the prerequisites for
                                        <systemitem class="osname">Fedora 13</systemitem> or
                                        <systemitem class="osname">Fedora 14</systemitem>, you would enter the command:
                                        <command>make -f Open-ILS/src/extras/Makefile.install fedora13</command>.</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
                                        </screen>
                                </step>
                                <step performance="optional">
                                        <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 section
                                        (see <xref linkend="serversideinstallation-installprereq-2.0"/>)
                                        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.
                                        If your PostgreSQL server will be on the same system as your Evergreen
                                        software, you can install the required PostgreSQL server packages as described
                                        in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official 
                                        web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
                                        for more information.</para>
                                        <note>
                                                <para>PostgreSQL version 8.4 is the minimum supported version to work 
                                                with Evergreen 2.0. If you have an older version of PostgreSQL, 
                                                you should upgrade before installing Evergreen. To find your current version 
                                                of PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
                                                user execute the command <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,
                                        and install several Perl modules there. As the 
                                        <systemitem class="username">root</systemitem> user, ensure the gcc compiler
                                        is installed, then install the following Perl modules:</para>
                                        <screen>
                                                <userinput>
        yum install gcc
        perl -MCPAN -e shell
                <prompt>cpan></prompt> install JSON::XS
                <prompt>cpan></prompt> install MARC::Record
                <prompt>cpan></prompt> 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 xml:id="serversideinstallation-configure-2.0">
                                        <title>Configure Evergreen</title>
                                        <para>In this step you will use the <command>configure</command> and
                                        <command>make</command> utilities to configure Evergreen so it can be compiled
                                        and linked later in <xref linkend="serversideinstallation-compile-2.0"/>.</para>
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, return to
                                        the Evergreen build directory and execute these commands:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        ./configure --prefix=/openils --sysconfdir=/openils/conf
        make</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-compile-2.0">
                                        <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>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        make STAFF_CLIENT_BUILD_ID=rel_2_0_7 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_2_0_7</filename> 
                                        containing the Staff Client.</para>
                                        <para>To complete the Staff Client installation, as the
                                        <systemitem class="username">root</systemitem> user execute the following commands
                                        to 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>
        # as the root user:
        cd /openils/var/web/xul
        ln -sf rel_2_0_7/server server</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <title>Copy the OpenSRF Configuration Files</title>
                                        <para>In this step you will replace some OpenSRF configuration files that you set up
                                        earlier in <xref linkend="serversideinstallation-opensrf-2.0"/> when you installed
                                        and tested OpenSRF.</para>
                                        <para>You must copy several example OpenSRF configuration files into place after first
                                        creating backup copies for troubleshooting purposes, then change all the file ownerships
                                        to <systemitem class="username">opensrf</systemitem>.
                                        As the <systemitem class="username">root</systemitem> user, execute the following
                                        commands:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        cd /openils/conf
        cp opensrf.xml        opensrf.xml.BAK
        cp opensrf_core.xml      opensrf_core.xml.BAK
        cp opensrf.xml.example      opensrf.xml
        cp opensrf_core.xml.example opensrf_core.xml
        cp oils_web.xml.example     oils_web.xml
        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> 
                                        , and if you installed the PostgreSQL 8.4 server packages on 
                                        <systemitem class="osname">Ubuntu</systemitem>, the path would be 
                                        <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
                                        <substeps>
                                                <step>
                                                        <title>Start the PostgreSQL service</title>
                                                        <para>As the <systemitem class="username">root</systemitem>
                                                        user on the PostgreSQL system, initialize the PostgreSQL cluster
                                                        and start the PostgreSQL service:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        service initdb postgresql
        /etc/init.d/postgresql start</userinput>
                                                        </screen>
                                                </step>
                                                <step>
                                                        <title>Create and configure the database</title>
                                                        <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>
        # as the postgres user:
        createdb evergreen -E UTF8 -T template0
        createlang plperl   evergreen
        createlang plperlu  evergreen
        createlang plpgsql  evergreen</userinput>
                                                        </screen>
                                                        <para>Continue as the <systemitem class="username">postgres</systemitem> 
                                                        user and execute the SQL scripts as shown below (remember to adjust the 
                                                        paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
                                                        your installed PostgreSQL version, for example
                                                        <literal>"8.4"</literal>).</para>
                                                        <screen>
                                                                <userinput>
        # as the postgres user:
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
        psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
                                                        </screen>
                                                </step>
                                                <step xml:id="serversideinstallation-postgresqlcreateuser-2.0">
                                                        <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 (remember to replace <emphasis>NEWPASSWORD</emphasis>
                                                        with an appropriate new password):</para>
                                                        <screen>
                                                                <userinput>
        # as the postgres user:
        createuser -P -s evergreen</userinput>
                                                                <computeroutput>
        Enter password for new role: <userinput>NEWPASSWORD</userinput>
        Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
                                                        </screen>
                                                </step>
                                                <step>
                                                        <title>Enable IPv4 and IPv6 connections</title>
                                                        <para>As the root user, enable IPv4 and IPv6 connections to the
                                                        PostgreSQL server. For a single-server instance, enable
                                                        password-protected connections from the Evergreen user to the
                                                        Evergreen database on localhost by adding the following lines to
                                                        <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:

        # IPv4 local connections:
        host    evergreen     evergreen  127.0.0.1/32     md5
        # IPv6 local connections:
        host    evergreen     evergreen  ::1/128               md5</userinput>
                                                        </screen>
                                                        <para>Then, as the root user, restart the PostgreSQL server to
                                                        make that configuration take effect:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        /etc/init.d/postgresql restart</userinput>
                                                        </screen>
                                                </step>
                                                <step>
                                                        <title>Create database schema</title>
                                                        <para>In this step you will create the database schema and configure your
                                                        system with the corresponding database authentication details for the
                                                        <emphasis>evergreen</emphasis> database user that you just created in
                                                        <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.</para>
                                                        <para>As the <systemitem class="username">root</systemitem> user, enter
                                                        the following commands and replace <emphasis>HOSTNAME, PORT,
                                                        PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
                                                        values:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
        --service all --create-schema --create-offline \
        --hostname HOSTNAME --port PORT \
        --user evergreen --password PASSWORD \
        --database DATABASENAME --admin-user ADMIN-USER \ 
        --admin-pass ADMIN-PASSWORD </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 
                                                        <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.
                                                        The <option>admin-user</option> and <option>admin-pass</option> options will 
                                                        specify the Evergreen administrator account's username and password. This was 
                                                        changed for security reasons, it was previously admin/open-ils</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>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 <command>bash</command> prompt to indicate that the command is
                                                        continued on the next line.</note>
                                                </step>
                                        </substeps>
                                </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 install some additional Apache configuration files. Then you will
                                        create a new Security Certificate. Finally, you must make several changes to Apache
                                        configuration files.</para>
                                        <substeps>
                                                <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>
        # as the root user:
        cd /home/opensrf/Evergreen-ILS-2.0.7
        cp Open-ILS/examples/apache/eg.conf     /etc/httpd/conf.d/
        cp Open-ILS/examples/apache/eg_vhost.conf  /etc/httpd/
        cp Open-ILS/examples/apache/startup.pl     /etc/httpd/</userinput>
                                                        </screen>
                                                </step>
                                                <step xml:id="serversideinstallation-createsslcertificate-2.0">
                                                        <title>Create a Security Certificate</title>
                                                        <para>In this step you will 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>
        # as the root user:
        mkdir /etc/httpd/ssl
        cd /etc/httpd/ssl
        openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
                                                        </screen>
                                                        <para>You will be prompted for several items of information; enter
                                                        the appropriate information for each item. The new files
                                                        <filename>server.crt</filename> and <filename>server.key</filename> will
                                                        be created in the directory 
                                                        <filename class="directory">/etc/httpd/ssl</filename> .</para>
                                                        <note>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. For further information on
                                                        installing a proper SSL certificate, see 
                                                        <xref linkend="serversideinstallation-ssl"/>.</note>
                                                </step>
                                                <step xml:id="serversideinstallation-modify-apache-2.0">
                                                        <title>Update Apache configuration files</title>
                                                        <para>You must make several changes to two Apache configuration files.</para>
                                                        <para>As the <systemitem class="username">root</systemitem>
                                                        user, edit the file <filename>/etc/httpd/conf.d/eg.conf</filename> 
                                                        and make the following changes:</para>
                                                        <itemizedlist>
                                                                <listitem>
                                                                        <para>Change all instances of <literal>apache2</literal>
                                                                        to <literal>httpd</literal> .</para>
                                                                </listitem>
                                                                <listitem>
                                                                        <para>In the section
                                                                        <literal>&lt;Directory "/openils/var/cgi-bin"></literal>
                                                                        replace the line:</para>
                                                                        <literal>Allow from 10.0.0.0/8</literal>
                                                                        <para>with the line:</para>
                                                                        <literal>Allow from all</literal>
                                                                        <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:</para>
                                                                        <literal>Listen 443</literal>
                                                                        <para>since it conflicts with the same declaration in 
                                                                        the configuration file:</para>
                                                                        <para><filename>/etc/httpd/conf.d/ssl.conf</filename>.</para>
                                                                </listitem>
                                                        </itemizedlist>
                                                        <para>
                                                        As the <systemitem class="username">root</systemitem> user, edit the
                                                        Apache configuration file <filename>/etc/httpd/conf.d/httpd.conf</filename>
                                                        and make the following changes:</para>
                                                        <itemizedlist>
                                                                <listitem>
                                                                        Change <literal>User apache</literal> to
                                                                        <literal>User opensrf</literal></listitem>
                                                                <listitem>
                                                                        Change <literal>KeepAlive</literal> to
                                                                        <literal>On</literal></listitem>
                                                                <listitem>
                                                                        Change <literal>KeepAliveTimeout</literal> to
                                                                        <literal>1</literal></listitem>
                                                        </itemizedlist>
                                                </step>
                                        </substeps>
                                </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 library <literal>dbdpgsql.so</literal>. As the
                                        <systemitem class="username">root</systemitem> user, do this by creating
                                        the new file <filename>/etc/ld.so.conf.d/eg.conf</filename> containing two
                                        new library paths, then run the command <command>ldconfig</command> to
                                        automatically read the file and modify the system dynamic library
                                        path:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        echo "/usr/lib/dbd"     > /etc/ld.so.conf.d/eg.conf
        echo "/usr/lib64/dbd/" >> /etc/ld.so.conf.d/eg.conf
        ldconfig</userinput>
                                        </screen>
                                </step>
                                <step xml:id="serversideinstallation-opensrf-config-2.0">
                                        <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>
                                        and update the Jabber usernames and passwords, and 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>See the table <xref linkend="serversideinstallation-xpath-table-2"/>
                                        for examples of the XPath syntax you will find in this XML file. The syntax
                                        indicates the approximate position within the file that needs changes.</para>
                                </step>
                                <step xml:id="serversideinstallation-opensrf-env-2.0">
                                        <title>Modify the OpenSRF Environment</title>
                                        <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
                                        <itemizedlist>
                                                <listitem>
                                                        <para>As the <systemitem class="username">opensrf</systemitem> user,
                                                        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>
                                                        <screen>
                                                                <userinput>
        # as the opensrf user:
        echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
        . ~/.bashrc</userinput>
                                                        </screen>
                                                        <note>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" ] &amp;&amp;
                                                        return </literal>. This will allow headless (scripted) logins to load the
                                                        correct environment.</note>
                                                </listitem>
                                        </itemizedlist>
                                </step>
                                <step>
                                        <title>Configuring Fedora Security</title>
                                        <para><systemitem class="osname">Fedora</systemitem> is a very secure
                                        system out of the box, including a very restrictive firewall and an
                                        automatically enabled set of SELinux system policies to prevent
                                        unauthorized access to system resources. Unfortunately, these secure
                                        system policies can interfere with the normal operation of
                                        applications like Evergreen.</para>
                                        <para>Until a person with the required SELinux skills can offer a
                                        nuanced set of policies appropriate for Evergreen, the simplest way to
                                        test and develop against a <systemitem class="osname">Fedora</systemitem>
                                        server is to completely disable the firewall and SELinux policies.</para>
                                        <substeps>
                                                <step>
                                                        <title>Disabling the Fedora firewall</title>
                                                        <para>To disable the <systemitem class="osname">Fedora</systemitem>
                                                        firewall until your next reboot, issue the
                                                        following command as the root user:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        /etc/init.d/iptables stop</userinput>
                                                        </screen>
                                                        <para>To disable the <systemitem class="osname">Fedora</systemitem>
                                                        firewall permanently, issue the following
                                                        command as the root user:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        chkconfig iptables off</userinput>
                                                        </screen>
                                                        <para>This change will take effect when you reboot your system.</para>
                                                </step>
                                                <step>
                                                        <title>Disabling the SELinux policies</title>
                                                        <para>To disable the SELinux policies until your next reboot, issue
                                                        the following command as the root user:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        /usr/sbin/setenforce 0</userinput>
                                                        </screen>
                                                        <para>To disable the SELinux policies permanently, as the root user
                                                        edit the file <filename>/etc/sysconfig/selinux</filename> and make the
                                                        following change:</para>
                                                        <screen>
                                                                <userinput>
        # as the root user:
        SELINUX=permissive</userinput>
                                                        </screen>
                                                        <para>This change will take effect when you reboot your system.</para>
                                                </step>
                                        </substeps>
                                </step>
                        </procedure>
                </section>
                <section xml:id="serversideinstallation-starting">
                        <title>Starting Evergreen</title>
                        <para>In this section you will learn how to start the Evergreen services. 
                        For completeness, instructions for stopping Evergreen can be found later in 
                        <xref linkend="serversideinstallation-stopping"/>.</para>
                        <procedure>
                                <step>
                                        <para>As the <systemitem class="username">root</systemitem> user,
                                        start the <systemitem class="service">ejabberd</systemitem>,
                                        <systemitem class="service">memcached</systemitem>, and 
                                        <systemitem class="service">PostgreSQL</systemitem> services 
                                        (if they aren't already running) as follows:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        /etc/init.d/ejabberd start
        /etc/init.d/memcached start
        /etc/init.d/postgresql start</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <para>If you want to have these services run automatically every time
                                        you boot your server, issue the following commands as the root
                                        user:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        chkconfig --levels 2345 ejabberd on
        chkconfig --levels 2345 memcached on
        chkconfig --levels 2345 postgresql on</userinput>
                                        </screen>
                                </step>
                                <step>
                                        <para>As the <systemitem class="username">opensrf</systemitem> user,
                                        start the OpenSRF <systemitem class="service">router</systemitem> ,
                                        <systemitem class="service">Perl</systemitem>, and <systemitem class="service">C</systemitem> services. The <option>-l</option> flag in 
                                        the following command is only necessary if you want to force Evergreen to
                                        treat the hostname as <literal>'localhost'</literal>. You should not
                                        use the '-l' flag if you configured <filename>opensrf.xml</filename>
                                        using the real hostname of your machine as returned by: <literal>perl
                                        -ENet::Domain 'print Net::Domain::hostfqdn() . “\n”;'</literal> .
                                        As the opensrf user, execute this command:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        osrf_ctl.sh -l -a start_all</userinput>
                                        </screen>
                                        <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>~/.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>.
                                                        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:
                                                        <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, as well as update the proximity of locations in the Organizational 
                                        Unit tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
                                        <para>You must do this the first time you start Evergreen and after making any
                                        changes to the library hierarchy.</para>
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
                                        following command and review the results as shown in this example:</para>
                                        <screen>
                                                <userinput>
        # as the opensrf user:
        cd /openils/bin
        ./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
        Updating web_fieldmapper
        Updating OrgTree
        removing OrgTree from the cache for locale hy-AM...
        removing OrgTree from the cache for locale cs-CZ...
        removing OrgTree from the cache for locale en-CA...
        removing OrgTree from the cache for locale en-US...
        removing OrgTree from the cache for locale fr-CA...
        removing OrgTree from the cache for locale ru-RU...
        Updating OrgTree HTML
        Updating locales selection HTML
        Updating Search Groups
        Refreshing proximity of org units
        Successfully updated the organization proximity
        Done</computeroutput>
                                        </screen>
                                </step>
                                <step>
                                        <para>As the <systemitem class="username">root</systemitem> user, restart the
                                        Apache Web server:</para>
                                        <screen>
                                                <userinput>
        # as the root user:
        /etc/init.d/httpd restart</userinput>
                                        </screen>
                                        <note>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.</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.
                                As the <systemitem class="username">opensrf</systemitem> user,
                                execute the following command and review the results as shown in this example to test
                                your Evergreen connection:</para>
                                <screen>
                                        <userinput>
        # as the opensrf user:
        /openils/bin/srfsh</userinput>
                                        <computeroutput>
        srfsh% <userinput>login admin open-ils</userinput>
        Received Data: "250bf1518c7527a03249858687714376"
        ------------------------------------
        Request Completed Successfully
        Request Time in seconds: 0.045286
        ------------------------------------
        Received Data: {
           "ilsevent":0,
           "textcode":"SUCCESS",
           "desc":" ",
           "pid":21616,
           "stacktrace":"oils_auth.c:304",
           "payload":{
              "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
              "authtime":420
           }
        }
        ------------------------------------
        Request Completed Successfully
        Request Time in seconds: 1.336568
        ------------------------------------</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
                                                utility <filename>settings-tester.pl</filename>  to review your Evergreen
                                                installation for any system configuration problems:</para>
                                                <screen>
                                                        <userinput>
        # as the opensrf user:
        cd /home/opensrf
        ./Evergreen-ILS-2.0.7/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>
                                                for assistance before making any drastic changes to your system
                                                configuration.</para>
                                        </listitem>
                                </itemizedlist>
                        </simplesect>
                        <simplesect xml:id="serversideinstallation-running-staffclient">
                                <title>Testing the Staff Client on Linux</title>
                                <para>In this section you will confirm that a basic login on the Staff Client works
                                properly.</para>
                                <para>Run the Evergreen Staff Client on your <systemitem class="osname">Fedora</systemitem>
                                system by using the application
                                <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
                                version 3.0 and later on Ubuntu and Debian distributions).</para>
                                <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
                                as shown:</para>
                                <screen>
                                        <userinput>
        # as the root user:
        xulrunner /home/opensrf/Evergreen-ILS-2.0.7/Open-ILS/xul/staff_client/build/application.ini</userinput>
                                </screen>
                                <para>A login screen for the Staff Client similar to this should appear:</para>
                                <mediaobject>
                                        <alt>Logging into the Staff Client</alt>
                                        <imageobject>
                                                <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>
                                        </imageobject>
                                </mediaobject>
                                <para>First, add the name of your Evergreen server to the field
                                <literal>Hostname</literal> in the <literal>Server</literal> section. You will
                                probably want to use <literal>127.0.0.1</literal>. After adding the server
                                name, click <guibutton>Re-Test Server</guibutton>. You should now see the
                                messages <literal>200:OK</literal> in the fields <literal>Status</literal> and
                                <literal>Version</literal>.</para>
                                <para>Because this is the initial run of the Staff Client, you will see a warning in the
                                upper-right saying: <emphasis role="bold">Not yet configured for the specified
                                server</emphasis>. To continue, you must assign a workstation name.</para>
                                <para>Try to log into the Staff Client with the admin username and password you created
                                during installation. If the login is successful, you will see the following
                                screen:</para>
                                <mediaobject>
                                        <alt>Logging into the Staff Client</alt>
                                        <imageobject>
                                                <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>
                                        </imageobject>
                                </mediaobject>
                                <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the
                                main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>
                                <mediaobject>
                                        <alt>Adding an SSL Exception in the Staff Client</alt>
                                        <imageobject>
                                                <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>
                                        </imageobject>
                                </mediaobject>
                                <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm
                                Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the
                                main window and try to log in again.</para>
                        </simplesect>
                        <simplesect xml:id="serversideinstallation-starting-apache-server">
                                <title>Testing the Apache Web Server</title>
                                <para>In this section you will test the Apache configuration file(s), then restart the
                                Apache web server.</para>
                                <para>As the <emphasis role="bold">root</emphasis> user, execute the following
                                commands. The use of <emphasis>restart</emphasis> will force the new Evergreen
                                modules to be reloaded even if the Apache server is already running. 
                                Any problems found with your configuration files should be displayed:</para>
                                <screen>
                                        <userinput>
        # as the root user:
        /etc/init.d/httpd configtest &amp;&amp; /etc/init.d/httpd restart</userinput>
                                </screen>
                        </simplesect>
                        <simplesect xml:id="serversideinstallation-stopping">
                                <title>Stopping Evergreen</title>
                                <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the
                                Evergreen services. For completeness, following are instructions for stopping the
                                Evergreen services.</para>
                                <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
                                services by using the following command:</para>
                                <screen>
                                        <userinput>
        # as the opensrf user
        #   stop the server; use "-l" to force hostname to be "localhost"
        osrf_ctl.sh -l -a stop_all</userinput>
                                </screen>
                                <note>You can also stop Evergreen services <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.</note>
                        </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 xml:id="serversideinstallation-ssl">
                                <title>Configure a permanent SSL key</title>
                                <para>You used the command <command>openssl</command> in an earlier step to
                                temporarily create a new SSL key for the Apache server (see 
                                <xref linkend="serversideinstallation-createsslcertificate-2.0"/> for further
                                information). This self-signed security 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>
                                <para>There are several open source software solutions that provide schemes to
                                generate and maintain public key security certificates for your library
                                system. Some popular projects are listed below; please review them for
                                background information on why you need such a system and how you can provide
                                it:</para>
                                <itemizedlist>
                                        <listitem>
                                                <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
                                        </listitem>
                                        <listitem>
                                                <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
                                        </listitem>
                                        <listitem>
                                                <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
                                        </listitem>
                                </itemizedlist>
                                <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>(OPTIONAL) IP-Redirection</title>
                                <para>By default, Evergreen is configured so searching the OPAC always starts in the
                                top-level (regional) library rather than in a second-level (branch) library. Instead,
                                you can use "IP-Redirection" to change the default OPAC search location to use the IP
                                address range assigned to the second-level library where the seach originates. You must
                                configure these IP ranges by creating the configuration file
                                <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
                                <filename>/etc/apache2/startup.pl</filename>.</para>
                                <para>First, copy the sample file
                                <filename>/home/opensrf/Evergreen-ILS-2.0.0/Open-ILS/examples/lib_ips.txt.example</filename>
                                to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
                                line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
                                the IP address ranges for your library system. Add new lines to represent the IP address
                                range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
                                values for each branch library found in the table
                                <literal>actor.org_unit</literal>.</para>
                                <para>Finally, modify the Apache startup script
                                <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
                                restarting the Apache server:</para>
                                <programlisting language="xml"><![CDATA[
# - Uncomment the following 2 lines to make use of the IP redirection code
# - The IP file should contain a map with the following format:
# - actor.org_unit.shortname <start_ip> <end_ip>
# - e.g.  LIB123 10.0.0.1 10.0.0.254
use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
]]></programlisting>
                        </section>
                        <section>
                                <title>(OPTIONAL) Set Up Support For Reports</title>
                                <para>Evergreen reports are extremely powerful but require some simple configuration.
                                See <xref linkend="report_starting_reporter_service"/> for information on starting and
                                stopping the Reporter daemon processes.</para>
                        </section>
                </section>
        </section>
</chapter>