--- /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>1.6.1.x</entry>
+ <entry>1.4.0</entry>
+ <entry>8.2 / 8.3</entry>
+ </row>
+ <row>
+ <entry>1.6.0.x</entry>
+ <entry>1.2</entry>
+ <entry>8.2 / 8.3</entry>
+ </row>
+ <row>
+ <entry>1.4.x</entry>
+ <entry>1.0</entry>
+ <entry>8.1 / 8.2</entry>
+ </row>
+ <row>
+ <entry>1.2.x</entry>
+ <entry>0.9</entry>
+ <entry>8.1 / 8.2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section xml:id="serversideinstallation-all">
+ <title>Installing Server-Side Software</title>
+ <para>This section describes the installation of the major components of Evergreen server-side software.</para>
+ <para>As far as possible, you should perform the following steps in the exact order given since the
+ success of many steps relies on the successful completion of earlier steps. You should make backup
+ copies of files and environments when you are instructed to do so. In the event of installation problems
+ those copies can allow you to back out of a step gracefully and resume the installation from a known
+ state. See <xref linkend="backingup"/> for further information.</para>
+ <para>Of course, after you successfully complete and test the entire Evergreen installation you should
+ take a final snapshot backup of your system(s). This can be the first in the series of regularly
+ scheduled system backups that you should probably also begin.</para>
+ <section xml:id="serversideinstallation-opensrf">
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>installation</secondary>
+ </indexterm>
+ <title>Installing OpenSRF 1.6.x On <systemitem class="osname">Ubuntu</systemitem> or
+ <systemitem class="osname">Debian</systemitem></title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Debian</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Ubuntu</secondary>
+ </indexterm>
+ <para>This section describes the installation of the latest version of the Open Service Request
+ Framework (OpenSRF), a major component of the Evergreen server-side software, on
+ <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
+ systems. Evergreen software is integrated with and depends on the OpenSRF software
+ system.</para>
+ <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
+ properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
+ continue with any further Evergreen installation steps
+ until you have verified that OpenSRF has been successfully installed and tested.</para>
+ <note>
+ <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
+ platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch
+ (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and
+ <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>
+ <para>In the following instructions, you are asked to perform certain steps as
+ either the <systemitem class="username">root</systemitem> user, the
+ <systemitem class="username">opensrf</systemitem> user, or the
+ <systemitem class="username">postgres</systemitem> user.</para>
+ <itemizedlist>
+ <listitem>
+ <para><systemitem class="osname">Debian</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ <listitem>
+ <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>sudo su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ </itemizedlist>
+ <para>To switch from the <systemitem class="username">root</systemitem> user to a
+ different user, issue the command <command>su - USERNAME</command>. For example, to
+ switch from the <systemitem class="username">root</systemitem> user to the
+ <systemitem class="username">opensrf</systemitem> user, issue the command
+ <command>su - opensrf</command>. Once you have become a non-root user, to become
+ the <systemitem class="username">root</systemitem> user again, simply issue the command
+ <command>exit</command>.</para>
+ </note>
+ <procedure>
+ <step>
+ <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
+ <para>As the <systemitem class="username">root</systemitem> user, add the
+ <systemitem class="username">opensrf</systemitem> user to the system.
+ In the following example, the default shell for the
+ <systemitem class="username">opensrf</systemitem> user is automatically set
+ to <command>/bin/bash</command> to inherit a reasonable environment:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ useradd -m -s /bin/bash opensrf
+ passwd opensrf</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Download and Unpack Latest OpenSRF Version</title>
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>download</secondary>
+ </indexterm>
+ <para>The latest version of OpenSRF can be found here:
+ <ulink url="http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz"></ulink> .
+ As the <systemitem class="username">opensrf</systemitem> user, change to
+ the directory <filename class="directory">/home/opensrf</filename> then download
+ and extract OpenSRF. The new subdirectory
+ <filename class="directory">/home/opensrf/opensrf-1.6.3</filename> will be created:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ wget http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz
+ tar zxf opensrf-1.6.3.tar.gz</userinput>
+ </screen>
+ </step>
+ <step>
+ <title>Install Prerequisites to Build OpenSRF</title>
+ <para>In this section you will install and configure a set of prerequisites that will be
+ used to build OpenSRF. In a following step you will actually build the OpenSRF software
+ using the <command>make</command> utility.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
+ below to build the prerequisites from the software distribution that you just downloaded
+ and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
+ example with the keyword corresponding to the name of one of the
+ <systemitem class="osname">Linux</systemitem> distributions listed in the following
+ distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
+ For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
+ enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ cd /home/opensrf/opensrf-1.6.3
+ make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
+ </screen>
+ <table xml:id="serversideinstallation-keywords-opensrf">
+ <?dbfo keep-together="always" ?>
+ <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
+ <tgroup align="left" cols="2" colsep="1" rowsep="1">
+ <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
+ <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+ <entry>Linux Version</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>debian-etch</entry>
+ <entry>Debian "Etch" (4.0)</entry>
+ </row>
+ <row>
+ <entry>debian-lenny</entry>
+ <entry>Debian "Lenny" (5.0)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-hardy</entry>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-lucid</entry>
+ <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
+ </row>
+ <row>
+ <entry>fedora13</entry>
+ <entry>Fedora "Goddard" (13)</entry>
+ </row>
+ <row>
+ <entry>centos</entry>
+ <entry>Centos</entry>
+ </row>
+ <row>
+ <entry>rhel</entry>
+ <entry>RHEL</entry>
+ </row>
+ <row>
+ <entry>gentoo</entry>
+ <entry>Gentoo</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>This will install a number of packages on the system that are required by OpenSRF,
+ including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
+ CPAN configuration prompt to allow it to automatically configure itself to download and
+ install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
+ it should install prerequisite modules - say <literal>Yes</literal>.</para>
+ </step>
+ <step>
+ <title>Build OpenSRF</title>
+ <para>In this section you will configure, build and install the OpenSRF
+ components that support other Evergreen services.</para>
+ <substeps>
+ <step>
+ <title>Configure OpenSRF</title>
+ <indexterm>
+ <primary>OpenSRF</primary>
+ <secondary>configure</secondary>
+ </indexterm>
+ <para>As the <systemitem class="username">opensrf</systemitem>
+ user, return to the new OpenSRF build directory and use the
+ <command>configure</command> utility to prepare for the next
+ step of compiling and linking the software. If you wish to
+ include support for Python and Java, add the configuration
+ options <option>--enable-python</option> and
+ <option>--enable-java</option>, respectively:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf/opensrf-1.6.3
+ ./configure --prefix=/openils --sysconfdir=/openils/conf
+ make</userinput>
+ </screen>
+ <para>This step will take several minutes to complete.</para>
+ </step>
+ <step>
+ <title>Compile, Link and Install OpenSRF</title>
+ <para>As the <systemitem class="username">root</systemitem>
+ user, return to the new OpenSRF build directory and use the
+ <command>make</command> utility to compile, link and install
+ OpenSRF:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ cd /home/opensrf/opensrf-1.6.3
+ make install</userinput>
+ </screen>
+ <para>This step will take several minutes to complete.</para>
+ </step>
+ <step>
+ <title>Update the System Dynamic Library Path</title>
+ <para>You must update the system dynamic library path to force
+ your system to recognize the newly installed libraries. As the
+ <systemitem class="username">root</systemitem> user, do this by
+ creating the new file
+ <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
+ new library path, then run the command
+ <command>ldconfig</command> to automatically read the file and
+ modify the system dynamic library path:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ echo "/openils/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:</para>
+ <literal>{max_user_sessions, 10}</literal>
+ <para>to instead read:</para>
+ <literal>{max_user_sessions, 10000}</literal>
+ <para/>
+ <para>If the line looks something like this:</para>
+ <literal>{access, max_user_sessions, [{10, all}]}</literal>
+ <para>then change it 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>Note that 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>
+ </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 location of the persistent database</title>
+ <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
+ file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the
+ element <literal>dbfile</literal> (near the end of the file) to set the
+ location of the persistent database. 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> (surf shell), 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>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 other
+ OpenSRF <systemitem class="service">router</systemitem> ,
+ <systemitem class="service">Perl</systemitem> , and
+ <systemitem class="service">C</systemitem> services.</para>
+ <itemizedlist>
+ <listitem>
+ <para>You can also start Evergreen without the
+ <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
+ utility must know the fully qualified domain name for the system
+ on which it will execute. That hostname was probably specified
+ in the configuration file <filename>opensrf.xml</filename> which
+ you configured in a previous step.</para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to
+ <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
+ environment variable <envar>PATH</envar> does not include the
+ directory <filename class="directory">/openils/bin</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PATH=$PATH:/openils/bin</literal></para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <title>Test connections to OpenSRF</title>
+ <para>Once you have installed and started OpenSRF, as the
+ <systemitem class="username">root</systemitem> user, test your connection to
+ <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
+ utility and trying to call the <command>add</command> method on the OpenSRF
+ <systemitem class="service">math</systemitem> service:</para>
+ <screen>
+ <userinput>
+ # 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 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or
+ <systemitem class="osname">Debian</systemitem></title>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Debian</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Linux</primary>
+ <secondary>Ubuntu</secondary>
+ </indexterm>
+ <para>This section outlines the installation process for the latest stable version of
+ Evergreen.</para>
+ <para>In this section you will download, unpack, install, configure and test the Evergreen
+ system, including the Evergreen server and the PostgreSQL database system. You will make several
+ configuration changes and adjustments to the software, including updates to configure the system
+ for your own locale, and some updates needed to work around a few known issues.</para>
+ <note>
+ <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
+ architectures. There may be differences between the Desktop and Server editions of
+ <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
+ edition.</para>
+ <para>In the following instructions, you are asked to perform certain steps as
+ either the <systemitem class="username">root</systemitem> user, the
+ <systemitem class="username">opensrf</systemitem> user, or the
+ <systemitem class="username">postgres</systemitem> user.</para>
+ <itemizedlist>
+ <listitem>
+ <para><systemitem class="osname">Debian</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ <listitem>
+ <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
+ <systemitem class="username">root</systemitem> user, issue the command
+ <command>sudo su -</command> and enter the password of the
+ <systemitem class="username">root</systemitem> user.</para>
+ </listitem>
+ </itemizedlist>
+ <para>To switch from the <systemitem class="username">root</systemitem> user to a
+ different user, issue the command <command>su - USERNAME</command>. For example, to
+ switch from the <systemitem class="username">root</systemitem> user to the
+ <systemitem class="username">opensrf</systemitem> user, issue the command
+ <command>su - opensrf</command>. Once you have become a non-root user, to become the
+ <systemitem class="username">root</systemitem> user again, simply issue the command
+ <command>exit</command>.</para>
+ </note>
+ <procedure>
+ <step>
+ <title>Install OpenSRF</title>
+ <para>Evergreen software is integrated with and depends on the Open Service
+ Request Framework (OpenSRF) software system. For further information on
+ installing, configuring and testing OpenSRF, see
+ <xref linkend="serversideinstallation-opensrf"/>.</para>
+ <para>Follow the steps outlined in that section and run the specified tests to
+ ensure that OpenSRF is properly installed and configured. Do
+ <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
+ any further Evergreen installation steps until you have verified that OpenSRF
+ has been successfully installed and tested.</para>
+ </step>
+ <step>
+ <title>Download and Unpack Latest Evergreen Version</title>
+ <para>The latest version of Evergreen can be found here:
+ <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.8.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-1.6.1.8</filename> will be created:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.8.tar.gz
+ tar zxf Evergreen-ILS-1.6.1.8.tar.gz</userinput>
+ </screen>
+ </step>
+ <step xml:id="serversideinstallation-installprereq">
+ <title>Install Prerequisites to Build Evergreen</title>
+ <para>In this section you will install and configure a set of prerequisites that will be
+ used later in <xref linkend="serversideinstallation-configure"/> and
+ <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
+ using the <command>make</command> utility.</para>
+ <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
+ below to build the prerequisites from the software distribution that you just downloaded
+ and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
+ example with the keyword corresponding to the name of one of the
+ <systemitem class="osname">Linux</systemitem> distributions listed in the following
+ distribution keywords table <xref linkend="serversideinstallation-keywords-evergreen"/> .
+ For example, to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would
+ enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
+ ubuntu-karmic</command>.</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ cd /home/opensrf/Evergreen-ILS-1.6.1.8
+ 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-etch</entry>
+ <entry>Debian "Etch" (4.0)</entry>
+ </row>
+ <row>
+ <entry>debian-lenny</entry>
+ <entry>Debian "Lenny" (5.0)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-hardy</entry>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-intrepid</entry>
+ <entry>Ubuntu "Intrepid Ibex" (8.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
+ </row>
+ <row>
+ <entry>ubuntu-karmic</entry>
+ <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
+ </row>
+ <row>
+ <entry>centos</entry>
+ <entry>Centos</entry>
+ </row>
+ <row>
+ <entry>rhel</entry>
+ <entry>RHEL</entry>
+ </row>
+ <row>
+ <entry>gentoo</entry>
+ <entry>Gentoo</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </step>
+ <step performance="optional" xml:id="serversideinstallation-postgresql-default">
+ <title>(OPTIONAL) Install the PostgreSQL Server</title>
+ <indexterm>
+ <primary>databases</primary>
+ <secondary>PostgreSQL</secondary>
+ </indexterm>
+ <para>Since the PostgreSQL server is usually a standalone server in multi-server
+ production systems, the prerequisite installer Makefile in the previous 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 versions 8.3 or 8.4 are the recommended versions to work
+ with Evergreen version 1.6.1.8 . 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.</para>
+ <para>You will need to install several Perl modules on the other system. As the
+ <systemitem class="username">root</systemitem> user install the following Perl
+ modules:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ # first, ensure the gcc compiler is installed:
+ apt-get install gcc
+
+ # then install the Perl modules:
+ perl -MCPAN -e shell</userinput>
+ <computeroutput>
+ cpan> <userinput>install JSON::XS</userinput>
+ cpan> <userinput>install MARC::Record</userinput>
+ cpan> <userinput>install MARC::File::XML</userinput></computeroutput>
+ </screen>
+ <para>For more information on installing Perl Modules vist the official
+ <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
+ <indexterm>
+ <primary>Perl</primary>
+ <secondary>CPAN</secondary>
+ </indexterm>
+ </step>
+ <step>
+ <title>Update the System Dynamic Library Path</title>
+ <para>You must update the system dynamic library path to force your system to recognize
+ the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
+ do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
+ containing a new library path, then run the command <command>ldconfig</command> to
+ automatically read the file and modify the system dynamic library path:</para>
+ <screen>
+ <userinput>
+ # 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.3</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-1.6.1.8
+ ./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-1.6.1.8
+ make STAFF_CLIENT_BUILD_ID=rel_1_6_1_8 install</userinput>
+ </screen>
+ <para>The Staff Client will also be automatically built, but you must remember
+ to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
+ Staff Client you will use to connect to the Evergreen server.</para>
+ <para>The above commands will create a new subdirectory
+ <filename class="directory">/openils/var/web/xul/rel_1_6_1_8</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_1_6_1_8/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.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>,
+ the path would be
+ <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem> .</para>
+ <substeps>
+ <step>
+ <para>
+ <emphasis role="bold">Create and configure the database</emphasis>
+ </para>
+ <para>As the <systemitem class="username">postgres</systemitem>
+ user on the PostgreSQL system create the PostgreSQL database,
+ then set some internal paths:</para>
+ <screen>
+ <userinput>
+ # 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.3</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-1.6.1.8
+ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
+ --service all --create-schema --create-bootstrap --create-offline \
+ --hostname HOSTNAME --port PORT \
+ --user evergreen --password PASSWORD --database DATABASENAME</userinput>
+ </screen>
+ <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
+ <emphasis role="bold">localhost</emphasis> and
+ <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
+ Of course, values for <emphasis>PASSWORD</emphasis> and
+ <emphasis>DATABASENAME</emphasis> must match the values you used in
+ <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</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-1.6.1.8
+ 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 file</title>
+ <para>You must make several changes to the new Apache
+ configuration file
+ <filename>/etc/apache2/sites-available/eg.conf</filename> .
+ As the <systemitem class="username">root</systemitem> user,
+ edit the file and make the following changes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>In the section
+ <literal><Directory "/openils/var/cgi-bin"></literal>
+ replace 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:
+ <filename>/etc/apache2/ports.conf</filename>. Note that
+ <systemitem class="osname">Debian </systemitem> users
+ should not do this since the conflict does not apply to
+ that operating system.</para>
+ </listitem>
+ <listitem>
+ <para>The following updates are needed to allow the logs
+ to function properly, but it may break other Apache
+ applications on your server:</para>
+ <para>For the
+ <systemitem class="osname">Linux</systemitem> distributions
+ <systemitem class="osname">Ubuntu Hardy</systemitem> or
+ <systemitem class="osname">Debian Etch</systemitem>, as
+ the <systemitem class="username">root</systemitem> user,
+ edit the Apache configuration file
+ <filename>/etc/apache2/apache2.conf</filename> and change
+ the line <literal>User www-data</literal> to <literal>User
+ opensrf</literal>.</para>
+ <para>For the
+ <systemitem class="osname">Linux</systemitem> distributions
+ <systemitem class="osname">Ubuntu Karmic</systemitem>,
+ <systemitem class="osname">Ubuntu Lucid</systemitem> or
+ <systemitem class="osname">Debian Lenny</systemitem>, as
+ the <systemitem class="username">root</systemitem> user,
+ edit the Apache configuration file and change 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>Modify the permissions in the directory
+ <filename class="directory">/openils/var/cgi-bin</filename>
+ to make the files executable:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ chmod 755 /openils/var/cgi-bin/*.cgi</userinput>
+ </screen>
+ </listitem>
+ <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>
+ <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>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
+ . ~/.bashrc</userinput>
+ </screen>
+ </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-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> and
+ <systemitem class="service">memcached</systemitem> services as follows:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ /etc/init.d/ejabberd start
+ /etc/init.d/memcached start</userinput>
+ </screen>
+ </step>
+ <step>
+ <para>As the <systemitem class="username">opensrf</systemitem> user,
+ start Evergreen as follows:</para>
+ <screen>
+ <userinput>
+ # 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 other
+ OpenSRF <systemitem class="service">router</systemitem> ,
+ <systemitem class="service">Perl</systemitem> , and
+ <systemitem class="service">C</systemitem> services.</para>
+ <itemizedlist>
+ <listitem>
+ <para>You can also start Evergreen without the
+ <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
+ utility must know the fully qualified domain name for the system
+ on which it will execute. That hostname was probably specified
+ in the configuration file <filename>opensrf.xml</filename> which
+ you configured in a previous step.</para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to
+ <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
+ environment variable <envar>PATH</envar> does not include the
+ directory <filename class="directory">/openils/bin</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PATH=$PATH:/openils/bin</literal></para>
+ </listitem>
+ <listitem>
+ <para>If you receive an error message similar to <emphasis>Can't
+ locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
+ aborted</emphasis>, then your environment variable
+ <emphasis role="bold">PERL5LIB</emphasis> does not include the
+ directory <filename class="directory">/openils/lib/perl5</filename>.
+ As the <systemitem class="username">opensrf</systemitem> user,
+ edit the configuration file <filename>~/.bashrc</filename> and
+ add the following line:
+ <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <para>In this step you will generate the Web files needed by the Staff Client
+ and catalog, and 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:</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/apache2 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 commands 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
+ <filename>settings-tester.pl</filename> utility to review your Evergreen
+ installation for any system configuration problems:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user:
+ cd /home/opensrf
+ ./Evergreen-ILS-1.6.1.8/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
+ </screen>
+ <para>If the output of <command>settings-tester.pl</command> does not help you
+ find the problem, please do not make any significant changes to your
+ configuration.</para>
+ </listitem>
+ <listitem>
+ <para>Follow the steps in the troubleshooting guide in
+ <xref linkend="troubleshooting"/>.</para>
+ </listitem>
+ <listitem>
+ <para>If you have followed the entire set of installation steps listed here
+ closely, you are probably extremely close to a working system. Gather your
+ configuration files and log files and contact the
+ <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
+ list for assistance before making any drastic changes to your system
+ configuration.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <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 a Linux 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-1.6.1.8/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 Re-Test
+ Server. 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. Refer to
+ <xref linkend="staffclientinstallation-workstationnames"/> for further details.</para>
+ <para>Try to log into the Staff Client with the username <literal>admin</literal> and
+ the password <literal>open-ils</literal>. 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. Note the use of <emphasis>restart</emphasis> to 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:
+ apache2ctl configtest && /etc/init.d/apache2 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"/> for further
+ information). This self-signed security certificate was adequate during
+ testing and development, but will continue to generate warnings in the Staff
+ Client and browser. For a public production server you should configure or
+ purchase a signed SSL certificate.</para>
+ <para>There are several open source software solutions that provide schemes to
+ generate and maintain public key security certificates for your library
+ system. Some popular projects are listed below; please review them for
+ background information on why you need such a system and how you can provide
+ it:</para>
+ <itemizedlist>
+ <listitem>
+ <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
+ </listitem>
+ <listitem>
+ <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
+ </listitem>
+ <listitem>
+ <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
+ </listitem>
+ </itemizedlist>
+ <warning>
+ <para>
+ <emphasis>The temporary SSL key was only created to expedite
+ testing. You should install a proper SSL certificate for a public
+ production system.</emphasis>
+ </para>
+ </warning>
+ </section>
+ <section>
+ <title>(OPTIONAL) IP-Redirection</title>
+ <para>By default, Evergreen is configured so searching the OPAC always starts in the
+ top-level (regional) library rather than in a second-level (branch) library. Instead,
+ you can use "IP-Redirection" to change the default OPAC search location to use the IP
+ address range assigned to the second-level library where the seach originates. You must
+ configure these IP ranges by creating the configuration file
+ <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
+ <filename>/etc/apache2/startup.pl</filename>.</para>
+ <para>First, copy the sample file
+ <filename>/home/opensrf/Evergreen-ILS-1.6.1.8/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 xml:id="serversideinstallation-virtual">
+ <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
+ <para>This section describes the installation of Evergreen software in so-called
+ "virtualized" software environments running on the
+ <systemitem class="osname">Microsoft Windows</systemitem> operating system.
+ Evergreen software runs as a native application
+ on any of several well-known x86 (32-bit) and x86-64 (64-bit)
+ <systemitem class="osname">Linux</systemitem> distributions including
+ <systemitem class="osname">Ubuntu</systemitem> and
+ <systemitem class="osname">Debian</systemitem>, but will not run directly on
+ the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
+ Instead, Evergreen executes within an encapsulated virtual
+ <systemitem class="osname">Linux</systemitem> "guest" installation,
+ which itself executes directly on <systemitem class="osname">Windows</systemitem>.
+ The <systemitem class="osname">Linux</systemitem> environment is fully emulated
+ and acts (within limits) just as if it were executing on a real standalone system.</para>
+ <para>This technique of emulating a <systemitem class="osname">Linux</systemitem>
+ environment on a <systemitem class="osname">Windows</systemitem> host is a practical
+ way to install and run an Evergreen system if it is not possible to dedicate a
+ physical machine solely as a <systemitem class="osname">Linux</systemitem> host, but
+ the architecture is not recommended for large scale systems. There are performance
+ limitations to running Evergreen in a virtualized environment, since the
+ virtualization application itself consumes memory and contributes to the CPU load on
+ the <systemitem class="osname">Windows</systemitem> host system. The emulated
+ Evergreen environment will execute more slowly than if it were a standalone system.
+ However, it is still a reasonable architecture for smaller experimental systems or as
+ a proof of concept.</para>
+ <section>
+ <title>Installing Virtualization Software</title>
+ <para>As described above, Evergreen can be installed on top of an emulated
+ <systemitem class="osname">Linux</systemitem> environment which, in turn,
+ is installed on top of a software application such as
+ <application>"VirtualBox"</application> or <application>"VMware"</application>
+ executing on <systemitem class="osname">Windows</systemitem>.
+ This section contains step-by-step examples on installing popular virtualization
+ applications on a <systemitem class="osname">Windows</systemitem> host system.
+ Following this section are further descriptions of installing
+ <systemitem class="osname">Linux</systemitem> and Evergreen systems on top
+ of that virtualization software.</para>
+ <section xml:id="serversideinstallation-virtual-vbox-install">
+ <title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
+ <para>This section reviews installation of the
+ <application>"VirtualBox"</application> application on
+ <systemitem class="osname">WindowsXP Professional (SP3)</systemitem>.
+ Download the latest version of the
+ <application>VirtualBox</application> from the official website:
+ <ulink url="http://www.virtualbox.org/wiki/Downloads">
+ http://www.virtualbox.org/wiki/Downloads</ulink>,
+ then run the executable file. Continue with the steps shown in the
+ next five figures until the software has been successfully
+ installed. The following example shows the installation of VirtualBox
+ version 3.8.2 .</para>
+ <figure>
+ <title>Starting the Windows installation of <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-1.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Welcome to <application>VirtualBox</application> setup wizard</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-2.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Accept the license agreement</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-3.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Waiting for installation to complete</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-4.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Installation is complete; start <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-5.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>At this point, <application>VirtualBox</application> has been
+ installed and started for the first time. Please continue with
+ <xref linkend="serversideinstallation-virtual-install-linux-ev"/>
+ for further instructions on the next step: installing the
+ <systemitem class="osname">Linux</systemitem> / Evergreen distribution.</para>
+ </section>
+ <section>
+ <title>Installing <application>"VMware"</application> Virtualization Software</title>
+ <para>For instructions on installing <application>VMware</application>,
+ visit the official website <ulink url="http://www.vmware.com/">
+ http://www.vmware.com/</ulink>. Then continue with
+ <xref linkend="serversideinstallation-virtual-install-linux-ev"/> for
+ further instructions on the next step: installing the
+ <systemitem class="osname">Linux</systemitem> / Evergreen distribution.</para>
+ </section>
+ </section>
+ <section xml:id="serversideinstallation-virtual-install-linux-ev">
+ <title>Installing <systemitem class="osname">Linux</systemitem>
+ / Evergreen on Virtualization Software</title>
+ <para>After the virtualization software is installed and running, there are
+ two ways to continue with installing
+ <systemitem class="osname">Linux</systemitem> and Evergreen software in the new
+ virtualized environment:</para>
+ <orderedlist>
+ <listitem>
+ <para>Manually install a
+ <systemitem class="osname">Linux</systemitem> guest system,
+ then manually install Evergreen on it (see
+ <xref linkend="serversideinstall-virtual-manual"/> for
+ details)</para>
+ </listitem>
+ <listitem>
+ <para>Download and install a prebuilt software image. The following
+ example shows installation of a working Debian "Lenny" (5.0)
+ <systemitem class="osname">Linux</systemitem> / Evergreen 1.6.1.4 system
+ (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
+ details)</para>
+ </listitem>
+ </orderedlist>
+ <para>We review each method in the following sections.</para>
+ <section xml:id="serversideinstall-virtual-manual">
+ <title>Manually install <systemitem class="osname">Linux</systemitem> and Evergreen</title>
+ <para>Instead of installing a pre-built, pre-configured virtual image
+ of <systemitem class="osname">Linux</systemitem> containing the
+ Evergreen software, you could just install a bare virtual
+ <systemitem class="osname">Linux</systemitem> guest system, then install
+ Evergreen from scratch on that system.</para>
+ <para>We recommend this approach if you need to specially configure
+ either the <systemitem class="osname">Linux</systemitem> system or
+ Evergreen itself. This will require a detailed review of both
+ <systemitem class="osname">Linux</systemitem> and Evergreen
+ configuration details. You are essentially doing a normal Evergreen
+ installation on a <systemitem class="osname">Linux</systemitem>
+ system; it just happens that
+ <systemitem class="osname">Linux</systemitem> is running within a
+ virtualized environment on a <systemitem class="osname">Windows</systemitem>
+ system. See <xref linkend="serversideinstallation-ubuntudebian"/> for
+ information on a normal Evergreen installation.</para>
+ </section>
+ <section xml:id="serversideinstall-virtual-prebuilt">
+ <title>Download and install a prebuilt software image</title>
+ <para>You can download a prebuilt software image that, when installed
+ on your virtualization software, emulates a
+ <systemitem class="osname">Linux</systemitem> guest system containing
+ a running Evergreen distribution. The image is essentially a snapshot
+ of a hard disk from a fully configured, functional
+ <systemitem class="osname">Linux</systemitem> system with Evergreen
+ already installed. It is even possible to install a software image
+ that is preloaded with useful data, e.g., Gutenberg records.</para>
+ <para>We recommend this approach if you wish to get Evergreen running
+ quickly with minimal attention to configuration. After adjusting only
+ a few configuration details you can have a working Evergreen system
+ that integrates smoothly with the rest of your network. See
+ <xref linkend="serversideinstall-virtual-versions"/> for a list of
+ prebuilt software images that are currently available to download and
+ install.</para>
+ <note>Evergreen servers and staff clients must match. For example, if
+ you are running server version 1.4.0.1, you should use version 1.4.0.1
+ of the staff client.</note>
+ <note>DISCLAIMER: The following virtual images have been contributed
+ by members of the Evergreen community for the purposes of testing,
+ evaluation, training, and development.</note>
+ <table xml:id="serversideinstall-virtual-versions">
+ <?dbfo keep-together="always" ?>
+ <title>Linux / Evergreen Virtual Images</title>
+ <tgroup align="left" cols="4" colsep="1" rowsep="1">
+ <colspec colname="Linux_version" colnum="1" colwidth="2.0*"/>
+ <colspec colname="EV_version" colnum="2" colwidth="1.0*"/>
+ <colspec colname="download_link" colnum="3" colwidth="1.0*"/>
+ <colspec colname="comments" colnum="4" colwidth="3.0*"/>
+ <thead>
+ <row>
+ <entry>Linux Version</entry>
+ <entry>Evergreen Version</entry>
+ <entry>Image</entry>
+ <entry>Comments</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Debian "Lenny" (5.0)</entry>
+ <entry>1.6.1.4</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen_1_6_1_4_Lenny.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Debian "Lenny" (5.0)</entry>
+ <entry>1.6.0.1</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
+ <entry>1.6.0.0</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ <entry>1.2.3.1</entry>
+ <entry>
+ <ulink url="http://open-ils.org/~denials/Ubuntu804.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Debian Etch (4.0)</entry>
+ <entry>1.2.2.3</entry>
+ <entry>
+ <ulink url="http://evergreen-ils.org/~denials/Evergreen_Debian_1.2.2.3.zip">
+ download</ulink>
+ </entry>
+ <entry>VMware image (preloaded with 13,000 Gutenberg records)</entry>
+ </row>
+ <row>
+ <entry>Ubuntu "Gutsy Gibbon" (7.10)</entry>
+ <entry>1.2.1.4</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/downloads/vmware/Evergreen_1.2.1.4_on_Ubuntu_7.10.zip">
+ download</ulink>
+ </entry>
+ <entry>VMware image, contributed by
+ <ulink url="http://library.calvin.edu/">
+ the Hekman Library, Calvin College</ulink></entry>
+ </row>
+ <row>
+ <entry>Gentoo</entry>
+ <entry>1.1.5</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen_1.1.5_Gentoo_x86.zip">
+ download </ulink>
+ </entry>
+ <entry>VMware image on Gentoo, courtesy of
+ <ulink url="http://coffeecode.net/">Dan Scott</ulink>,
+ <ulink url="http://laurentian.ca/library">Laurentian University</ulink>
+ (file size is 1.1GB)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>In the following example you will install a prebuilt Debian
+ "Lenny" (5.0) / Evergreen 1.6.1.4 system. We assume you have already
+ installed the <application>VirtualBox</application> application (see
+ <xref linkend="serversideinstallation-virtual-vbox-install"/> for
+ details). Continue with the following steps; refer to the accompanying
+ figures for more information:</para>
+ <procedure>
+ <step>
+ <title>Download software</title>
+ <para>Download the prebuilt software image for Debian
+ "Lenny" (5.0) / Evergreen 1.6.1.4 contained in the
+ file <literal>Evergreen_1_6_1_4_Lenny.zip</literal> .
+ Create a temporary directory
+ <literal>C:\temp</literal>, then extract the contents
+ of the <literal>.ZIP</literal> file there.</para>
+ </step>
+ <step>
+ <title>Add new virtual disk</title>
+ <para>You must configure VirtualBox to recognized the new disk
+ image before you can create a new virtual machine to use it.
+ Start VirtualBox and select
+ <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>,
+ then choose the disk image <literal>Lenny_1614_disk1.vmdk</literal>
+ that you just extracted to the temporary directory. Review
+ <xref linkend="serversideinstallation-virtual-vm-install-2"/>,
+ <xref linkend="serversideinstallation-virtual-vm-install-3"/> and
+ <xref linkend="serversideinstallation-virtual-vm-install-4"/>
+ for details.</para>
+ </step>
+ <step>
+ <title>Start virtual machine wizard</title>
+ <para>Click <guibutton>New</guibutton> to start the "Virtual
+ Machine Wizard", then click <guibutton>Next</guibutton> to
+ create a new virtual machine (VM)
+ <xref linkend="serversideinstallation-virtual-vm-install-5"/>).</para>
+ </step>
+ <step>
+ <title>Define new virtual machine</title>
+ <para>Define a name for the new virtual machine, set the operating
+ system type, then click <guibutton>Next</guibutton> (see
+ <xref linkend="serversideinstallation-virtual-vm-install-6"/>).</para>
+ </step>
+ <step>
+ <title>Set memory size</title>
+ <para>Set the memory size (we chose a default value of 512Mb),
+ then click <guibutton>Next</guibutton> (see
+ <xref linkend="serversideinstallation-virtual-vm-install-7"/>).</para>
+ </step>
+ <step>
+ <title>Attach virtual disk</title>
+ <para>Attach the virtual hard disk image by setting the radio boxes
+ <literal>Boot Hard Disk</literal> and <literal>Use existing hard
+ disk</literal>. Ensure that the proper disk name is selected.
+ Click <guibutton>Finish</guibutton> to finish the setup. Review
+ <xref linkend="serversideinstallation-virtual-vm-install-8"/>,
+ <xref linkend="serversideinstallation-virtual-vm-install-9"/> and
+ and <xref linkend="serversideinstallation-virtual-vm-install-10"/>
+ for details.</para>
+ </step>
+ <step>
+ <title>Start new virtual machine</title>
+ <para>Click <guibutton>Start</guibutton> to boot the new VM.</para>
+ </step>
+ <step>
+ <title>Manually start Evergreen</title>
+ <para>After the new virtual machine boots up for the first time,
+ you must manually start Evergreen. Start it as follows, starting
+ as the root user (see
+ <xref linkend="serversideinstallation-starting"/> for more
+ information):</para>
+ <screen>
+ <userinput>
+ su - # become the root user - enter "evergreen" for the password
+ su - opensrf # as the opensrf user
+ osrf_ctl.sh -l -a start_all # start all Evergreen services
+ exit # become the root user again
+ /etc/init.d/apache2 restart # restart the Apache server</userinput>
+ </screen>
+ <para>The following table lists the default accounts already set
+ up in the virtual machine:</para>
+ <table xml:id="serversideinstall-virtual-accounts">
+ <?dbfo keep-together="always" ?>
+ <title>Default Accounts</title>
+ <tgroup align="left" cols="3" colsep="1" rowsep="1">
+ <colspec colname="account" colnum="1" colwidth="1.0*"/>
+ <colspec colname="password" colnum="2" colwidth="1.0*"/>
+ <colspec colname="type" colnum="3" colwidth="1.0*"/>
+ <thead>
+ <row>
+ <entry>Account</entry>
+ <entry>Password</entry>
+ <entry>Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>root</entry>
+ <entry>evergreen</entry>
+ <entry>Linux account</entry>
+ </row>
+ </tbody>
+ <tbody>
+ <row>
+ <entry>evergreen</entry>
+ <entry>evergreen</entry>
+ <entry>Linux account</entry>
+ </row>
+ </tbody>
+ <tbody>
+ <row>
+ <entry>opensrf</entry>
+ <entry>evergreen</entry>
+ <entry>Linux account</entry>
+ </row>
+ </tbody>
+ <tbody>
+ <row>
+ <entry>evergreen</entry>
+ <entry>evergreen</entry>
+ <entry>Database account</entry>
+ </row>
+ </tbody>
+ <tbody>
+ <row>
+ <entry>admin</entry>
+ <entry>open-ils</entry>
+ <entry>Evergreen account</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>At this point you have a running
+ <systemitem class="osname">Linux</systemitem> / Evergreen system. If
+ you need to modify the Evergreen configuration in any way, review
+ <xref linkend="serversideinstallation-ubuntudebian"/>
+ in the standard Evergreen installation instructions.</para>
+ </step>
+ <step>
+ <title>Start staff client</title>
+ <para> The virtual machine just installed has been configured
+ to include an optional graphical desktop environment. If you
+ configure the virtual machine for 1.0 GB RAM, you should be
+ able to run the desktop at the same time as Evergreen. To
+ start the desktop, log in as the
+ <systemitem class="username">opensrf</systemitem> user and
+ enter the command <command>startx</command>.</para>
+ <para>The desktop in this virtual machine includes the web
+ browser <application>IceWeasel</application> (the
+ <systemitem class="osname">Debian</systemitem> version of
+ Firefox) and <emphasis>XULRunner 1.9</emphasis>. Once you
+ start the desktop and Evergreen, you can connect to Evergreen
+ using the built-in staff client with the following
+ commands:</para>
+ <screen>
+ <userinput>
+ # as the opensrf user
+ cd /home/opensrf/Evergreen-ILS-1.6.1.8/Open-ILS
+ xulrunner-1.9 xul/staff_client/build/application.ini</userinput>
+ </screen>
+ <para>Connect to
+ <emphasis role="bold">localhost</emphasis> using the
+ username and password
+ <emphasis role="bold">admin</emphasis> /
+ <emphasis role="bold">open-ils</emphasis> and begin populating the
+ data in your image.</para>
+ </step>
+ <step>
+ <title>(OPTIONAL) Modify network connections</title>
+ <para>This machine was configured with a NAT connection on the
+ first Ethernet adapter
+ (<emphasis role="bold">eth0</emphasis>). As the virtual machines
+ tend to map virtual devices to real MAC addresses on their host,
+ you might need to clear that mapping before making a connection.
+ As root, run:</para>
+ <screen>
+ <userinput>
+ # as the root user:
+ rm /etc/udev/rules.d/70-persistent-net.rules
+ reboot</userinput>
+ </screen>
+ <para>To create a network connection, as root run:
+ <emphasis role="bold">dhclient eth0</emphasis> to set up a NAT
+ connection.</para>
+ </step>
+ <step xml:id="serversideinstallation-virtual-vm-host-based">
+ <title>Add another host connection</title>
+ <para>To add another host connection, you must add a second
+ Ethernet adapter (<emphasis role="bold">eth1</emphasis>) network
+ configuration interface and configure it as a host-based
+ connection. After you add the second Ethernet adapter for the
+ host connection, to create the host network connection, as root
+ run: <emphasis role="bold">dhclient eth1</emphasis>.</para>
+ <para>To connect to your virtual machine from your host
+ machine, create the host connection and check the IP address
+ of device <literal>eth1</literal> using the
+ <command>ifconfig</command> command:
+ <emphasis role="bold">/sbin/ifconfig eth1</emphasis>. The IP address
+ will be listed in the inet_addr stanza as something like: <emphasis role="bold">inet addr: 192.168.56.101</emphasis>.</para>
+ </step>
+ <step>
+ <title>Network connections for external staff clients</title>
+ <para>While you can use the IP address to access the OPAC, the
+ staff client needs a hostname to connect to Evergreen. For the
+ built-in staff client in the Linux graphical desktop, you can
+ just use <literal>"localhost"</literal>. But for external staff
+ clients, if your network does not assign a real hostname to the
+ IP address for the virtual image, you may need to alter the
+ hosts file on your client workstations to provide an alias for
+ the IP address.</para>
+ <para>On Linux, the hosts file can be found in the file
+ <filename>/etc/hosts</filename>. On
+ <systemitem class="osname">Windows</systemitem>, the hosts file
+ can be found in
+ <filename>C:\WINDOWS\System32\drivers\etc\hosts</filename>.</para>
+ </step>
+ <step>
+ <title>External staff clients</title>
+ <para>You can connect a staff client to the virtual Evergreen system
+ by getting your host-based connection running (see
+ <xref linkend="serversideinstallation-virtual-vm-host-based"/>).
+ Once you have a host-based connection, you can install and use the
+ <systemitem class="osname">Windows</systemitem> 1.6.1.8 staff
+ client available from
+ <ulink url="http://evergreen-ils.org/downloads/evergreen-setup-rel_1_6_1_8.exe">
+ http://evergreen-ils.org/downloads/evergreen-setup-rel_1_6_1_8.exe</ulink>
+ to connect to the virtual Evergreen system from another
+ <systemitem class="osname">Windows</systemitem> machine.</para>
+ </step>
+ </procedure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-2">
+ <title>Starting <application>VirtualBox</application> for the first time</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-2.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-3">
+ <title>Selecting the software image in Virtual Media Manager</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-3.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-4">
+ <title>New software image added to <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-4.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-5">
+ <title>Creating a new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-5.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-6">
+ <title>Setting the VM name and OS type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-6.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-7">
+ <title>Setting memory size</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-7.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-8">
+ <title>Setting up the Virtual Hard Disk</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-8.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-9">
+ <title>Finishing definition of new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-9.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-10">
+ <title>Summary of the new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-10.png" format="PNG" scalefit="1" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ </section>
+ </section>
+</chapter>
projects / Evergreen-DocBook.git / blobdiff