-<?xml version="1.0" encoding="UTF-8"?>\r
-<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">\r
- <info>\r
- <title>Server-side Installation of Evergreen Software</title>\r
- <abstract>\r
- <para>This section describes installation of the Evergreen server-side software and its associated components.\r
- Installation, configuration, testing and verification \r
- of the software is straightforward if you follow some simple directions.</para>\r
- </abstract>\r
- </info>\r
- <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current\r
- stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to\r
- installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating\r
- system.</para>\r
- <para>The current version of the Evergreen server-side software runs as a native application on any of several\r
- well-known <systemitem class="osname">Linux</systemitem> distributions \r
- (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>). \r
- It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem> \r
- operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP\r
- Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be\r
- installed and run on <systemitem class="osname">Windows</systemitem> via a so-called\r
- <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,\r
- <application>"VirtualBox"</application> or <application>"VMware"</application>\r
- to emulate a <systemitem class="osname">Linux</systemitem>\r
- environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem> \r
- systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or\r
- <application>"VMware"</application>). More information on virtualized environments can be found in \r
- <xref linkend="serversideinstallation-virtual"/>.</para>\r
- <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>\r
- <para>The Evergreen server-side software has dependencies on particular versions of certain major software\r
- sub-components. Successful installation of Evergreen software requires that software versions agree with those\r
- listed here:</para>\r
- <table xml:id="serversideinstall-software-dependencies">\r
- <?dbfo keep-together="always" ?>\r
- <title>Evergreen Software Dependencies</title>\r
- <indexterm>\r
- <primary>Evergreen software dependencies</primary>\r
- </indexterm>\r
- <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
- <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>\r
- <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>\r
- <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Evergreen</entry>\r
- <entry>OpenSRF</entry>\r
- <entry>PostgreSQL</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>2.0</entry>\r
- <entry>1.6.3</entry>\r
- <entry>8.4</entry>\r
- </row>\r
- <row>\r
- <entry>1.6.1.x</entry>\r
- <entry>1.4.0</entry>\r
- <entry>8.2 / 8.3</entry>\r
- </row>\r
- <row>\r
- <entry>1.6.0.x</entry>\r
- <entry>1.2</entry>\r
- <entry>8.2 / 8.3</entry>\r
- </row>\r
- <row>\r
- <entry>1.4.x</entry>\r
- <entry>1.0</entry>\r
- <entry>8.1 / 8.2</entry>\r
- </row>\r
- <row>\r
- <entry>1.2.x</entry>\r
- <entry>0.9</entry>\r
- <entry>8.1 / 8.2</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <section xml:id="serversideinstallation-all">\r
- <title>Installing Server-Side Software</title>\r
- <para>This section describes the installation of the major components of Evergreen server-side software.</para>\r
- <para>As far as possible, you should perform the following steps in the exact order given since the\r
- success of many steps relies on the successful completion of earlier steps. You should make backup\r
- copies of files and environments when you are instructed to do so. In the event of installation problems\r
- those copies can allow you to back out of a step gracefully and resume the installation from a known\r
- state. See <xref linkend="backingup"/> for further information.</para>\r
- <para>Of course, after you successfully complete and test the entire Evergreen installation you should\r
- take a final snapshot backup of your system(s). This can be the first in the series of regularly\r
- scheduled system backups that you should probably also begin.</para>\r
- <section xml:id="serversideinstallation-opensrf">\r
- <indexterm>\r
- <primary>OpenSRF</primary>\r
- <secondary>installation</secondary>\r
- </indexterm>\r
- <title>Installing OpenSRF 1.6.3 On <systemitem class="osname">Ubuntu</systemitem> or\r
- <systemitem class="osname">Debian</systemitem></title>\r
- <indexterm>\r
- <primary>Linux</primary>\r
- <secondary>Debian</secondary>\r
- </indexterm>\r
- <indexterm>\r
- <primary>Linux</primary>\r
- <secondary>Ubuntu</secondary>\r
- </indexterm>\r
- <para>This section describes the installation of the latest version of the Open Service Request\r
- Framework (OpenSRF), a major component of the Evergreen server-side software, on \r
- <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>\r
- systems. Evergreen software is integrated with and depends on the OpenSRF software\r
- system.</para>\r
- <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is\r
- properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>\r
- continue with any further Evergreen installation steps\r
- until you have verified that OpenSRF has been successfully installed and tested.</para>\r
- <note>\r
- <para>The following steps have been tested on the x86 (32-bit) architecture of\r
- <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,\r
- <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on\r
- <systemitem class="osname">Fedora 13</systemitem> and\r
- <systemitem class="osname">Fedora 14</systemitem>.</para>\r
- <para>In the following instructions, you are asked to perform certain steps as \r
- either the <systemitem class="username">root</systemitem> user, the \r
- <systemitem class="username">opensrf</systemitem> user, or the \r
- <systemitem class="username">postgres</systemitem> user.</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para><systemitem class="osname">Debian</systemitem> -- To become the\r
- <systemitem class="username">root</systemitem> user, issue the command\r
- <command>su -</command> and enter the password of the\r
- <systemitem class="username">root</systemitem> user.</para>\r
- </listitem>\r
- <listitem>\r
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
- <systemitem class="username">root</systemitem> user, issue the command\r
- <command>sudo su -</command> and enter the password of the \r
- <systemitem class="username">root</systemitem> user.</para>\r
- </listitem>\r
- </itemizedlist>\r
- <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
- different user, issue the command <command>su - USERNAME</command>. For example, to\r
- switch from the <systemitem class="username">root</systemitem> user to the \r
- <systemitem class="username">opensrf</systemitem> user, issue the command \r
- <command>su - opensrf</command>. Once you have become a non-root user, to become \r
- the <systemitem class="username">root</systemitem> user again, simply issue the command\r
- <command>exit</command>.</para>\r
- </note>\r
- <procedure>\r
- <step>\r
- <title>Add New <systemitem class="username">opensrf</systemitem> User</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, add the\r
- <systemitem class="username">opensrf</systemitem> user to the system.\r
- In the following example, the default shell for the \r
- <systemitem class="username">opensrf</systemitem> user is automatically set\r
- to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- useradd -m -s /bin/bash opensrf\r
- passwd opensrf</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Download and Unpack Latest OpenSRF Version</title>\r
- <indexterm>\r
- <primary>OpenSRF</primary>\r
- <secondary>download</secondary>\r
- </indexterm>\r
- <para>The latest version of OpenSRF can be found here:\r
- <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz"></ulink> .\r
- As the <systemitem class="username">opensrf</systemitem> user, change to\r
- the directory <filename class="directory">/home/opensrf</filename> then download\r
- and extract OpenSRF. The new subdirectory\r
- <filename class="directory">/home/opensrf/OpenSRF-1.6.3</filename> will be created:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /home/opensrf\r
- wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz\r
- tar zxf OpenSRF-1.6.3.tar.gz</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Install Prerequisites to Build OpenSRF</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be\r
- used to build OpenSRF. In a following step you will actually build the OpenSRF software \r
- using the <command>make</command> utility.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
- below to build the prerequisites from the software distribution that you just downloaded\r
- and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
- example with the keyword corresponding to the name of one of the\r
- <systemitem class="osname">Linux</systemitem> distributions listed in the\r
- distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> . \r
- For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would\r
- enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /home/opensrf/OpenSRF-1.6.3\r
- make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
- <table xml:id="serversideinstallation-keywords-opensrf">\r
- <?dbfo keep-together="always" ?>\r
- <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colname="keyword" colnum="1" colwidth="1.0*"/>\r
- <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Linux Version</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>debian-squeeze</entry>\r
- <entry>Debian "Squeeze" (6.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-etch</entry>\r
- <entry>Debian "Etch" (4.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-lenny</entry>\r
- <entry>Debian "Lenny" (5.0)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-hardy</entry>\r
- <entry>Ubuntu "Hardy Heron" (8.04)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-karmic</entry>\r
- <entry>Ubuntu "Karmic Koala" (9.10)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-lucid</entry>\r
- <entry>Ubuntu "Lucid Lynx" (10.04)</entry>\r
- </row>\r
- <row>\r
- <entry>fedora13</entry>\r
- <entry>Fedora "Goddard" (13)</entry>\r
- </row>\r
- <row>\r
- <entry>fedora13</entry>\r
- <entry>Fedora "Laughlin" (14)</entry>\r
- </row>\r
- <row>\r
- <entry>centos</entry>\r
- <entry>CentOS 5</entry>\r
- </row>\r
- <row>\r
- <entry>rhel</entry>\r
- <entry>Red Hat Enterprise Linux 5</entry>\r
- </row>\r
- <row>\r
- <entry>gentoo</entry>\r
- <entry>Gentoo</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
- <indexterm><primary>Linux</primary><secondary>Fedora</secondary></indexterm>\r
- <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
- <indexterm><primary>Linux</primary><secondary>CentOS</secondary></indexterm>\r
- <indexterm><primary>Linux</primary><secondary>Red Hat</secondary></indexterm>\r
- <indexterm><primary>Linux</primary><secondary>Gentoo</secondary></indexterm>\r
- <para>This will install a number of packages on the system that are required by OpenSRF,\r
- including some Perl modules from CPAN. You can say <literal>No</literal> to the initial\r
- CPAN configuration prompt to allow it to automatically configure itself to download and\r
- install Perl modules from CPAN. The CPAN installer will ask you a number of times whether\r
- it should install prerequisite modules - say <literal>Yes</literal>.</para>\r
- </step>\r
- <step>\r
- <title>Build OpenSRF</title>\r
- <para>In this section you will configure, build and install the OpenSRF\r
- components that support other Evergreen services.</para>\r
- <substeps>\r
- <step>\r
- <title>Configure OpenSRF</title>\r
- <indexterm>\r
- <primary>OpenSRF</primary>\r
- <secondary>configure</secondary>\r
- </indexterm>\r
- <para>As the <systemitem class="username">opensrf</systemitem>\r
- user, return to the new OpenSRF build directory and use the\r
- <command>configure</command> utility to prepare for the next\r
- step of compiling and linking the software. If you wish to\r
- include support for Python and Java, add the configuration\r
- options <option>--enable-python</option> and\r
- <option>--enable-java</option>, respectively:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /home/opensrf/OpenSRF-1.6.3\r
- ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- make</userinput>\r
-</screen>\r
- <para>This step will take several minutes to complete.</para>\r
- </step>\r
- <step>\r
- <title>Compile, Link and Install OpenSRF</title>\r
- <para>As the <systemitem class="username">root</systemitem>\r
- user, return to the new OpenSRF build directory and use the\r
- <command>make</command> utility to compile, link and install\r
- OpenSRF:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /home/opensrf/OpenSRF-1.6.3\r
- make install</userinput>\r
-</screen>\r
- <para>This step will take several minutes to complete.</para>\r
- </step>\r
- <step>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>You must update the system dynamic library path to force\r
- your system to recognize the newly installed libraries. As the\r
- <systemitem class="username">root</systemitem> user, do this by\r
- creating the new file\r
- <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing two\r
- new library paths, then execute the command\r
- <command>ldconfig</command> to automatically read the file and\r
- modify the system dynamic library path:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf\r
- echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf\r
- ldconfig</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-definedomains">\r
- <title>Define Public and Private OpenSRF Domains</title>\r
- <para>For security purposes, OpenSRF uses Jabber domains to separate services\r
- into public and private realms. On a single-server system the easiest way to\r
- define public and private OpenSRF domains is to define separate host names by \r
- adding entries to the file <filename>/etc/hosts</filename>.</para>\r
- <para>In the following steps we will use the example domains\r
- <systemitem class="domainname">public.localhost</systemitem> for the public\r
- domain and <systemitem class="domainname">private.localhost</systemitem> \r
- for the private domain. In an upcoming step, you will configure two special\r
- <systemitem class="service">ejabberd</systemitem> users\r
- to handle communications for these two domains.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
- <filename>/etc/hosts</filename> and add the following example domains:</para>\r
- <indexterm>\r
- <primary>Jabber</primary>\r
- </indexterm>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- 127.0.1.2 public.localhost public\r
- 127.0.1.3 private.localhost private</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Change File Ownerships</title>\r
- <para>Finally, as the <systemitem class="username">root</systemitem>\r
- user, change the ownership of all files installed in the\r
- directory <filename class="directory">/openils</filename> to the\r
- user <systemitem class="username">opensrf</systemitem>:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- chown -R opensrf:opensrf /openils</userinput>\r
-</screen>\r
- </step>\r
- </substeps>\r
- </step>\r
- <step xml:id="stop-ejabberd-service">\r
- <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
- <indexterm>\r
- <primary>ejabberd</primary>\r
- </indexterm>\r
- <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>\r
- you must stop that service. As the <systemitem class="username">root</systemitem> user,\r
- execute the following command to stop the service:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /etc/init.d/ejabberd stop</userinput>\r
-</screen>\r
- <para>If <systemitem class="service">ejabberd</systemitem> reports that it \r
- is already stopped, there may have been a problem when it started back\r
- in the installation step. If there are any remaining daemon processes such as\r
- <systemitem class="daemon">beam</systemitem> or\r
- <systemitem class="daemon">epmd</systemitem> \r
- you may need to perform the following commands to kill them:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- epmd -kill\r
- killall beam; killall beam.smp\r
- rm /var/lib/ejabberd/*\r
- echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
- <para>You must make several configuration changes for the\r
- <systemitem class="service">ejabberd</systemitem> service before\r
- it is started again.\r
- As the <systemitem class="username">root</systemitem> user, edit the file\r
- <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
- <substeps>\r
- <step>\r
- <para>Change the line:</para>\r
- <literal>{hosts, ["localhost"]}.</literal>\r
- <para>to instead read:</para>\r
- <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>\r
- <para/>\r
- </step>\r
- <step>\r
- <para>Change the line for older versions of <systemitem class="service">ejabberd</systemitem>:</para>\r
- <literal>{max_user_sessions, 10}</literal>\r
- <para>to instead read:</para>\r
- <literal>{max_user_sessions, 10000}</literal>\r
- <para/>\r
- <para>Change the line for newer versions of <systemitem class="service">ejabberd</systemitem>:</para>\r
- <literal>{access, max_user_sessions, [{10, all}]}</literal>\r
- <para>to instead read:</para>\r
- <literal>{access, max_user_sessions, [{10000, all}]}</literal>\r
- </step>\r
- <step>\r
- <para>Change all three occurrences of:</para>\r
- <literal>max_stanza_size</literal>\r
- <para>to instead read:</para>\r
- <literal>2000000</literal>\r
- </step>\r
- <step>\r
- <para>Change both occurrences of:</para>\r
- <literal>maxrate</literal>\r
- <para>to instead read:</para>\r
- <literal>500000</literal>\r
- </step>\r
- <step>\r
- <para>Comment out the line:</para>\r
- <literal>{mod_offline, []}</literal>\r
- <para>by placing two <literal>%</literal> comment signs in front\r
- so it instead reads:</para>\r
- <literal>%%{mod_offline, []}</literal>\r
- </step>\r
- </substeps>\r
- </step>\r
- <step xml:id="serversideinstallation-opensrf-continued">\r
- <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, restart the\r
- <systemitem class="service">ejabberd</systemitem> service to test the\r
- configuration changes and to register your users:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /etc/init.d/ejabberd start</userinput>\r
- </screen>\r
- </step>\r
- <step>\r
- <title>Register <systemitem class="username">router</systemitem> and\r
- <systemitem class="username">opensrf</systemitem> as\r
- <systemitem class="service">ejabberd</systemitem> users</title>\r
- <para>The two <systemitem class="service">ejabberd</systemitem> users \r
- <systemitem class="username">router</systemitem> and \r
- <systemitem class="username">opensrf</systemitem> must be registered \r
- and configured to manage OpenSRF router service and communications \r
- for the two domains <literal>public.localhost</literal> and\r
- <literal>private.localhost</literal> that you added to the file\r
- <filename>/etc/hosts</filename> in a previous step\r
- (see <xref linkend="serversideinstallation-definedomains"/>).\r
- The users include:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>the <systemitem class="username">router</systemitem> user,\r
- to whom all requests to connect to an OpenSRF service will be\r
- routed;</para>\r
- </listitem>\r
- <listitem>\r
- <para>the <systemitem class="username">opensrf</systemitem> user,\r
- which clients use to connect to OpenSRF services (you may name\r
- the user anything you like, but we use\r
- <literal>opensrf</literal> in these examples)</para>\r
- </listitem>\r
- </itemizedlist>\r
- <para>As the <systemitem class="username">root</systemitem> user, execute the\r
- <command>ejabberdctl</command> utility as shown below to register and create passwords\r
- for the users <systemitem class="username">router</systemitem> and\r
- <systemitem class="username">opensrf</systemitem> on each domain (remember to replace\r
- <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- # Note: the syntax for registering a user with ejabberdctl is:\r
- # ejabberdctl register USER DOMAIN PASSWORD\r
- ejabberdctl register router private.localhost NEWPASSWORD\r
- ejabberdctl register router public.localhost NEWPASSWORD\r
- ejabberdctl register opensrf private.localhost NEWPASSWORD\r
- ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>\r
-</screen>\r
- <para>The users <systemitem class="username">router</systemitem> and\r
- <systemitem class="username">opensrf</systemitem> and their respective passwords \r
- will be used again in <xref linkend="serversideinstallation-passwords"/> when\r
- we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para>\r
- <note>\r
- <para>\r
- There appears to be a problem with <command>ejabberdctl</command> in\r
- that it does not escape input correctly, so a password like\r
- <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.\r
- A bug against ejabberd has been filed. To register a password using\r
- <command>ejabberdctl</command> with special shell characters until such\r
- time as that bug is resolved, the workaround is to specify a\r
- double-escaped character at the command line, for example,\r
- <literal>'0P3N\\\\$RF'</literal> .</para>\r
- </note>\r
- </step>\r
- <step xml:id="serversideinstallation-opensrf-createconfig">\r
- <title>Create OpenSRF configuration files</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, \r
- execute the following commands to create the new configuration files\r
- <filename>/openils/conf/opensrf_core.xml</filename> and\r
- <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /openils/conf\r
- cp opensrf.xml.example opensrf.xml\r
- cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-passwords">\r
- <title>Update usernames and passwords in the OpenSRF configuration file</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
- OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>\r
- and update the usernames and passwords to match the values shown in the\r
- following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>\r
- shows common XPath syntax to indicate the approximate position within the XML\r
- file that needs changes. The right-hand side of the table shows the replacement\r
- values:</para>\r
- <table xml:id="serversideinstallation-xpath-table-1">\r
- <?dbfo keep-together="always" ?>\r
- <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>\r
- <colspec colname="Value" colnum="2" colwidth="2.0*"/>\r
- <thead>\r
- <row>\r
- <entry>XPath location</entry>\r
- <entry>Value</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>/config/opensrf/username</entry>\r
- <entry>\r
- <systemitem class="username">opensrf</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/opensrf/passwd </entry>\r
- <entry><systemitem class="domainname">private.localhost</systemitem>\r
- password for\r
- <systemitem class="username">opensrf</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/gateway/username</entry>\r
- <entry>\r
- <systemitem class="username">opensrf</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/gateway/passwd</entry>\r
- <entry><systemitem class="domainname">public.localhost</systemitem>\r
- password for\r
- <systemitem class="username">opensrf</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/username, \r
- first entry where server == public.localhost</entry>\r
- <entry>\r
- <systemitem class="username">router</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/password,\r
- first entry where server == public.localhost</entry>\r
- <entry><systemitem class="domainname">public.localhost</systemitem>\r
- password for\r
- <systemitem class="username">router</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/username,\r
- second entry where server == private.localhost</entry>\r
- <entry>\r
- <systemitem class="username">router</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/password,\r
- second entry where server == private.localhost</entry>\r
- <entry><systemitem class="domainname">private.localhost</systemitem>\r
- password for\r
- <systemitem class="username">router</systemitem> user\r
- </entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <para>You may also need to modify the file to specify the domains from which \r
- <systemitem class="service">OpenSRF</systemitem> will accept connections,\r
- and to which it will make connections.\r
- If you are installing <application>OpenSRF</application> on a single server\r
- and using the <systemitem class="domainname">private.localhost</systemitem> and\r
- <systemitem class="domainname">public.localhost</systemitem> domains, \r
- these will already be set to the correct values. Otherwise, search and replace\r
- to match values for your own systems.</para>\r
- </step>\r
- <step>\r
- <title>Set the location of the persistent database</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
- file <filename>/openils/conf/opensrf.xml</filename>, then find and verify that\r
- the element <literal>dbfile</literal> (near the end of the file) is set to the \r
- location of the persistent database. If necessary, change the default line:</para>\r
- <literal>/openils/var/persist.db</literal>\r
- <para>to instead read:</para>\r
- <literal>/tmp/persist.db</literal>\r
- <para>Following is a sample modification of that portion of the file:</para>\r
- <programlisting language="xml"><![CDATA[\r
-<!-- Example of an app-specific setting override -->\r
-<opensrf.persist>\r
- <app_settings>\r
- <dbfile>/tmp/persist.db</dbfile>\r
- </app_settings>\r
-</opensrf.persist>\r
-]]></programlisting>\r
- </step>\r
- <step xml:id="serversideinstallation-srfsh">\r
- <title>Create configuration files for users needing <command>srfsh</command></title>\r
- <para>In this section you will set up a special configuration file for each user\r
- who will need to run the <command>srfsh</command> (pronounced <emphasis>surf\r
- shell</emphasis>) utility.</para>\r
- <indexterm>\r
- <primary>srfsh</primary>\r
- </indexterm>\r
- <para>The software installation will automatically create the utility\r
- <command>srfsh</command>, a command line diagnostic tool for testing and\r
- interacting with <application>OpenSRF</application>. It will be used\r
- in a future step to complete and test the Evergreen installation. See \r
- <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, copy the\r
- sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>\r
- to the home directory of each user who will use <command>srfsh</command>. \r
- For instance, do the following for the \r
- <systemitem class="username">opensrf</systemitem> user:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>\r
-</screen>\r
- <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the\r
- following changes:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Modify <literal>domain</literal> to be the router hostname\r
- (following our domain examples,\r
- <systemitem class="domainname">private.localhost</systemitem> will give\r
- <command>srfsh</command> access to all OpenSRF services, while\r
- <systemitem class="domainname">public.localhost</systemitem>\r
- will only allow access to those OpenSRF services that are\r
- publicly exposed).</para>\r
- </listitem>\r
- <listitem>\r
- <para>Modify <literal>username</literal> and\r
- <literal>password</literal> to match the\r
- <literal>opensrf</literal> Jabber user for the chosen\r
- domain</para>\r
- </listitem>\r
- <listitem>\r
- <para>Modify <literal>logfile</literal> to be the full path for\r
- a log file to which the user has write access</para>\r
- </listitem>\r
- <listitem>\r
- <para>Modify <literal>loglevel</literal> as needed for testing</para>\r
- </listitem>\r
- <listitem>\r
- <para>Change the owner of the file to match the owner of the home directory</para>\r
- </listitem>\r
- </itemizedlist>\r
- <para>Following is a sample of the file:</para>\r
- <programlisting language="xml"><![CDATA[\r
-<?xml version="1.0"?>\r
-<!-- This file follows the standard bootstrap config file layout -->\r
-<!-- found in opensrf_core.xml -->\r
-<srfsh>\r
-<router_name>router</router_name>\r
-<domain>private.localhost</domain>\r
-<username>opensrf</username>\r
-<passwd>SOMEPASSWORD</passwd>\r
-<port>5222</port>\r
-<logfile>/tmp/srfsh.log</logfile>\r
-<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->\r
-<loglevel>4</loglevel>\r
-</srfsh>\r
-]]></programlisting>\r
- </step>\r
- <step>\r
- <title>Modify the environmental variable <envar>PATH</envar> for the\r
- <systemitem class="username">opensrf</systemitem> user</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, modify the\r
- environmental variable <envar>PATH</envar> by adding a new file path to the\r
- <systemitem class="username">opensrf</systemitem> user's shell configuration\r
- file <filename>~/.bashrc</filename>:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Start OpenSRF</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, start the\r
- <systemitem class="service">ejabberd</systemitem> and \r
- <systemitem class="service">memcached</systemitem> services:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /etc/init.d/ejabberd start\r
- /etc/init.d/memcached start</userinput>\r
-</screen>\r
- <para>Then as the <systemitem class="username">opensrf</systemitem> user,\r
- start OpenSRF as follows:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- osrf_ctl.sh -l -a start_all</userinput>\r
-</screen>\r
- <para>The flag <option>-l</option> forces Evergreen to use \r
- <systemitem class="domainname">localhost</systemitem> (your current system) \r
- as the hostname. The flag <option>-a start_all</option> starts the\r
- OpenSRF <systemitem class="service">router</systemitem> , \r
- <systemitem class="service">Perl</systemitem> , and\r
- <systemitem class="service">C</systemitem> services.</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>You can also start Evergreen without the\r
- <option>-l</option> flag, but the <command>osrf_ctl.sh</command>\r
- utility must know the fully qualified domain name for the system\r
- on which it will execute. That hostname was probably specified\r
- in the configuration file <filename>opensrf.xml</filename> which\r
- you configured in a previous step.</para>\r
- </listitem>\r
- <listitem>\r
- <para>If you receive an error message similar to\r
- <emphasis>osrf_ctl.sh: command not found</emphasis>, then your\r
- environment variable <envar>PATH</envar> does not include the\r
- directory <filename class="directory">/openils/bin</filename>.\r
- As the <systemitem class="username">opensrf</systemitem> user,\r
- edit the configuration file <filename>~/.bashrc</filename> and\r
- add the following line: \r
- <literal>export PATH=$PATH:/openils/bin</literal></para>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step>\r
- <title>Test connections to OpenSRF</title>\r
- <para>Once you have installed and started OpenSRF, as the \r
- <systemitem class="username">root</systemitem> user test your connection to \r
- <systemitem class="service">OpenSRF</systemitem> with the <command>srfsh</command> \r
- utility and try to call the <command>add</command> method on the OpenSRF \r
- <systemitem class="service">math</systemitem> service:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /openils/bin/srfsh</userinput>\r
- <computeroutput>\r
- srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>\r
- <computeroutput>\r
- Received Data: 4\r
- ------------------------------------\r
- Request Completed Successfully\r
- Request Time in seconds: 0.007519\r
- ------------------------------------</computeroutput>\r
-</screen>\r
- <para>For other <command>srfsh</command> commands, type in\r
- <userinput>help</userinput> at the prompt.</para>\r
- </step>\r
- <step>\r
- <title>Stop OpenSRF</title>\r
- <para>After OpenSRF has started, you can stop it at any time by using the\r
- <command>osrf_ctl.sh</command> again. As the \r
- <systemitem class="username">opensrf</systemitem> \r
- user, stop OpenSRF as follows:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- osrf_ctl.sh -l -a stop_all</userinput>\r
-</screen>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="serversideinstallation-ubuntudebian">\r
- <title>Installing Evergreen 2.0 On <systemitem class="osname">Ubuntu</systemitem> or\r
- <systemitem class="osname">Debian</systemitem></title>\r
- <indexterm>\r
- <primary>Linux</primary>\r
- <secondary>Debian</secondary>\r
- </indexterm>\r
- <indexterm>\r
- <primary>Linux</primary>\r
- <secondary>Ubuntu</secondary>\r
- </indexterm>\r
- <para>This section outlines the installation process for the latest stable version of\r
- Evergreen.</para>\r
- <para>In this section you will download, unpack, install, configure and test the Evergreen\r
- system, including the Evergreen server and the PostgreSQL database system. You will make several\r
- configuration changes and adjustments to the software, including updates to configure the system\r
- for your own locale, and some updates needed to work around a few known issues.</para>\r
- <note>\r
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)\r
- architectures. There may be differences between the Desktop and Server editions of\r
- <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server\r
- edition.</para>\r
- <para>In the following instructions, you are asked to perform certain steps as \r
- either the <systemitem class="username">root</systemitem> user, the \r
- <systemitem class="username">opensrf</systemitem> user, or the \r
- <systemitem class="username">postgres</systemitem> user.</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para><systemitem class="osname">Debian</systemitem> -- To become the\r
- <systemitem class="username">root</systemitem> user, issue the command\r
- <command>su -</command> and enter the password of the \r
- <systemitem class="username">root</systemitem> user.</para>\r
- </listitem>\r
- <listitem>\r
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
- <systemitem class="username">root</systemitem> user, issue the command\r
- <command>sudo su -</command> and enter the password of the \r
- <systemitem class="username">root</systemitem> user.</para>\r
- </listitem>\r
- </itemizedlist>\r
- <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
- different user, issue the command <command>su - USERNAME</command>. For example, to\r
- switch from the <systemitem class="username">root</systemitem> user to the \r
- <systemitem class="username">opensrf</systemitem> user, issue the command \r
- <command>su - opensrf</command>. Once you have become a non-root user, to become the\r
- <systemitem class="username">root</systemitem> user again, simply issue the command\r
- <command>exit</command>.</para>\r
- </note>\r
- <procedure>\r
- <step>\r
- <title>Install OpenSRF</title>\r
- <para>Evergreen software is integrated with and depends on the Open Service\r
- Request Framework (OpenSRF) software system. For further information on\r
- installing, configuring and testing OpenSRF, see \r
- <xref linkend="serversideinstallation-opensrf"/>.</para>\r
- <para>Follow the steps outlined in that section and run the specified tests to\r
- ensure that OpenSRF is properly installed and configured. Do \r
- <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with\r
- any further Evergreen installation steps until you have verified that OpenSRF\r
- has been successfully installed and tested.</para>\r
- </step>\r
- <step>\r
- <title>Download and Unpack Latest Evergreen Version</title>\r
- <para>The latest version of Evergreen can be found here:\r
- <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .\r
- As the <systemitem class="username">opensrf</systemitem> user, change to\r
- the directory <filename class="directory">/home/opensrf</filename> then download\r
- and extract Evergreen. The new subdirectory\r
- <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename> will be created:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /home/opensrf\r
- wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz\r
- tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-installprereq">\r
- <title>Install Prerequisites to Build Evergreen</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be\r
- used later in <xref linkend="serversideinstallation-configure"/> and \r
- <xref linkend="serversideinstallation-compile"/> to build the Evergreen software \r
- using the <command>make</command> utility.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
- below to build the prerequisites from the software distribution that you just downloaded\r
- and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
- example with the keyword corresponding to the name of one of the \r
- <systemitem class="osname">Linux</systemitem> distributions listed in the following\r
- distribution list.\r
- For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would\r
- enter this command: <command>make -f Open-ILS/src/extras/Makefile.install\r
- ubuntu-lucid</command>.</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /home/opensrf/Evergreen-ILS-2.0.4\r
- make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
- <itemizedlist>\r
- \r
- <listitem>\r
- <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>\r
- </listitem>\r
- \r
- <listitem>\r
- <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx \r
- (10.04)</systemitem></para>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step performance="optional" xml:id="serversideinstallation-postgresql-default">\r
- <title>(OPTIONAL) Install the PostgreSQL Server</title>\r
- <indexterm>\r
- <primary>databases</primary>\r
- <secondary>PostgreSQL</secondary>\r
- </indexterm>\r
- <para>Since the PostgreSQL server is usually a standalone server in multi-server\r
- production systems, the prerequisite installer Makefile in the previous section\r
- (see <xref linkend="serversideinstallation-installprereq"/>)\r
- does not automatically install PostgreSQL. You must install the PostgreSQL server\r
- yourself, either on the same system as Evergreen itself or on another system.\r
- If your PostgreSQL server is on a different system, just skip this step.\r
- If your PostgreSQL server will be on the same system as your Evergreen\r
- software, you can install the required PostgreSQL server packages as described\r
- in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official \r
- web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>\r
- for more information.</para>\r
- <note>\r
- <para>PostgreSQL version 8.4 is the minimum supported version to work \r
- with Evergreen 2.0. If you have an older version of PostgreSQL, \r
- you should upgrade before installing Evergreen. To find your current version \r
- of PostgreSQL, as the <systemitem class="username">postgres</systemitem> \r
- user execute the command <command>psql</command>, then type \r
- <userinput>SELECT version();</userinput> to get detailed information \r
- about your version of PostgreSQL.</para>\r
- </note>\r
- </step>\r
- <step performance="optional">\r
- <title>Install Perl Modules on PostgreSQL Server</title>\r
- <para>If PostgreSQL is running on the same system as your Evergreen software,\r
- then the Perl modules will automatically be available. Just skip this step.\r
- Otherwise, continue if your PostgreSQL server is running on another system.</para>\r
- <para>You will need to install several Perl modules on the other system. As the\r
- <systemitem class="username">root</systemitem> user install the following Perl\r
- modules:</para>\r
- <para>as the root user, ensure the gcc compiler is installed:</para>\r
-<screen>\r
- <userinput>aptitude install gcc libxml-libxml-perl libxml-libxslt-perl</userinput>\r
-</screen>\r
- <para>then install the Perl modules:</para>\r
-<screen>\r
- <userinput>perl -MCPAN -e shell</userinput>\r
- <prompt>cpan></prompt> <userinput>Business::ISBN</userinput> \r
- <prompt>cpan></prompt> <userinput>install JSON::XS</userinput>\r
- <prompt>cpan></prompt> <userinput>Library::CallNumber::LC</userinput>\r
- <prompt>cpan></prompt> <userinput>install MARC::Record</userinput>\r
- <prompt>cpan></prompt> <userinput>install MARC::File::XML</userinput>\r
- <prompt>cpan></prompt> <userinput>cpan UUID::Tiny</userinput>\r
-</screen>\r
- <para>For more information on installing Perl Modules vist the official\r
- <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>\r
- <indexterm>\r
- <primary>Perl</primary>\r
- <secondary>CPAN</secondary>\r
- </indexterm>\r
- </step>\r
- <step>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>You must update the system dynamic library path to force your system to recognize\r
- the newly installed libraries. As the <systemitem class="username">root</systemitem> user,\r
- do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>\r
- containing a new library path, then run the command <command>ldconfig</command> to\r
- automatically read the file and modify the system dynamic library path:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf\r
- echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf\r
- ldconfig</userinput>\r
-</screen>\r
- </step>\r
- <step performance="optional">\r
- <title>Restart the PostgreSQL Server</title>\r
- <para>If PostgreSQL is running on the same system as the rest of Evergreen, as\r
- the <systemitem class="username">root</systemitem> user you must restart\r
- PostgreSQL to re-read the new library paths just configured. If PostgreSQL is\r
- running on another system, you may skip this step.\r
- As the <systemitem class="username">opensrf</systemitem> user,\r
- execute the following command (remember to replace\r
- <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,\r
- for example <literal>8.4</literal>):</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-configure">\r
- <title>Configure Evergreen</title>\r
- <para>In this step you will use the <command>configure</command> and\r
- <command>make</command> utilities to configure Evergreen so it can be compiled\r
- and linked later in <xref linkend="serversideinstallation-compile"/>.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to\r
- the Evergreen build directory and execute these commands:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /home/opensrf/Evergreen-ILS-2.0.4\r
- ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- make</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-compile">\r
- <title>Compile, Link and Install Evergreen</title>\r
- <para>In this step you will actually compile, link and install Evergreen and the \r
- default Evergreen Staff Client.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, return to the\r
- Evergreen build directory and use the <command>make</command> utility as shown below:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /home/opensrf/Evergreen-ILS-2.0.4\r
- make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>\r
-</screen>\r
- <para>The Staff Client will also be automatically built, but you must remember\r
- to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the \r
- Staff Client you will use to connect to the Evergreen server.</para>\r
- <para>The above commands will create a new subdirectory\r
- <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename> \r
- containing the Staff Client.</para>\r
- <para>To complete the Staff Client installation, as the\r
- <systemitem class="username">root</systemitem> user execute the following commands to\r
- create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client\r
- directory <filename class="directory">/openils/var/web/xul</filename> that points to the\r
- subdirectory <filename class="directory">/server</filename> of the new Staff Client\r
- build:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /openils/var/web/xul\r
- ln -sf rel_2_0_4/server server</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Copy the OpenSRF Configuration Files</title>\r
- <para>In this step you will replace some OpenSRF configuration files that you set up in\r
- <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and\r
- tested OpenSRF.</para>\r
- <para>You must copy several example OpenSRF configuration files into place after first\r
- creating backup copies for troubleshooting purposes, then change all the file ownerships\r
- to <systemitem class="username">opensrf</systemitem>.\r
- As the <systemitem class="username">root</systemitem> user, execute the following\r
- commands:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /openils/conf\r
- cp opensrf.xml opensrf.xml.BAK\r
- cp opensrf_core.xml opensrf_core.xml.BAK\r
- cp opensrf.xml.example opensrf.xml\r
- cp opensrf_core.xml.example opensrf_core.xml\r
- cp oils_web.xml.example oils_web.xml\r
- chown -R opensrf:opensrf /openils/</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Create and Configure PostgreSQL Database</title>\r
- <indexterm>\r
- <primary>databases</primary>\r
- <secondary>PostgreSQL</secondary>\r
- </indexterm>\r
- <para>In this step you will create the Evergreen database. In the commands\r
- below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>\r
- repository to match your PostgreSQL server\r
- layout. For example, if you built PostgreSQL from source the path would be\r
- <filename class="directory">/usr/local/share/contrib</filename> , and if you\r
- installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,\r
- the path would be \r
- <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>\r
- <substeps>\r
- <step>\r
- <para>\r
- <emphasis role="bold">Create and configure the database</emphasis>\r
- </para>\r
- <para>As the <systemitem class="username">postgres</systemitem>\r
- user on the PostgreSQL system create the PostgreSQL database,\r
- then set some internal paths:</para>\r
-<screen>\r
- <userinput>\r
- # as the postgres user:\r
- createdb evergreen -E UTF8 -T template0\r
- createlang plperl evergreen\r
- createlang plperlu evergreen\r
- createlang plpgsql evergreen</userinput>\r
-</screen>\r
- <para>Continue as the <systemitem class="username">postgres</systemitem> user\r
- and execute the SQL scripts as shown below (remember to adjust the paths as needed,\r
- where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL\r
- version, for example <literal>8.4</literal>).</para>\r
-<screen>\r
- <userinput>\r
- # as the postgres user:\r
- psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen\r
- psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen\r
- psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-postgresqlcreateuser">\r
- <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>\r
- <para>As the <systemitem class="username">postgres</systemitem>\r
- user on the PostgreSQL system, create a new PostgreSQL user\r
- named <systemitem class="username">evergreen</systemitem> and\r
- assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>\r
- with an appropriate new password):</para>\r
-<screen>\r
- <userinput>\r
- # as the postgres user:\r
- createuser -P -s evergreen</userinput>\r
- <computeroutput>\r
- Enter password for new role: <userinput>NEWPASSWORD</userinput>\r
- Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>\r
-</screen>\r
- </step>\r
- <step>\r
- <title>Create database schema</title>\r
- <para>In this step you will create the database schema and configure your\r
- system with the corresponding database authentication details for the\r
- <emphasis>evergreen</emphasis> database user that you just created in\r
- <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, enter\r
- the following commands and replace <emphasis>HOSTNAME, PORT,\r
- PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate\r
- values:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-2.0.4\r
-perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
---service all --create-schema --create-offline \\r
---hostname HOSTNAME --port PORT \\r
---user evergreen --password PASSWORD \\r
---database DATABASENAME --admin-user ADMIN-USER \ \r
---admin-pass ADMIN-PASSWORD </userinput>\r
-</screen>\r
- <para>On most systems, <emphasis>HOSTNAME</emphasis> will be\r
- <emphasis role="bold">localhost</emphasis> and\r
- <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.\r
- Of course, values for <emphasis>PASSWORD</emphasis> and\r
- <emphasis>DATABASENAME</emphasis> must match the values you used in \r
- <xref linkend="serversideinstallation-postgresqlcreateuser"/>. The <option>admin-user</option> and <option>admin-pass</option> options will \r
- specify the Evergreen administrator account's username and password. This was \r
- changed for security reasons, it was previously admin/open-ils</para>\r
- <para>As the command executes, you may see warnings similar to:\r
- <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,\r
- you may see one warning per schema) but they can be safely ignored.</para>\r
- <note>If you are entering the above command on a single line, do not\r
- include the <literal>\</literal> (backslash) characters. If you are using\r
- the <command>bash</command> shell, these should only be used at the end of\r
- a line at a <command>bash</command> prompt to indicate that the command is\r
- continued on the next line.</note>\r
- </step>\r
- </substeps>\r
- </step>\r
- <step>\r
- <title>Configure the Apache web server</title>\r
- <indexterm>\r
- <primary>web server</primary>\r
- <secondary>Apache</secondary>\r
- </indexterm>\r
- <para>In this step you will configure the Apache web server to support Evergreen\r
- software.</para>\r
- <para>First, you must enable some built-in Apache modules and install some\r
- additional Apache configuration files. Then you will create a new Security\r
- Certificate. Finally, you must make several changes to the Apache configuration\r
- file.</para>\r
- <substeps>\r
- <step>\r
- <title>Enable the required Apache Modules</title>\r
- <para>As the <systemitem class="username">root</systemitem>\r
- user, enable some modules in the Apache server, then copy the\r
- new configuration files to the Apache server directories:</para>\r
- <indexterm>\r
- <primary>Apache modules</primary>\r
- </indexterm>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- a2enmod ssl # enable mod_ssl\r
- a2enmod rewrite # enable mod_rewrite\r
- a2enmod expires # enable mod_expires</userinput>\r
-</screen>\r
- <para>As the commands execute, you may see warnings similar to:\r
- <literal>Module SOMEMODULE already enabled</literal> but you can\r
- safely ignore them.</para>\r
- </step>\r
- <step>\r
- <title>Copy Apache configuration files</title>\r
- <para>You must copy the Apache configuration files from the\r
- Evergreen installation directory to the Apache directory. As the\r
- <systemitem class="username">root</systemitem> user, perform the\r
- following commands:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- cd /home/opensrf/Evergreen-ILS-2.0.4\r
- cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/\r
- cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/\r
- cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>\r
-</screen>\r
- </step>\r
- <step xml:id="serversideinstallation-createsslcertificate">\r
- <title>Create a Security Certificate</title>\r
- <para>In this step you will create a new Security Certificate (SSL Key)\r
- for the Apache server using the <command>openssl</command> command. For a\r
- public production server you must configure or purchase a signed SSL\r
- certificate, but for now you can just use a self-signed certificate and\r
- accept the warnings in the Staff Client and browser during testing and\r
- development. As the <systemitem class="username">root</systemitem> user,\r
- perform the following commands:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- mkdir /etc/apache2/ssl\r
- cd /etc/apache2/ssl\r
- openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>\r
-</screen>\r
- <para>You will be prompted for several items of information; enter\r
- the appropriate information for each item. The new files\r
- <filename>server.crt</filename> and <filename>server.key</filename> will\r
- be created in the directory \r
- <filename class="directory">/etc/apache2/ssl</filename> .</para>\r
- <note>This step generates a self-signed SSL certificate. You must install\r
- a proper SSL certificate for a public production system to avoid warning\r
- messages when users login to their account through the OPAC or when staff\r
- login through the Staff Client. For further information on\r
- installing a proper SSL certificate, see \r
- <xref linkend="serversideinstallation-ssl"/>.</note>\r
- </step>\r
- <step xml:id="serversideinstallation-modify-apache">\r
- <title>Update Apache configuration file</title>\r
- <para>You must make several changes to the new Apache\r
- configuration file\r
- <filename>/etc/apache2/sites-available/eg.conf</filename> . \r
- As the <systemitem class="username">root</systemitem> user,\r
- edit the file and make the following changes:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>In the section\r
- <literal><Directory "/openils/var/cgi-bin"></literal>\r
- replace the line:</para>\r
- <literal>Allow from 10.0.0.0/8</literal>\r
- <para>with the line:</para>\r
- <literal>Allow from all</literal>\r
- <warning>This change allows access to your configuration\r
- CGI scripts from any workstation on any network. This is\r
- only a temporary change to expedite testing and should be\r
- removed after you have finished and successfully tested\r
- the Evergreen installation. See \r
- <xref linkend="serversideinstallation-postinstallation"/> \r
- for further details on removing this change after the\r
- Evergreen installation is complete.\r
- </warning>\r
- </listitem>\r
- <listitem>\r
- <para>Comment out the line:</para>\r
- <literal>Listen 443</literal>\r
- <para>since it conflicts with the same declaration in \r
- the configuration file:</para>\r
- <para><filename>/etc/apache2/ports.conf</filename>.</para>\r
- </listitem>\r
- <listitem>\r
- <para>The following updates are needed to allow the logs\r
- to function properly, but it may break other Apache\r
- applications on your server:</para>\r
- \r
- <para>Edit the Apache configuration file and change the lines:</para>\r
-<screen>\r
-<userinput>export APACHE_RUN_USER=www-data</userinput>\r
-<userinput>export APACHE_RUN_GROUP=www-data</userinput>\r
-</screen>\r
- <para>to instead read:</para>\r
-<screen>\r
- <userinput>\r
- export APACHE_RUN_USER=opensrf\r
- export APACHE_RUN_GROUP=opensrf</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>As the \r
- <systemitem class="username">root</systemitem> user,\r
- edit the Apache configuration file\r
- <filename>/etc/apache2/apache2.conf</filename> and\r
- modify the value for <literal>KeepAliveTimeout</literal>\r
- and <literal>MaxKeepAliveRequests</literal> to match\r
- the following:</para>\r
-<screen>\r
- <userinput>\r
- KeepAliveTimeout 1\r
- MaxKeepAliveRequests 100</userinput>\r
-</screen>\r
- </listitem>\r
- <listitem>\r
- <para>Further configuration changes to Apache may be\r
- necessary for busy systems. These changes increase the\r
- number of Apache server processes that are started to\r
- support additional browser connections.</para>\r
- <para>As the \r
- <systemitem class="username">root</systemitem> user, \r
- edit the Apache configuration file\r
- <filename>/etc/apache2/apache2.conf</filename>, locate \r
- and modify the section related to <emphasis>prefork\r
- configuration</emphasis> to suit the load on your\r
- system:</para>\r
- <programlisting language="xml"><![CDATA[\r
-<IfModule mpm_prefork_module>\r
- StartServers 20\r
- MinSpareServers 5\r
- MaxSpareServers 15\r
- MaxClients 150\r
- MaxRequestsPerChild 10000\r
-</IfModule>\r
-]]></programlisting>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step>\r
- <title>Enable the Evergreen web site</title>\r
- <para>Finally, you must enable the Evergreen web site. As the\r
- <systemitem class="username">root</systemitem> user, execute the\r
- following Apache configuration commands to disable the default\r
- <emphasis>It Works</emphasis> web page and enable the Evergreen\r
- web site, and then restart the Apache server:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- # disable/enable web sites\r
- a2dissite default\r
- a2ensite eg.conf\r
- # restart the server\r
- /etc/init.d/apache2 reload</userinput>\r
-</screen>\r
- </step>\r
- </substeps>\r
- </step>\r
- <step xml:id="serversideinstallation-opensrf-config">\r
- <title>Update the OpenSRF Configuration File</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
- OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>\r
- to update the Jabber usernames and passwords, and to specify the domain from\r
- which we will accept and to which we will make connections.</para>\r
- <para>If you are installing Evergreen on a single server and using the\r
- <systemitem class="domainname">private.localhost</systemitem> / \r
- <systemitem class="domainname">public.localhost</systemitem> domains, \r
- these will already be set to the correct values. Otherwise, search and replace\r
- to match your customized values.</para>\r
- <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>\r
- shows common XPath syntax to indicate the approximate position within the XML\r
- file that needs changes. The right-hand side of the table shows the replacement\r
- values:</para>\r
- <table xml:id="serversideinstallation-xpath-table-2">\r
- <?dbfo keep-together="always" ?>\r
- <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>\r
- <colspec colname="Value" colnum="2" colwidth="2.0*"/>\r
- <thead>\r
- <row>\r
- <entry>XPath location</entry>\r
- <entry>Value</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>/config/opensrf/username</entry>\r
- <entry>\r
- <systemitem class="username">opensrf</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/opensrf/passwd </entry>\r
- <entry><systemitem class="domainname">private.localhost</systemitem>\r
- password for\r
- <systemitem class="username">opensrf</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/gateway/username</entry>\r
- <entry>\r
- <systemitem class="username">opensrf</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/gateway/passwd</entry>\r
- <entry><systemitem class="domainname">public.localhost</systemitem>\r
- password for\r
- <systemitem class="username">opensrf</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/username,\r
- first entry where server == public.localhost</entry>\r
- <entry>\r
- <systemitem class="username">router</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/password,\r
- first entry where server == public.localhost</entry>\r
- <entry><systemitem class="domainname">public.localhost</systemitem>\r
- password for\r
- <systemitem class="username">router</systemitem> user\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/username,\r
- second entry where server == private.localhost</entry>\r
- <entry>\r
- <systemitem class="username">router</systemitem>\r
- </entry>\r
- </row>\r
- <row>\r
- <entry>/config/routers/router/transport/password,\r
- second entry where server == private.localhost</entry>\r
- <entry><systemitem class="domainname">private.localhost</systemitem>\r
- password for\r
- <systemitem class="username">router</systemitem> user\r
- </entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- </step>\r
- <step performance="optional">\r
- <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>\r
- <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the\r
- software installation automatically created a utility named <command>srfsh</command> (surf\r
- shell). This is a command line diagnostic tool for testing and interacting with\r
- OpenSRF. It will be used in a future step to complete and test the Evergreen installation.\r
- Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration \r
- file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.\r
- See <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
- </step>\r
- <step xml:id="serversideinstallation-opensrf-env">\r
- <title>Modify the OpenSRF Environment</title>\r
- <para>In this step you will make some minor modifications to the OpenSRF environment:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user,\r
- modify the shell configuration file <filename>~/.bashrc</filename> for\r
- user <systemitem class="username">opensrf</systemitem> by adding a Perl\r
- environmental variable, then execute the shell configuration file to load\r
- the new variables into your current environment.</para>\r
- <note>In a multi-server environment, you must add any\r
- modifications to <filename>~/.bashrc</filename> to the top of the file\r
- <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&\r
- return </literal>. This will allow headless (scripted) logins to load the\r
- correct environment.</note>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc\r
- . ~/.bashrc</userinput>\r
-</screen>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step performance="optional">\r
- <title>(OPTIONAL) Enable and Disable Language Localizations</title>\r
- <para>You can load translations such as Armenian (hy-AM), Canadian French\r
- (fr-CA), and others into the database to complete the translations available in\r
- the OPAC and Staff Client. For further information, see\r
- <xref linkend="languagesandlocalization"/>.</para>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="serversideinstallation-fedora">\r
- <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or\r
- <systemitem class="osname">Fedora 14</systemitem> </title>\r
- </section>\r
- <section xml:id="serversideinstallation-starting">\r
- <title>Starting Evergreen</title>\r
- <para>In this section you will learn how to start the Evergreen services. \r
- For completeness, instructions for stopping Evergreen can be found later in \r
- <xref linkend="serversideinstallation-stopping"/>.</para>\r
- <procedure>\r
- <step>\r
- <para>As the <systemitem class="username">root</systemitem>\r
- user, start the <systemitem class="service">ejabberd</systemitem> and \r
- <systemitem class="service">memcached</systemitem> services as follows:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /etc/init.d/ejabberd start\r
- /etc/init.d/memcached start</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user,\r
- start the OpenSRF router service as follows:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- osrf_ctl.sh -l -a start_all</userinput>\r
-</screen>\r
- <para>The flag <option>-l</option> forces Evergreen to use\r
- <systemitem class="domainname">localhost</systemitem> (your current system) \r
- as the hostname. The flag <option>-a start_all</option> starts the \r
- OpenSRF <systemitem class="service">router</systemitem> , \r
- <systemitem class="service">Perl</systemitem> , and\r
- <systemitem class="service">C</systemitem> services.</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>You can also start Evergreen without the\r
- <option>-l</option> flag, but the <command>osrf_ctl.sh</command>\r
- utility must know the fully qualified domain name for the system\r
- on which it will execute. That hostname was probably specified\r
- in the configuration file <filename>opensrf.xml</filename> which\r
- you configured in a previous step.</para>\r
- </listitem>\r
- <listitem>\r
- <para>If you receive an error message similar to\r
- <emphasis>osrf_ctl.sh: command not found</emphasis>, then your\r
- environment variable <envar>PATH</envar> does not include the\r
- directory <filename class="directory">/openils/bin</filename>.\r
- As the <systemitem class="username">opensrf</systemitem> user,\r
- edit the configuration file <filename>~/.bashrc</filename> and\r
- add the following line: \r
- <literal>export PATH=$PATH:/openils/bin</literal></para>\r
- </listitem>\r
- <listitem>\r
- <para>If you receive an error message similar to <emphasis>Can't\r
- locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation\r
- aborted</emphasis>, then your environment variable \r
- <emphasis role="bold">PERL5LIB</emphasis> does not include the \r
- directory <filename class="directory">/openils/lib/perl5</filename>.\r
- As the <systemitem class="username">opensrf</systemitem> user, \r
- edit the configuration file <filename>~/.bashrc</filename> and\r
- add the following line: \r
- <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>\r
- </listitem>\r
- </itemizedlist>\r
- </step>\r
- <step>\r
- <para>In this step you will generate the Web files needed by the Staff Client\r
- and catalog, and update the proximity of locations in the Organizational Unit\r
- tree (which allows <emphasis>Holds</emphasis> to work properly).</para>\r
- <para>You must do this the first time you start Evergreen and after making any\r
- changes to the library hierarchy.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, execute the\r
- following command and review the results:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /openils/bin\r
- ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
- <computeroutput>\r
- Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'\r
- Updating fieldmapper\r
- Updating web_fieldmapper\r
- Updating OrgTree\r
- removing OrgTree from the cache for locale hy-AM...\r
- removing OrgTree from the cache for locale cs-CZ...\r
- removing OrgTree from the cache for locale en-CA...\r
- removing OrgTree from the cache for locale en-US...\r
- removing OrgTree from the cache for locale fr-CA...\r
- removing OrgTree from the cache for locale ru-RU...\r
- Updating OrgTree HTML\r
- Updating locales selection HTML\r
- Updating Search Groups\r
- Refreshing proximity of org units\r
- Successfully updated the organization proximity\r
- Done</computeroutput>\r
-</screen>\r
- </step>\r
- <step>\r
- <para>As the <systemitem class="username">root</systemitem> user, restart the\r
- Apache Web server:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- /etc/init.d/apache2 restart</userinput>\r
-</screen>\r
- <note>If the Apache Web server was running when you started the OpenSRF\r
- services, you might not be able to successfully log into the OPAC or Staff\r
- Client until the Apache Web server has been restarted.</note>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="serversideinstallation-testing">\r
- <title>Testing Your Evergreen Installation</title>\r
- <para>This section describes several simple tests you can perform to verify that the Evergreen\r
- server-side software has been installed and configured properly and is running as\r
- expected.</para>\r
- <simplesect xml:id="serversideinstallation-testing-connections">\r
- <title>Testing Connections to Evergreen</title>\r
- <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the\r
- <command>srfsh</command> application and try logging onto the Evergreen server using the default\r
- administrator username and password. Following is sample output generated by executing\r
- <command>srfsh</command> after a successful Evergreen installation. For help with\r
- <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.\r
- As the <systemitem class="username">opensrf</systemitem> user,\r
- execute the following commands to test your Evergreen connection:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- /openils/bin/srfsh</userinput>\r
- <computeroutput>\r
- srfsh% <userinput>login admin open-ils</userinput>\r
- Received Data: "250bf1518c7527a03249858687714376"\r
- ------------------------------------\r
- Request Completed Successfully\r
- Request Time in seconds: 0.045286\r
- ------------------------------------\r
- Received Data: {\r
- "ilsevent":0,\r
- "textcode":"SUCCESS",\r
- "desc":" ",\r
- "pid":21616,\r
- "stacktrace":"oils_auth.c:304",\r
- "payload":{\r
- "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",\r
- "authtime":420\r
- }\r
- }\r
- ------------------------------------\r
- Request Completed Successfully\r
- Request Time in seconds: 1.336568\r
- ------------------------------------</computeroutput>\r
-</screen>\r
- <para>If this does not work, try the following:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the\r
- <filename>settings-tester.pl</filename> utility to review your Evergreen\r
- installation for any system configuration problems:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user:\r
- cd /home/opensrf\r
- ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl</userinput>\r
-</screen>\r
- <para>If the output of <command>settings-tester.pl</command> does not help you\r
- find the problem, please do not make any significant changes to your\r
- configuration.</para>\r
- </listitem>\r
- <listitem>\r
- <para>Follow the steps in the troubleshooting guide in \r
- <xref linkend="troubleshooting"/>.</para>\r
- </listitem>\r
- <listitem>\r
- <para>If you have followed the entire set of installation steps listed here\r
- closely, you are probably extremely close to a working system. Gather your\r
- configuration files and log files and contact the \r
- <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>\r
- list for assistance before making any drastic changes to your system\r
- configuration.</para>\r
- </listitem>\r
- </itemizedlist>\r
- </simplesect>\r
- <simplesect xml:id="serversideinstallation-running-staffclient">\r
- <title>Testing the Staff Client on Linux</title>\r
- <para>In this section you will confirm that a basic login on the Staff Client works\r
- properly.</para>\r
- <para>Run the Evergreen Staff Client on a Linux system by using the application\r
- <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox\r
- version 3.0 and later on Ubuntu and Debian distributions).</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client\r
- as shown:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini</userinput>\r
-</screen>\r
- <para>A login screen for the Staff Client similar to this should appear:</para>\r
- <mediaobject>\r
- <alt>Logging into the Staff Client</alt>\r
- <imageobject>\r
- <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- </mediaobject>\r
- <para>First, add the name of your Evergreen server to the field\r
- <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably\r
- want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test\r
- Server. You should now see the messages <literal>200:OK</literal> in the fields\r
- <literal>Status</literal> and <literal>Version</literal>.</para>\r
- <para>Because this is the initial run of the Staff Client, you will see a warning in the\r
- upper-right saying: <emphasis role="bold">Not yet configured for the specified\r
- server</emphasis>. To continue, you must assign a workstation name.</para>\r
- <para>Try to log into the Staff Client with the admin username and password you created during installation. If the login is successful, \r
- you will see the following screen:</para>\r
- <mediaobject>\r
- <alt>Logging into the Staff Client</alt>\r
- <imageobject>\r
- <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- </mediaobject>\r
- <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the\r
- main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>\r
- <mediaobject>\r
- <alt>Adding an SSL Exception in the Staff Client</alt>\r
- <imageobject>\r
- <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>\r
- </imageobject>\r
- </mediaobject>\r
- <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm\r
- Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the\r
- main window and try to log in again.</para>\r
- </simplesect>\r
- <simplesect xml:id="serversideinstallation-starting-apache-server">\r
- <title>Testing the Apache Web Server</title>\r
- <para>In this section you will test the Apache configuration file(s), then restart the\r
- Apache web server.</para>\r
- <para>As the <emphasis role="bold">root</emphasis> user, execute the following\r
- commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen\r
- modules to be reloaded even if the Apache server is already running. Any problems found\r
- with your configuration files should be displayed:</para>\r
-<screen>\r
- <userinput>\r
- # as the root user:\r
- apache2ctl configtest && /etc/init.d/apache2 restart</userinput>\r
-</screen>\r
- </simplesect>\r
- <simplesect xml:id="serversideinstallation-stopping">\r
- <title>Stopping Evergreen</title>\r
- <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the\r
- Evergreen services. For completeness, following are instructions for stopping the\r
- Evergreen services.</para>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen\r
- services by using the following command:</para>\r
-<screen>\r
- <userinput>\r
- # as the opensrf user\r
- # stop the server; use "-l" to force hostname to be "localhost"\r
- osrf_ctl.sh -l -a stop_all</userinput>\r
-</screen>\r
- <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the\r
- <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the\r
- fully qualified domain name for the system on which it will execute. That hostname may\r
- have been specified in the configuration file <filename>opensrf.xml</filename>, which\r
- you configured in a previous step.</note>\r
- </simplesect>\r
- </section>\r
- <section xml:id="serversideinstallation-postinstallation">\r
- <title>Post-Installation Chores</title>\r
- <para>There are several additional steps you may need to complete after Evergreen has been\r
- successfully installed and tested. Some steps may not be needed (e.g., setting up support for\r
- Reports).</para>\r
- <section>\r
- <title>Remove temporary Apache configuration changes</title>\r
- <para>You modified the Apache configuration file\r
- <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a\r
- temporary measure to expedite testing (see \r
- <xref linkend="serversideinstallation-modify-apache"/> for further information).\r
- Those changes must now be reversed in order to deny unwanted access to your \r
- CGI scripts from users on other public networks.</para>\r
- <warning>\r
- <para>\r
- <emphasis>This temporary network update was done to expedite\r
- testing. You <emphasis role="bold">must</emphasis> correct\r
- this for a public production system.</emphasis>\r
- </para>\r
- </warning>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the configuration\r
- file again and comment out the line <literal>Allow from all</literal> and uncomment the\r
- line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network\r
- address scheme.</para>\r
- </section>\r
- <section xml:id="serversideinstallation-ssl">\r
- <title>Configure a permanent SSL key</title>\r
- <para>You used the command <command>openssl</command> in an earlier step to\r
- temporarily create a new SSL key for the Apache server (see \r
- <xref linkend="serversideinstallation-createsslcertificate"/> for further\r
- information). This self-signed security certificate was adequate during\r
- testing and development, but will continue to generate warnings in the Staff\r
- Client and browser. For a public production server you should configure or\r
- purchase a signed SSL certificate.</para>\r
- <para>There are several open source software solutions that provide schemes to\r
- generate and maintain public key security certificates for your library\r
- system. Some popular projects are listed below; please review them for\r
- background information on why you need such a system and how you can provide\r
- it:</para>\r
- <itemizedlist>\r
- <listitem>\r
- <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>\r
- </listitem>\r
- <listitem>\r
- <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>\r
- </listitem>\r
- <listitem>\r
- <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>\r
- </listitem>\r
- </itemizedlist>\r
- <warning>\r
- <para>\r
- <emphasis>The temporary SSL key was only created to expedite\r
- testing. You should install a proper SSL certificate for a public\r
- production system.</emphasis>\r
- </para>\r
- </warning>\r
- </section>\r
- <section>\r
- <title>(OPTIONAL) IP-Redirection</title>\r
- <para>By default, Evergreen is configured so searching the OPAC always starts in the\r
- top-level (regional) library rather than in a second-level (branch) library. Instead,\r
- you can use "IP-Redirection" to change the default OPAC search location to use the IP\r
- address range assigned to the second-level library where the seach originates. You must\r
- configure these IP ranges by creating the configuration file\r
- <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script\r
- <filename>/etc/apache2/startup.pl</filename>.</para>\r
- <para>First, copy the sample file\r
- <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>\r
- to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single\r
- line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use\r
- the IP address ranges for your library system. Add new lines to represent the IP address\r
- range for each branch library. Replace the values for <literal>MY-LIB</literal> with the\r
- values for each branch library found in the table\r
- <literal>actor.org_unit</literal>.</para>\r
- <para>Finally, modify the Apache startup script\r
- <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then\r
- restarting the Apache server:</para>\r
- <programlisting language="xml"><![CDATA[\r
-# - Uncomment the following 2 lines to make use of the IP redirection code\r
-# - The IP file should contain a map with the following format:\r
-# - actor.org_unit.shortname <start_ip> <end_ip>\r
-# - e.g. LIB123 10.0.0.1 10.0.0.254\r
-use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);\r
-OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');\r
-]]></programlisting>\r
- </section>\r
- <section>\r
- <title>(OPTIONAL) Set Up Support For Reports</title>\r
- <para>Evergreen reports are extremely powerful but require some simple configuration.\r
- See <xref linkend="report_starting_reporter_service"/> for information on starting and\r
- stopping the Reporter daemon processes.</para>\r
- </section>\r
- </section>\r
- </section>\r
-</chapter>\r
+<?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-1.6.3">
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>installation</secondary>
+ </indexterm>
+ <title>Installing OpenSRF 1.6.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-1.6.3.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-1.6.3</filename> will be created:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz
+ tar zxf OpenSRF-1.6.3.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-1.6.3
+ 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-1.6.3
+ ./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-1.6.3
+ 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-1.6.3"/>.</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.4.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.4</filename>
+ will be created:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
+ tar zxf Evergreen-ILS-2.0.4.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.4
+ 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.4
+ ./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.4
+ make STAFF_CLIENT_BUILD_ID=rel_2_0_4 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_4</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_4/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.4
+ 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.4
+ 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><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" ] &&
+ 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-1.6.3"/>.</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.4.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.4</filename>
+ will be created:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
+ tar zxf Evergreen-ILS-2.0.4.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.4
+ 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.4
+ ./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.4
+ make STAFF_CLIENT_BUILD_ID=rel_2_0_4 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_4</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_4/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.4
+ 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.4
+ 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><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" ] &&
+ 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.4/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.4/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 && /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-1.6.1.2/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>
projects / Evergreen-DocBook.git / commitdiff