+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter version="5.0" xml:id="serversideinstallation" xml:lang="EN" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
- <info>
- <title>Server-side Installation of Evergreen Software</title>
- <abstract>
- <para>This section describes installation of the Evergreen server-side software and
- its associated components. Installation, configuration, testing and verification of
- the software is straightforward if you follow some simple directions.</para>
- </abstract>
- </info>
- <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
- stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
- installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
- system.</para>
- <para>The current version of the Evergreen server-side software runs as a native application on any of several
- well-known <systemitem class="osname">Linux</systemitem> distributions
- (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
- It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
- operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
- Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
- installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
- <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
- <application>"VirtualBox"</application> or <application>"VMware"</application>
- to emulate a <systemitem class="osname">Linux</systemitem>
- environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
- systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
- <application>"VMware"</application>). More information on virtualized environments can be found in
- <xref linkend="serversideinstallation-virtual"/>.</para>
- <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
- <para>The Evergreen server-side software has dependencies on particular versions of certain major software
- sub-components. Successful installation of Evergreen software requires that software versions agree with those
- listed here:</para>
- <table xml:id="serversideinstall-software-dependencies">
- <?dbfo keep-together="always" ?>
- <title>Evergreen Software Dependencies</title>
- <indexterm>
- <primary>Evergreen software dependencies</primary>
- </indexterm>
- <tgroup align="left" cols="3" colsep="1" rowsep="1">
- <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
- <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
- <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
- <thead>
- <row>
- <entry>Evergreen</entry>
- <entry>OpenSRF</entry>
- <entry>PostgreSQL</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>2.0</entry>
- <entry>1.6.3</entry>
- <entry>8.4</entry>
- </row>
- <row>
- <entry>1.6.1.x</entry>
- <entry>1.4.0</entry>
- <entry>8.2 / 8.3</entry>
- </row>
- <row>
- <entry>1.6.0.x</entry>
- <entry>1.2</entry>
- <entry>8.2 / 8.3</entry>
- </row>
- <row>
- <entry>1.4.x</entry>
- <entry>1.0</entry>
- <entry>8.1 / 8.2</entry>
- </row>
- <row>
- <entry>1.2.x</entry>
- <entry>0.9</entry>
- <entry>8.1 / 8.2</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <section xml:id="serversideinstallation-all">
- <title>Installing Server-Side Software</title>
- <para>This section describes the installation of the major components of Evergreen server-side software.</para>
- <para>As far as possible, you should perform the following steps in the exact order given since the
- success of many steps relies on the successful completion of earlier steps. You should make backup
- copies of files and environments when you are instructed to do so. In the event of installation problems
- those copies can allow you to back out of a step gracefully and resume the installation from a known
- state. See <xref linkend="backingup"/> for further information.</para>
- <para>Of course, after you successfully complete and test the entire Evergreen installation you should
- take a final snapshot backup of your system(s). This can be the first in the series of regularly
- scheduled system backups that you should probably also begin.</para>
- <section xml:id="serversideinstallation-opensrf-2.0.1">
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>installation</secondary>
- </indexterm>
- <title>Installing OpenSRF 2.0.x On <systemitem class="osname">Ubuntu</systemitem> or
- <systemitem class="osname">Debian</systemitem></title>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Debian</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Ubuntu</secondary>
- </indexterm>
- <para>This section describes the installation of the latest version of the Open Service Request
- Framework (OpenSRF), a major component of the Evergreen server-side software, on
- <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
- systems. Evergreen software is integrated with and depends on the OpenSRF software
- system.</para>
- <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
- properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
- continue with any further Evergreen installation steps
- until you have verified that OpenSRF has been successfully installed and tested.</para>
- <note>
- <para>The following steps have been tested on the x86 (32-bit) architecture of
- <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
- <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
- <systemitem class="osname">Fedora 13</systemitem> and
- <systemitem class="osname">Fedora 14</systemitem>.</para>
- <para>In the following instructions, you are asked to perform certain steps as
- either the <systemitem class="username">root</systemitem> user, the
- <systemitem class="username">opensrf</systemitem> user, or the
- <systemitem class="username">postgres</systemitem> user.</para>
- <itemizedlist>
- <listitem>
- <para><systemitem class="osname">Debian</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- <listitem>
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>sudo su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- </itemizedlist>
- <para>To switch from the <systemitem class="username">root</systemitem> user to a
- different user, issue the command <command>su - USERNAME</command>. For example, to
- switch from the <systemitem class="username">root</systemitem> user to the
- <systemitem class="username">opensrf</systemitem> user, issue the command
- <command>su - opensrf</command>. Once you have become a non-root user, to become
- the <systemitem class="username">root</systemitem> user again, simply issue the command
- <command>exit</command>.</para>
- </note>
- <procedure>
- <step>
- <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
- <para>As the <systemitem class="username">root</systemitem> user, add the
- <systemitem class="username">opensrf</systemitem> user to the system.
- In the following example, the default shell for the
- <systemitem class="username">opensrf</systemitem> user is automatically set
- to <command>/bin/bash</command> to inherit a reasonable environment:</para>
- <screen>
- <userinput>
- # as the root user:
- useradd -m -s /bin/bash opensrf
- passwd opensrf</userinput>
- </screen>
- </step>
- <step>
- <title>Download and Unpack Latest OpenSRF Version</title>
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>download</secondary>
- </indexterm>
- <para>The latest version of OpenSRF can be found here:
- <ulink url="http://evergreen-ils.org/downloads/opensrf-2.0.1.tar.gz"></ulink> .
- As the <systemitem class="username">opensrf</systemitem> user, change to
- the directory <filename class="directory">/home/opensrf</filename> then download
- and extract OpenSRF. The new subdirectory
- <filename class="directory">/home/opensrf/opensrf-2.0.1</filename> will be created:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- cd /home/opensrf
- wget http://evergreen-ils.org/downloads/opensrf-2.0.1.tar.gz
- tar zxf opensrf-2.0.1.tar.gz</userinput>
- </screen>
- </step>
- <step>
- <title>Install Prerequisites to Build OpenSRF</title>
- <para>In this section you will install and configure a set of prerequisites that will be
- used to build OpenSRF. In a following step you will actually build the OpenSRF software
- using the <command>make</command> utility.</para>
- <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
- below to build the prerequisites from the software distribution that you just downloaded
- and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
- example with the keyword corresponding to the name of one of the
- <systemitem class="osname">Linux</systemitem> distributions listed in the
- distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
- For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
- enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
- <screen>
- <userinput>
- # as the root user:
- cd /home/opensrf/opensrf-2.0.1
- make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
- </screen>
- <table xml:id="serversideinstallation-keywords-opensrf">
- <?dbfo keep-together="always" ?>
- <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
- <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
- <thead>
- <row>
- <entry>Keyword</entry>
- <entry>Linux Version</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>debian-squeeze</entry>
- <entry>Debian "Squeeze" (6.0)</entry>
- </row>
- <row>
- <entry>debian-etch</entry>
- <entry>Debian "Etch" (4.0)</entry>
- </row>
- <row>
- <entry>debian-lenny</entry>
- <entry>Debian "Lenny" (5.0)</entry>
- </row>
- <row>
- <entry>ubuntu-hardy</entry>
- <entry>Ubuntu "Hardy Heron" (8.04)</entry>
- </row>
- <row>
- <entry>ubuntu-karmic</entry>
- <entry>Ubuntu "Karmic Koala" (9.10)</entry>
- </row>
- <row>
- <entry>ubuntu-lucid</entry>
- <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
- </row>
- <row>
- <entry>fedora13</entry>
- <entry>Fedora "Goddard" (13)</entry>
- </row>
- <row>
- <entry>fedora13</entry>
- <entry>Fedora "Laughlin" (14)</entry>
- </row>
- <row>
- <entry>centos</entry>
- <entry>CentOS 5</entry>
- </row>
- <row>
- <entry>rhel</entry>
- <entry>Red Hat Enterprise Linux 5</entry>
- </row>
- <row>
- <entry>gentoo</entry>
- <entry>Gentoo</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Debian</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Fedora</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Ubuntu</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>CentOS</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Red Hat</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Gentoo</secondary>
- </indexterm>
- <para>This will install a number of packages on the system that are required by OpenSRF,
- including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
- CPAN configuration prompt to allow it to automatically configure itself to download and
- install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
- it should install prerequisite modules - say <literal>Yes</literal>.</para>
- </step>
- <step>
- <title>Build OpenSRF</title>
- <para>In this section you will configure, build and install the OpenSRF
- components that support other Evergreen services.</para>
- <substeps>
- <step>
- <title>Configure OpenSRF</title>
- <indexterm>
- <primary>OpenSRF</primary>
- <secondary>configure</secondary>
- </indexterm>
- <para>As the <systemitem class="username">opensrf</systemitem>
- user, return to the new OpenSRF build directory and use the
- <command>configure</command> utility to prepare for the next
- step of compiling and linking the software. If you wish to
- include support for Python and Java, add the configuration
- options <option>--enable-python</option> and
- <option>--enable-java</option>, respectively:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- cd /home/opensrf/opensrf-2.0.1
- ./configure --prefix=/openils --sysconfdir=/openils/conf
- make</userinput>
- </screen>
- <para>This step will take several minutes to complete.</para>
- </step>
- <step>
- <title>Compile, Link and Install OpenSRF</title>
- <para>As the <systemitem class="username">root</systemitem>
- user, return to the new OpenSRF build directory and use the
- <command>make</command> utility to compile, link and install
- OpenSRF:</para>
- <screen>
- <userinput>
- # as the root user:
- cd /home/opensrf/opensrf-2.0.1
- make install</userinput>
- </screen>
- <para>This step will take several minutes to complete.</para>
- </step>
- <step>
- <title>Update the System Dynamic Library Path</title>
- <para>You must update the system dynamic library path to force
- your system to recognize the newly installed libraries. As the
- <systemitem class="username">root</systemitem> user, do this by
- creating the new file
- <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing two
- new library paths, then execute the command
- <command>ldconfig</command> to automatically read the file and
- modify the system dynamic library path:</para>
- <screen>
- <userinput>
- # as the root user:
- echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
- echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
- ldconfig</userinput>
- </screen>
- </step>
- <step xml:id="serversideinstallation-definedomains">
- <title>Define Public and Private OpenSRF Domains</title>
- <para>For security purposes, OpenSRF uses Jabber domains to separate services
- into public and private realms. On a single-server system the easiest way to
- define public and private OpenSRF domains is to define separate host names by
- adding entries to the file <filename>/etc/hosts</filename>.</para>
- <para>In the following steps we will use the example domains
- <systemitem class="domainname">public.localhost</systemitem> for the public
- domain and <systemitem class="domainname">private.localhost</systemitem>
- for the private domain. In an upcoming step, you will configure two special
- <systemitem class="service">ejabberd</systemitem> users
- to handle communications for these two domains.</para>
- <para>As the <systemitem class="username">root</systemitem> user, edit the file
- <filename>/etc/hosts</filename> and add the following example domains:</para>
- <indexterm>
- <primary>Jabber</primary>
- </indexterm>
- <screen>
- <userinput>
- # as the root user:
- 127.0.1.2 public.localhost public
- 127.0.1.3 private.localhost private</userinput>
- </screen>
- </step>
- <step>
- <title>Change File Ownerships</title>
- <para>Finally, as the <systemitem class="username">root</systemitem>
- user, change the ownership of all files installed in the
- directory <filename class="directory">/openils</filename> to the
- user <systemitem class="username">opensrf</systemitem>:</para>
- <screen>
- <userinput>
- # as the root user:
- chown -R opensrf:opensrf /openils</userinput>
- </screen>
- </step>
- </substeps>
- </step>
- <step xml:id="stop-ejabberd-service">
- <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
- <indexterm>
- <primary>ejabberd</primary>
- </indexterm>
- <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
- you must stop that service. As the <systemitem class="username">root</systemitem> user,
- execute the following command to stop the service:</para>
- <screen>
- <userinput>
- # as the root user:
- /etc/init.d/ejabberd stop</userinput>
- </screen>
- <para>If <systemitem class="service">ejabberd</systemitem> reports that it
- is already stopped, there may have been a problem when it started back
- in the installation step. If there are any remaining daemon processes such as
- <systemitem class="daemon">beam</systemitem> or
- <systemitem class="daemon">epmd</systemitem>
- you may need to perform the following commands to kill them:</para>
- <screen>
- <userinput>
- # as the root user:
- epmd -kill
- killall beam; killall beam.smp
- rm /var/lib/ejabberd/*
- echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
- </screen>
- </step>
- <step>
- <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
- <para>You must make several configuration changes for the
- <systemitem class="service">ejabberd</systemitem> service before
- it is started again.
- As the <systemitem class="username">root</systemitem> user, edit the file
- <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
- <substeps>
- <step>
- <para>Change the line:</para>
- <literal>{hosts, ["localhost"]}.</literal>
- <para>to instead read:</para>
- <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
- <para/>
- </step>
- <step>
- <para>Change the line for older versions of
- <systemitem class="service">ejabberd</systemitem>:</para>
- <literal>{max_user_sessions, 10}</literal>
- <para>to instead read:</para>
- <literal>{max_user_sessions, 10000}</literal>
- <para/>
- <para>Change the line for newer versions of
- <systemitem class="service">ejabberd</systemitem>:</para>
- <literal>{access, max_user_sessions, [{10, all}]}</literal>
- <para>to instead read:</para>
- <literal>{access, max_user_sessions, [{10000, all}]}</literal>
- </step>
- <step>
- <para>Change all three occurrences of:</para>
- <literal>max_stanza_size</literal>
- <para>to instead read:</para>
- <literal>2000000</literal>
- </step>
- <step>
- <para>Change both occurrences of:</para>
- <literal>maxrate</literal>
- <para>to instead read:</para>
- <literal>500000</literal>
- </step>
- <step>
- <para>Comment out the line:</para>
- <literal>{mod_offline, []}</literal>
- <para>by placing two <literal>%</literal> comment signs in front
- so it instead reads:</para>
- <literal>%%{mod_offline, []}</literal>
- </step>
- </substeps>
- </step>
- <step xml:id="serversideinstallation-opensrf-continued">
- <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
- <para>As the <systemitem class="username">root</systemitem> user, restart the
- <systemitem class="service">ejabberd</systemitem> service to test the
- configuration changes and to register your users:</para>
- <screen>
- <userinput>
- # as the root user:
- /etc/init.d/ejabberd start</userinput>
- </screen>
- </step>
- <step>
- <title>Register <systemitem class="username">router</systemitem> and
- <systemitem class="username">opensrf</systemitem> as
- <systemitem class="service">ejabberd</systemitem> users</title>
- <para>The two <systemitem class="service">ejabberd</systemitem> users
- <systemitem class="username">router</systemitem> and
- <systemitem class="username">opensrf</systemitem> must be registered
- and configured to manage OpenSRF router service and communications
- for the two domains <literal>public.localhost</literal> and
- <literal>private.localhost</literal> that you added to the file
- <filename>/etc/hosts</filename> in a previous step
- (see <xref linkend="serversideinstallation-definedomains"/>).
- The users include:</para>
- <itemizedlist>
- <listitem>
- <para>the <systemitem class="username">router</systemitem> user,
- to whom all requests to connect to an OpenSRF service will be
- routed;</para>
- </listitem>
- <listitem>
- <para>the <systemitem class="username">opensrf</systemitem> user,
- which clients use to connect to OpenSRF services (you may name
- the user anything you like, but we use
- <literal>opensrf</literal> in these examples)</para>
- </listitem>
- </itemizedlist>
- <para>As the <systemitem class="username">root</systemitem> user, execute the
- <command>ejabberdctl</command> utility as shown below to register and create passwords
- for the users <systemitem class="username">router</systemitem> and
- <systemitem class="username">opensrf</systemitem> on each domain (remember to replace
- <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
- <screen>
- <userinput>
- # as the root user:
- # Note: the syntax for registering a user with ejabberdctl is:
- # ejabberdctl register USER DOMAIN PASSWORD
- ejabberdctl register router private.localhost NEWPASSWORD
- ejabberdctl register router public.localhost NEWPASSWORD
- ejabberdctl register opensrf private.localhost NEWPASSWORD
- ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
- </screen>
- <para>The users <systemitem class="username">router</systemitem> and
- <systemitem class="username">opensrf</systemitem> and their respective passwords
- will be used again in <xref linkend="serversideinstallation-passwords"/> when
- we modify the OpenSRF configuration file
- <filename>/openils/conf/opensrf_core.xml</filename> .</para>
- <note>
- <para>
- There appears to be a problem with <command>ejabberdctl</command> in
- that it does not escape input correctly, so a password like
- <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
- A bug against ejabberd has been filed. To register a password using
- <command>ejabberdctl</command> with special shell characters until such
- time as that bug is resolved, the workaround is to specify a
- double-escaped character at the command line, for example,
- <literal>'0P3N\\\\$RF'</literal> .</para>
- </note>
- </step>
- <step xml:id="serversideinstallation-opensrf-createconfig">
- <title>Create OpenSRF configuration files</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user,
- execute the following commands to create the new configuration files
- <filename>/openils/conf/opensrf_core.xml</filename> and
- <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- cd /openils/conf
- cp opensrf.xml.example opensrf.xml
- cp opensrf_core.xml.example opensrf_core.xml</userinput>
- </screen>
- </step>
- <step xml:id="serversideinstallation-passwords">
- <title>Update usernames and passwords in the OpenSRF configuration file</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
- OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
- and update the usernames and passwords to match the values shown in the
- following table. The left-hand side of
- <xref linkend="serversideinstallation-xpath-table-1"/> shows common XPath
- syntax to indicate the approximate position within the XML file that needs
- changes. The right-hand side of the table shows the replacement values:</para>
- <table xml:id="serversideinstallation-xpath-table-1">
- <?dbfo keep-together="always" ?>
- <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
- <tgroup align="left" cols="2" colsep="1" rowsep="1">
- <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
- <colspec colname="Value" colnum="2" colwidth="2.0*"/>
- <thead>
- <row>
- <entry>XPath location</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>/config/opensrf/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/opensrf/passwd </entry>
- <entry><systemitem class="domainname">private.localhost</systemitem>
- password for
- <systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/gateway/username</entry>
- <entry>
- <systemitem class="username">opensrf</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/gateway/passwd</entry>
- <entry><systemitem class="domainname">public.localhost</systemitem>
- password for
- <systemitem class="username">opensrf</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport/username,
- first entry where server == public.localhost</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport/password,
- first entry where server == public.localhost</entry>
- <entry><systemitem class="domainname">public.localhost</systemitem>
- password for
- <systemitem class="username">router</systemitem> user
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport/username,
- second entry where server == private.localhost</entry>
- <entry>
- <systemitem class="username">router</systemitem>
- </entry>
- </row>
- <row>
- <entry>/config/routers/router/transport/password,
- second entry where server == private.localhost</entry>
- <entry><systemitem class="domainname">private.localhost</systemitem>
- password for
- <systemitem class="username">router</systemitem> user
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>You may also need to modify the file to specify the domains from which
- <systemitem class="service">OpenSRF</systemitem> will accept connections,
- and to which it will make connections.
- If you are installing <application>OpenSRF</application> on a single server
- and using the <systemitem class="domainname">private.localhost</systemitem> and
- <systemitem class="domainname">public.localhost</systemitem> domains,
- these will already be set to the correct values. Otherwise, search and replace
- to match values for your own systems.</para>
- </step>
- <step>
- <title>Set the location of the persistent database</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
- file <filename>/openils/conf/opensrf.xml</filename>, then find and verify that
- the element <literal>dbfile</literal> (near the end of the file) is set to the
- location of the persistent database. If necessary, change the default line:</para>
- <literal>/openils/var/persist.db</literal>
- <para>to instead read:</para>
- <literal>/tmp/persist.db</literal>
- <para>Following is a sample modification of that portion of the file:</para>
- <programlisting language="xml"><![CDATA[
-<!-- Example of an app-specific setting override -->
-<opensrf.persist>
- <app_settings>
- <dbfile>/tmp/persist.db</dbfile>
- </app_settings>
-</opensrf.persist>
-]]></programlisting>
- </step>
- <step xml:id="serversideinstallation-srfsh">
- <title>Create configuration files for users needing <command>srfsh</command></title>
- <para>In this section you will set up a special configuration file for each user
- who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
- shell</emphasis>) utility.</para>
- <indexterm>
- <primary>srfsh</primary>
- </indexterm>
- <para>The software installation will automatically create the utility
- <command>srfsh</command>, a command line diagnostic tool for testing and
- interacting with <application>OpenSRF</application>. It will be used
- in a future step to complete and test the Evergreen installation. See
- <xref linkend="serversideinstallation-testing"/> for further information.</para>
- <para>As the <systemitem class="username">root</systemitem> user, copy the
- sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
- to the home directory of each user who will use <command>srfsh</command>.
- For instance, do the following for the
- <systemitem class="username">opensrf</systemitem> user:</para>
- <screen>
- <userinput>
- # as the root user:
- cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>
- </screen>
- <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
- following changes:</para>
- <itemizedlist>
- <listitem>
- <para>Modify <literal>domain</literal> to be the router hostname
- (following our domain examples,
- <systemitem class="domainname">private.localhost</systemitem> will give
- <command>srfsh</command> access to all OpenSRF services, while
- <systemitem class="domainname">public.localhost</systemitem>
- will only allow access to those OpenSRF services that are
- publicly exposed).</para>
- </listitem>
- <listitem>
- <para>Modify <literal>username</literal> and
- <literal>password</literal> to match the
- <literal>opensrf</literal> Jabber user for the chosen
- domain</para>
- </listitem>
- <listitem>
- <para>Modify <literal>logfile</literal> to be the full path for
- a log file to which the user has write access</para>
- </listitem>
- <listitem>
- <para>Modify <literal>loglevel</literal> as needed for testing</para>
- </listitem>
- <listitem>
- <para>Change the owner of the file to match the owner of the
- home directory</para>
- </listitem>
- </itemizedlist>
- <para>Following is a sample of the file:</para>
- <programlisting language="xml"><![CDATA[
-<?xml version="1.0"?>
-<!-- This file follows the standard bootstrap config file layout -->
-<!-- found in opensrf_core.xml -->
-<srfsh>
-<router_name>router</router_name>
-<domain>private.localhost</domain>
-<username>opensrf</username>
-<passwd>SOMEPASSWORD</passwd>
-<port>5222</port>
-<logfile>/tmp/srfsh.log</logfile>
-<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
-<loglevel>4</loglevel>
-</srfsh>
-]]></programlisting>
- </step>
- <step>
- <title>Modify the environmental variable <envar>PATH</envar> for the
- <systemitem class="username">opensrf</systemitem> user</title>
- <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
- environmental variable <envar>PATH</envar> by adding a new file path to the
- <systemitem class="username">opensrf</systemitem> user's shell configuration
- file <filename>~/.bashrc</filename>:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
- </screen>
- </step>
- <step>
- <title>Start OpenSRF</title>
- <para>As the <systemitem class="username">root</systemitem> user, start the
- <systemitem class="service">ejabberd</systemitem> and
- <systemitem class="service">memcached</systemitem> services:</para>
- <screen>
- <userinput>
- # as the root user:
- /etc/init.d/ejabberd start
- /etc/init.d/memcached start</userinput>
- </screen>
- <para>Then as the <systemitem class="username">opensrf</systemitem> user,
- start OpenSRF as follows:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- osrf_ctl.sh -l -a start_all</userinput>
- </screen>
- <para>The flag <option>-l</option> forces Evergreen to use
- <systemitem class="domainname">localhost</systemitem> (your current system)
- as the hostname. The flag <option>-a start_all</option> starts the
- OpenSRF <systemitem class="service">router</systemitem> ,
- <systemitem class="service">Perl</systemitem> , and
- <systemitem class="service">C</systemitem> services.</para>
- <itemizedlist>
- <listitem>
- <para>You can also start Evergreen without the
- <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
- utility must know the fully qualified domain name for the system
- on which it will execute. That hostname was probably specified
- in the configuration file <filename>opensrf.xml</filename> which
- you configured in a previous step.</para>
- </listitem>
- <listitem>
- <para>If you receive an error message similar to
- <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
- environment variable <envar>PATH</envar> does not include the
- directory <filename class="directory">/openils/bin</filename>.
- As the <systemitem class="username">opensrf</systemitem> user,
- edit the configuration file <filename>~/.bashrc</filename> and
- add the following line:
- <literal>export PATH=$PATH:/openils/bin</literal></para>
- </listitem>
- </itemizedlist>
- </step>
- <step>
- <title>Test connections to OpenSRF</title>
- <para>Once you have installed and started OpenSRF, as the
- <systemitem class="username">root</systemitem> user test your connection to
- <systemitem class="service">OpenSRF</systemitem> with the <command>srfsh</command>
- utility and try to call the <command>add</command> method on the OpenSRF
- <systemitem class="service">math</systemitem> service:</para>
- <screen>
- <userinput>
- # as the root user:
- /openils/bin/srfsh</userinput>
- <computeroutput>
- srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
- <computeroutput>
- Received Data: 4
- ------------------------------------
- Request Completed Successfully
- Request Time in seconds: 0.007519
- ------------------------------------</computeroutput>
- </screen>
- <para>For other <command>srfsh</command> commands, type in
- <userinput>help</userinput> at the prompt.</para>
- </step>
- <step>
- <title>Stop OpenSRF</title>
- <para>After OpenSRF has started, you can stop it at any time by using the
- <command>osrf_ctl.sh</command> again. As the
- <systemitem class="username">opensrf</systemitem>
- user, stop OpenSRF as follows:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- osrf_ctl.sh -l -a stop_all</userinput>
- </screen>
- </step>
- </procedure>
- </section>
- <section xml:id="serversideinstallation-ubuntudebian">
- <title>Installing Evergreen 2.x On <systemitem class="osname">Ubuntu</systemitem> or
- <systemitem class="osname">Debian</systemitem></title>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Debian</secondary>
- </indexterm>
- <indexterm>
- <primary>Linux</primary>
- <secondary>Ubuntu</secondary>
- </indexterm>
- <para>This section outlines the installation process for the latest stable
- version of Evergreen on <systemitem class="osname">Ubuntu</systemitem> or
- <systemitem class="osname">Debian</systemitem> systems. See
- <xref linkend="serversideinstallation-fedora"/> for description of a similar
- installation on a <systemitem class="osname">Fedora 14</systemitem> system.</para>
- <para>In this section you will download, unpack, install, configure and test the Evergreen
- system, including the Evergreen server and the PostgreSQL database system. You will make several
- configuration changes and adjustments to the software, including updates to configure the system
- for your own locale, and some updates needed to work around a few known issues.</para>
- <note>
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
- architectures. There may be differences between the Desktop and Server editions of
- <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
- edition.</para>
- <para>In the following instructions, you are asked to perform certain steps as
- either the <systemitem class="username">root</systemitem> user, the
- <systemitem class="username">opensrf</systemitem> user, or the
- <systemitem class="username">postgres</systemitem> user.</para>
- <itemizedlist>
- <listitem>
- <para><systemitem class="osname">Debian</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- <listitem>
- <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
- <systemitem class="username">root</systemitem> user, issue the command
- <command>sudo su -</command> and enter the password of the
- <systemitem class="username">root</systemitem> user.</para>
- </listitem>
- </itemizedlist>
- <para>To switch from the <systemitem class="username">root</systemitem> user to a
- different user, issue the command <command>su - USERNAME</command>. For example, to
- switch from the <systemitem class="username">root</systemitem> user to the
- <systemitem class="username">opensrf</systemitem> user, issue the command
- <command>su - opensrf</command>. Once you have become a non-root user, to become the
- <systemitem class="username">root</systemitem> user again, simply issue the command
- <command>exit</command>.</para>
- </note>
- <procedure>
- <step>
- <title>Install OpenSRF</title>
- <para>Evergreen software is integrated with and depends on the Open Service
- Request Framework (OpenSRF) software system. For further information on
- installing, configuring and testing OpenSRF, see
- <xref linkend="serversideinstallation-opensrf-2.0.1"/>.</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.9.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.9</filename>
- will be created:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- cd /home/opensrf
- wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.9.tar.gz
- tar zxf Evergreen-ILS-2.0.9.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 in the
- distribution keywords table <xref linkend="serversideinstallation-keywords-evergreen"/>.
- 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.9
- make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
- </screen>
-
- <table xml:id="serversideinstallation-keywords-evergreen">
- <?dbfo keep-together="always" ?>
- <title>Keyword Targets for Evergreen <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-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-lucid</entry>
- <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
- </row>
- <row>
- <entry>fedora13</entry>
- <entry>Fedora "Goddard" (13)</entry>
- </row>
- <row>
- <entry>centos</entry>
- <entry>CentOS 5</entry>
- </row>
- <row>
- <entry>rhel</entry>
- <entry>Red Hat Enterprise Linux 5</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>
- </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.9
- ./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.9
- make STAFF_CLIENT_BUILD_ID=rel_2_0_9 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_9</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_9/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.9
- 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.9
- 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>As the <systemitem class="username">root</systemitem> user, edit the Apache configuration file <filename>/etc/apache2/envvars</filename> and
- change the lines:</para>
- <screen>
- <userinput>
- export APACHE_RUN_USER=www-data
- 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-2.0.1"/>.</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.9.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.9</filename>
- will be created:</para>
- <screen>
- <userinput>
- # as the opensrf user:
- cd /home/opensrf
- wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.9.tar.gz
- tar zxf Evergreen-ILS-2.0.9.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.9
- 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.9
- ./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.9
- make STAFF_CLIENT_BUILD_ID=rel_2_0_9 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_9</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_9/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.9
- 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.9
- 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.9/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.9/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-2.0.0/Open-ILS/examples/lib_ips.txt.example</filename>
- to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
- line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
- the IP address ranges for your library system. Add new lines to represent the IP address
- range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
- values for each branch library found in the table
- <literal>actor.org_unit</literal>.</para>
- <para>Finally, modify the Apache startup script
- <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
- restarting the Apache server:</para>
- <programlisting language="xml"><![CDATA[
-# - Uncomment the following 2 lines to make use of the IP redirection code
-# - The IP file should contain a map with the following format:
-# - actor.org_unit.shortname <start_ip> <end_ip>
-# - e.g. LIB123 10.0.0.1 10.0.0.254
-use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
-OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
-]]></programlisting>
- </section>
- <section>
- <title>(OPTIONAL) Set Up Support For Reports</title>
- <para>Evergreen reports are extremely powerful but require some simple configuration.
- See <xref linkend="report_starting_reporter_service"/> for information on starting and
- stopping the Reporter daemon processes.</para>
- </section>
- </section>
- </section>
-</chapter>
projects / Evergreen-DocBook.git / blobdiff