+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>\r
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
- xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serversideinstallation-previousversions">\r
-\r
- <title>Installing Previous Versions of Evergreen</title>\r
- <para>Earlier releases of Evergreen are available. Instructions for installing, configuring and testing earlier versions are found below.</para>\r
- <para>The next most recent previous release of Evergreen is version <emphasis><emphasis role="bold">1.4.0.6</emphasis></emphasis>. The accompanying previous release of OpenSRF \r
- is version <emphasis><emphasis role="bold">1.0.7</emphasis></emphasis>.</para>\r
- <section xml:id="serversideinstallation-evergreen-previous">\r
- <title>Installing Evergreen 1.4.0.6 On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem></title>\r
- <para>This section outlines the installation process for the previous version 1.4.0.6 of Evergreen.</para>\r
- <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>\r
- <note>\r
- <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>\r
- <para>If you are starting with a clean install of <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>, you are strongly recommended <emphasis role="bold">not</emphasis> to install the packaged PostgreSQL server. This can confuse port numbers and system configuration. Evergreen 1.4 requires PostgreSQL 8.2.</para>\r
- </note>\r
- <section>\r
- <title>Installing OpenSRF 1.0.7</title>\r
- <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-previous"/>.</para>\r
- <para>Follow the steps outlined in that section and run the specified tests to ensure that OpenSRF is properly installed and configured. Do not continue with any further Evergreen installation steps until you have verified that OpenSRF has been successfully installed.</para>\r
- </section>\r
- <section>\r
- <title>Download and Unpack Evergreen Version 1.4.0.6</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the latest version of Evergreen. The latest version can be found here: <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz"></ulink></para>\r
- <figure>\r
- <title>Commands to download and unpack Evergreen</title>\r
- <screen>\r
- $ su - opensrf\r
- $ wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz\r
- $ tar zxf Evergreen-ILS-1.4.0.6.tar.gz\r
- </screen>\r
- </figure>\r
- <para>The new directory <filename class="directory">/home/opensrf/Evergreen-ILS-1.4.0.6</filename> will be created.</para>\r
- </section>\r
- <section>\r
- <title>Install Prerequisites to Build Evergreen</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be used to build Evergreen. In a following step you will actually build the software using the <command>make</command> utility.</para>\r
- <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 example with the keyword corresponding to the actual <systemitem class="osname">Linux</systemitem> distribution listed in the <link linkend="serversideinstallation-keywords-figure-2-a">"Keywords"</link> figure below.</para>\r
- <figure>\r
- <title>Commands to install prerequisites for Evergreen</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ make -f Open-ILS/src/extras/Makefile.install [distribution]\r
- ...\r
- </screen>\r
- </figure>\r
- <table xml:id="serversideinstallation-keywords-figure-2-a">\r
- <title>Keywords Targets for <application>"make"</application> Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>debian-lenny</entry>\r
- <entry>for Debian Lenny (5.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-etch</entry>\r
- <entry>for Debian Etch (4.0)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-intrepid</entry>\r
- <entry>for Ubuntu Intrepid (8.10)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-hardy</entry>\r
- <entry>for Ubuntu Hardy (8.04)</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- </section>\r
- <section>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating the new file <filename>/etc/ld.so.conf.d/eg.conf</filename> containing two new library paths, then run the command <command>ldconfig</command> to automatically read the file and modify the system dynamic library path:</para>\r
- <figure>\r
- <title>Commands to modify system dynamic library path</title>\r
- <screen>\r
- $ su - root\r
- $ cat > /etc/ld.so.conf.d/eg.conf << ENDOFFILE\r
- /usr/local/lib\r
- /usr/local/lib/dbd\r
- ENDOFFILE\r
- $ ldconfig\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Restart the PostgreSQL Server</title>\r
- <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 the PostgreSQL server to avoid a problem where the library <filename>plperl.so</filename> cannot be found. If your PostgreSQL server is running on another system, just skip this step.</para>\r
- <figure>\r
- <title>Commands to restart PostgreSQL server</title>\r
- <screen>\r
- $ su - root\r
- $ /etc/init.d/postgresql-8.2 restart\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Configure Evergreen</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to the Evergreen build directory and use the <command>configure</command> utility to prepare for the next step of compiling and linking the software:</para>\r
- <figure>\r
- <title>Commands to configure Evergreen</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- $ make\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Compile, Link and Install Evergreen</title>\r
- <para>In this step you will actually compile, link and install Evergreen and the default Evergreen Staff Client.</para>\r
- <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. 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>\r
- <para>For further information on manually building the Staff Client, see <xref linkend="serversideinstallation-building-staffclient"/>.</para>\r
- <figure>\r
- <title>Commands to build, link and install Evergreen</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ make STAFF_CLIENT_BUILD_ID=rel_1_4_0_6 install\r
- ...\r
- </screen>\r
- <para>The above commands will create a new subdirectory <filename class="directory">/openils/var/web/xul/rel_1_4_0_6</filename> containing the Staff Client.</para>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Copy the OpenSRF Configuration Files</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, copy the example OpenSRF configuration files into place. This replaces the configuration files that you set up in a previous step when you installed and tested OpenSRF. You should also create backup copies of the old files for troubleshooting purposes. Finally, change the ownership on the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>\r
- <figure>\r
- <title>Commands to copy OpenSRF configuration files</title>\r
- <screen>\r
- $ su - root\r
- $ cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml\r
- $ cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml\r
- $ chown -R opensrf:opensrf /openils/\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Create and Configure PostgreSQL Database</title>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on your PostgreSQL server, create the Evergreen database.</para>\r
- <para>In the commands below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis> repository to match your PostgreSQL server layout. For example, if you built PostgreSQL from source the path would be <filename class="directory">/usr/local/share/contrib</filename>; if you installed the PostgreSQL 8.2 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>, the path would be <filename class="directory">/usr/share/postgresql/8.2/contrib/</filename>.</para>\r
- <procedure>\r
- <step>\r
- <para>\r
- <emphasis role="bold">Create and configure the database</emphasis>\r
- </para>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL system create the PostgreSQL database, then set some internal paths:</para>\r
- <figure>\r
- <title>Commands to create database and adjust the path</title>\r
- <screen>\r
- # create the database\r
- $ su - postgres\r
- $ createdb -E UNICODE evergreen\r
- $ createlang plperl evergreen\r
- $ createlang plperlu evergreen\r
- $ createlang plpgsql evergreen\r
- \r
- # adjust the paths\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen\r
- </screen>\r
- </figure>\r
- <emphasis>Where <literal>PGSQL_VERSION</literal> is your installed PostgreSQL version (e.g. <literal>8.2</literal>).</emphasis>\r
- </step>\r
- <step>\r
- <para>\r
- <emphasis role="bold">Create new Evergreen superuser</emphasis>\r
- </para>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL system, create the \r
- new database <systemitem class="username">evergreen</systemitem> user and assign a password:</para>\r
-<screen>\r
-# create superuser 'evergreen' and set the password\r
-<userinput>su - postgres</userinput>\r
-<userinput>createuser -P -s evergreen</userinput>\r
-<prompt>Enter password for new role:</prompt> <userinput>MYNEWPASSWORD</userinput>\r
-<prompt>Enter it again:</prompt><userinput>MYNEWPASSWORD</userinput>\r
-</screen>\r
- <emphasis>Where <literal>MYNEWPASSWORD</literal> is the password chosen.</emphasis>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section>\r
- <title>Create Database Schema</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, create the database schema and configure your system with the corresponding database authentication details for the <emphasis>evergreen</emphasis> database user that you created in the previous step.</para>\r
- <para>Enter the following commands and replace <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate values.</para>\r
- <figure>\r
- <title>Commands to create Evergreen database schema</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
- --service all --create-schema --create-bootstrap --create-offline \\r
- --hostname HOSTNAME --port PORT \\r
- --user evergreen --password PASSWORD --database DATABASENAME\r
- </screen>\r
- </figure>\r
- <emphasis>Where, on most systems, <emphasis>HOSTNAME</emphasis> will be <emphasis role="bold">localhost</emphasis>, <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>, and <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> will be those assigned when PostgreSQL was installed in the previous step.</emphasis>\r
- <note>\r
- <para>\r
- <emphasis>If you are entering the above command on a single line, do not include the <literal>\</literal> (backslash) characters. If you are using the <command>bash</command> shell, these should only be used at the end of a line at a bash prompt to indicate that the command is continued on the next line.</emphasis>\r
- </para>\r
- </note>\r
- </section>\r
- <section>\r
- <title>Evergreen installation - (continued)</title>\r
- <para><emphasis>The remainder of the Evergreen installation procedure is identical to that for installing the latest version of Evergreen. Continue with the instructions found in</emphasis> <xref linkend="serversideinstallation-modify-apache"/>.</para>\r
- </section>\r
- </section>\r
- <section xml:id="serversideinstallation-opensrf-previous">\r
- <title>Installing OpenSRF 1.0.7 On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem></title>\r
- <para>This section describes the installation of the previous 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>\r
- <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is properly installed and configured. Do not continue with any further Evergreen installation steps until you have verified that OpenSRF has been successfully installed.</para>\r
- <note>\r
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) platforms. OpenSRF 1.0.7 has been tested on <systemitem class="osname">Debian Etch (4.0)</systemitem>, <systemitem class="osname">Debian Lenny</systemitem>, <systemitem class="osname">Ubuntu Hardy Heron (8.04)</systemitem>, and <systemitem class="osname">Ubuntu Intrepid Ibex (8.10)</systemitem>.</para>\r
- <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>\r
- <itemizedlist>\r
- <listitem><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.</listitem>\r
- <listitem><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.</listitem>\r
- </itemizedlist>\r
- <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>\r
- </note>\r
- <section>\r
- <title>Add the OpenSRF User</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, add the opensrf user to the system. The default shell for the new user is automatically set to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
- <figure>\r
- <title>Commands to add <systemitem class="username">opensrf</systemitem> user</title>\r
- <screen>\r
- $ su - opensrf\r
- $ useradd -m -s /bin/bash opensrf\r
- $ passwd opensrf\r
- Enter new UNIX password: ******\r
- Retype new UNIX password: ******\r
- passwd: password updated successfully\r
- $\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Download and Unpack Latest OpenSRF Version</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the latest version of OpenSRF. The latest version can be found here: <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.0.7.tar.gz"></ulink></para>\r
- <figure>\r
- <title>Commands to download and unpack OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ wget http://evergreen-ils.org/downloads/OpenSRF-1.0.7.tar.gz\r
- $ tar zxf OpenSRF-1.0.7.tar.gz\r
- </screen>\r
- </figure>\r
- <para>The new directory <filename class="directory">/home/opensrf/OpenSRF-1.0.7</filename> will be created.</para>\r
- </section>\r
- <section>\r
- <title>Install Prerequisites to Build OpenSRF</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be used to build OpenSRF. In a following step you will actually build the software using the <command>make</command> utility.</para>\r
- <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 example with the keyword corresponding to the actual <systemitem class="osname">Linux</systemitem> distribution listed in the <link linkend="serversideinstallation-keywords-figure-1a">"Keywords"</link> figure below.</para>\r
- <figure>\r
- <title>Commands to install prerequisites for OpenSRF</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ make -f src/extras/Makefile.install [DISTRIBUTION]\r
- ...\r
- </screen>\r
- </figure>\r
- <table xml:id="serversideinstallation-keywords-figure-1a">\r
- <title>Keywords Targets for <application>"make"</application> Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>debian-lenny</entry>\r
- <entry>for Debian Lenny (5.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-etch</entry>\r
- <entry>for Debian Etch (4.0)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-intrepid</entry>\r
- <entry>for Intrepid (8.10)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-hardy</entry>\r
- <entry>for Ubuntu Hardy (8.04)</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <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>\r
- </section>\r
- <section>\r
- <title>Configure OpenSRF</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to the OpenSRF build directory and use the <command>configure</command> utility to prepare for the next step of compiling and linking the software. You can include the <option>--enable-python</option> and <option>--enable-java</option> configuration options if you wish to include support for Python and Java, respectively:</para>\r
- <figure>\r
- <title>Commands to configure OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- $ make\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Compile, Link and Install OpenSRF</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, return to the OpenSRF build directory and use the <command>make</command> utility to compile, link and install OpenSRF:</para>\r
- <figure>\r
- <title>Commands to build, link and install OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ make install\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. 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>\r
- <figure>\r
- <title>Commands to modify system dynamic library path</title>\r
- <screen>\r
- $ su - root\r
- $ echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf\r
- $ ldconfig\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Define Public and Private OpenSRF Domains</title>\r
- <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, 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. On a single-server system, the easiest way to define public and private domains is to define separate host names by adding entries to the file <filename>/etc/hosts</filename>.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/hosts</filename> and add the following entries for our example domains:</para>\r
- <figure>\r
- <title>Example public and private domains in /etc/hosts</title>\r
- <screen>\r
- 127.0.1.2 public.localhost public\r
- 127.0.1.3 private.localhost private\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Change File Ownerships</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, change the ownership of files installed in the directory <filename class="directory">/openils</filename> to the <systemitem class="username">opensrf</systemitem> user:</para>\r
- <figure>\r
- <title>Commands to change file ownerships</title>\r
- <screen>\r
- $ chown -R opensrf:opensrf /openils\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, stop the <systemitem class="service">ejabberd</systemitem> service:</para>\r
- <figure>\r
- <title>Commands to stop the <systemitem class="service">ejabberd</systemitem> service</title>\r
- <screen>\r
- $ /etc/init.d/ejabberd stop\r
- </screen>\r
- </figure>\r
- <para>If <systemitem class="service">ejabberd</systemitem> reports that it is already stopped, it may have run into a problem starting back at the installation stage. One possible fix is to kill any remaining <systemitem class="daemon">beam</systemitem> and <systemitem class="daemon">epmd</systemitem> processes, then edit the configuration file <filename>/etc/ejabberd/ejabberd.cfg</filename> to hardcode a domain:</para>\r
- <figure>\r
- <title>Commands to recover from <systemitem class="service">ejabberd</systemitem> errors</title>\r
- <screen>\r
- $ su - root\r
- $ epmd -kill\r
- $ killall beam; killall beam.smp\r
- $ rm /var/lib/ejabberd/*\r
- $ echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
- <itemizedlist>\r
- <listitem>Change <literal>{hosts, ["localhost"]}.</literal> to <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal></listitem>\r
- <listitem>Change <literal>{max_user_sessions, 10}.</literal> to <literal>{max_user_sessions, 1000}.</literal> If you see something like this instead: <literal>{access, max_user_sessions, [{10, all}]}.</literal>, then change it to <literal>{access, max_user_sessions, [{1000, all}]}.</literal></listitem>\r
- <listitem>Change all three occurrences of <literal>max_stanza_size</literal> to <literal>2000000</literal>.</listitem>\r
- <listitem>Change both occurrences of <literal>maxrate</literal> to <literal>500000</literal>.</listitem>\r
- <listitem>Comment out the line <literal>{mod_offline, []}</literal> by placing two <literal>%</literal> comment signs in front.</listitem>\r
- </itemizedlist>\r
- </section>\r
- <section>\r
- <title>OpenSRF installation - (continued)</title>\r
- <para>\r
- <emphasis>The remainder of the OpenSRF installation procedure is identical to that for installing the latest version of OpenSRF. Continue with the instructions found in <xref linkend="serversideinstallation-opensrf-continued"/>.</emphasis>\r
- </para>\r
- </section>\r
- </section>\r
- </section>\r
- <section xml:id="serversideinstallation-postgresql">\r
- <title>Installing PostgreSQL</title>\r
- <para>In production Evergreen systems, the PostgreSQL database server may reside on the same system on which Evergreen is installed or on another standalone system so, by default, PostgreSQL is not automatically installed along with Evergreen. This section details the steps needed to manually install PostgreSQL on a <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem> system.</para>\r
- <para>If your PostgreSQL server will be on the same system as your Evergreen software, return to the previous section <xref linkend="serversideinstallation-postgresql-default"/> and follow those instructions. Otherwise, to manually install PostgreSQL on a system, continue with the instructions below.</para>\r
- <note>\r
- <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
- </note>\r
- <procedure>\r
- <step>\r
- <para>Install the application <application>"stow"</application> on your system if it is not already installed. Issue the following command as the <systemitem class="username">root</systemitem> user:</para>\r
- <figure>\r
- <title>Installing <application>"stow"</application></title>\r
- <screen>\r
- $ apt-get install stow\r
- ...\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Download, compile, and install the latest release for PostgreSQL 8.2 (which was version <literal>8.2.12</literal> at the time of this writing). As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Installing PostgreSQL</title>\r
- <screen>\r
- $ wget http://wwwmaster.postgresql.org/redir/198/h/source/v8.2.17/postgresql-8.2.17.tar.bz2\r
- $ tar xzf postgresql-8.2.17.tar.gz\r
- $ cd postgresql-8.2.17\r
- $ ./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
- ...\r
- $ make\r
- ...\r
- $ make install\r
- ...\r
- $ cd contrib\r
- $ make\r
- ...\r
- $ make install\r
- $ cd xml2\r
- $ make\r
- ...\r
- $ make install\r
- $ cd /usr/local/stow\r
- $ stow pgsql\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ adduser postgres\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ mkdir -p /usr/local/pgsql/data\r
- $ chown postgres /usr/local/pgsql/data\r
- $ su - postgres\r
- $ initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
- $ pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
- </screen>\r
- </figure>\r
- <note>\r
- <para>If an error occurs during the final step above, review the path of the home directory for the <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
- </note>\r
- </step>\r
- <step>\r
- <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values and some suggested updates for several useful parameters:</para>\r
- <table>\r
- <title>Suggested configuration values</title>\r
- <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="1.0*"/>\r
- <colspec colnum="3" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Parameter</entry>\r
- <entry>Default</entry>\r
- <entry>Suggested</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>default_statistics_target</entry>\r
- <entry>10</entry>\r
- <entry>100</entry>\r
- </row>\r
- <row>\r
- <entry>work_mem</entry>\r
- <entry>4Mb</entry>\r
- <entry>128Mb</entry>\r
- </row>\r
- <row>\r
- <entry>shared_buffers</entry>\r
- <entry>8Mb</entry>\r
- <entry>512Mb</entry>\r
- </row>\r
- <row>\r
- <entry>effective_cache_size</entry>\r
- <entry>128Mb</entry>\r
- <entry>4Gb</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS</secondary>\r
- </indexterm>\r
- <caution>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS </caution>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="serversideinstallation-apache">\r
- <title>Installing Apache</title>\r
- <section>\r
- <title>Securing Apache (httpd)</title>\r
- <para>The main consideration is to secure the directory <filename class="directory">cgi-bin</filename>. The only persons that need access to this directory are Evergreen system administrators. This directory should be restricted by both IP (to those workstations designated as Evergeen Administration systems), and by username/password.</para>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD CONTENT ON HOW TO RESTRICT APACHE BY IP AND USERNAME/PASSWORD </secondary>\r
- </indexterm>\r
- <caution>ADD CONTENT ON HOW TO RESTRICT APACHE BY IP AND USERNAME/PASSWORD </caution>\r
- <para>A user could add new libraries, re-arrange consortia, or change user groups; or a staff member could access the directory, and change his associated security group to administrative level privileges.</para>\r
- </section>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD MORE CONTENT FOR APACHE </secondary>\r
- </indexterm>\r
- <caution>ADD MORE CONTENT FOR APACHE </caution>\r
- </section>\r
- </chapter>\r
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>\r
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
- xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="installation-previousversions">\r
-\r
- <title>Installing Previous Versions of Evergreen</title>\r
- <para>Earlier releases of Evergreen are available. Instructions for installing, configuring and testing earlier versions are found below.</para>\r
- <para>The next most recent previous release of Evergreen is version <emphasis><emphasis role="bold">1.4.0.6</emphasis></emphasis>. The accompanying previous release of OpenSRF \r
- is version <emphasis><emphasis role="bold">1.0.7</emphasis></emphasis>.</para>\r
- <section xml:id="serversideinstallation-evergreen-previous">\r
- <title>Installing Evergreen 1.4.0.6 On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem></title>\r
- <para>This section outlines the installation process for the previous version 1.4.0.6 of Evergreen.</para>\r
- <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>\r
- <note>\r
- <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>\r
- <para>If you are starting with a clean install of <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>, you are strongly recommended <emphasis role="bold">not</emphasis> to install the packaged PostgreSQL server. This can confuse port numbers and system configuration. Evergreen 1.4 requires PostgreSQL 8.2.</para>\r
- </note>\r
- <section>\r
- <title>Installing OpenSRF 1.0.7</title>\r
- <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-previous"/>.</para>\r
- <para>Follow the steps outlined in that section and run the specified tests to ensure that OpenSRF is properly installed and configured. Do not continue with any further Evergreen installation steps until you have verified that OpenSRF has been successfully installed.</para>\r
- </section>\r
- <section>\r
- <title>Download and Unpack Evergreen Version 1.4.0.6</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the latest version of Evergreen. The latest version can be found here: <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz"></ulink></para>\r
- <figure>\r
- <title>Commands to download and unpack Evergreen</title>\r
- <screen>\r
- $ su - opensrf\r
- $ wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.4.0.6.tar.gz\r
- $ tar zxf Evergreen-ILS-1.4.0.6.tar.gz\r
- </screen>\r
- </figure>\r
- <para>The new directory <filename class="directory">/home/opensrf/Evergreen-ILS-1.4.0.6</filename> will be created.</para>\r
- </section>\r
- <section>\r
- <title>Install Prerequisites to Build Evergreen</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be used to build Evergreen. In a following step you will actually build the software using the <command>make</command> utility.</para>\r
- <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 example with the keyword corresponding to the actual <systemitem class="osname">Linux</systemitem> distribution listed in the <link linkend="serversideinstallation-keywords-figure-2-a">"Keywords"</link> figure below.</para>\r
- <figure>\r
- <title>Commands to install prerequisites for Evergreen</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ make -f Open-ILS/src/extras/Makefile.install [distribution]\r
- ...\r
- </screen>\r
- </figure>\r
- <table xml:id="serversideinstallation-keywords-figure-2-a">\r
- <title>Keywords Targets for <application>"make"</application> Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>debian-lenny</entry>\r
- <entry>for Debian Lenny (5.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-etch</entry>\r
- <entry>for Debian Etch (4.0)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-intrepid</entry>\r
- <entry>for Ubuntu Intrepid (8.10)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-hardy</entry>\r
- <entry>for Ubuntu Hardy (8.04)</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- </section>\r
- <section>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating the new file <filename>/etc/ld.so.conf.d/eg.conf</filename> containing two new library paths, then run the command <command>ldconfig</command> to automatically read the file and modify the system dynamic library path:</para>\r
- <figure>\r
- <title>Commands to modify system dynamic library path</title>\r
- <screen>\r
- $ su - root\r
- $ cat > /etc/ld.so.conf.d/eg.conf << ENDOFFILE\r
- /usr/local/lib\r
- /usr/local/lib/dbd\r
- ENDOFFILE\r
- $ ldconfig\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Restart the PostgreSQL Server</title>\r
- <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 the PostgreSQL server to avoid a problem where the library <filename>plperl.so</filename> cannot be found. If your PostgreSQL server is running on another system, just skip this step.</para>\r
- <figure>\r
- <title>Commands to restart PostgreSQL server</title>\r
- <screen>\r
- $ su - root\r
- $ /etc/init.d/postgresql-8.2 restart\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Configure Evergreen</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to the Evergreen build directory and use the <command>configure</command> utility to prepare for the next step of compiling and linking the software:</para>\r
- <figure>\r
- <title>Commands to configure Evergreen</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- $ make\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Compile, Link and Install Evergreen</title>\r
- <para>In this step you will actually compile, link and install Evergreen and the default Evergreen Staff Client.</para>\r
- <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. 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>\r
- <para>For further information on manually building the Staff Client, see <xref linkend="serversideinstallation-building-staffclient"/>.</para>\r
- <figure>\r
- <title>Commands to build, link and install Evergreen</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ make STAFF_CLIENT_BUILD_ID=rel_1_4_0_6 install\r
- ...\r
- </screen>\r
- <para>The above commands will create a new subdirectory <filename class="directory">/openils/var/web/xul/rel_1_4_0_6</filename> containing the Staff Client.</para>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Copy the OpenSRF Configuration Files</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, copy the example OpenSRF configuration files into place. This replaces the configuration files that you set up in a previous step when you installed and tested OpenSRF. You should also create backup copies of the old files for troubleshooting purposes. Finally, change the ownership on the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>\r
- <figure>\r
- <title>Commands to copy OpenSRF configuration files</title>\r
- <screen>\r
- $ su - root\r
- $ cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml\r
- $ cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml\r
- $ chown -R opensrf:opensrf /openils/\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Create and Configure PostgreSQL Database</title>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on your PostgreSQL server, create the Evergreen database.</para>\r
- <para>In the commands below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis> repository to match your PostgreSQL server layout. For example, if you built PostgreSQL from source the path would be <filename class="directory">/usr/local/share/contrib</filename>; if you installed the PostgreSQL 8.2 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>, the path would be <filename class="directory">/usr/share/postgresql/8.2/contrib/</filename>.</para>\r
- <procedure>\r
- <step>\r
- <para>\r
- <emphasis role="bold">Create and configure the database</emphasis>\r
- </para>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL system create the PostgreSQL database, then set some internal paths:</para>\r
- <figure>\r
- <title>Commands to create database and adjust the path</title>\r
- <screen>\r
- # create the database\r
- $ su - postgres\r
- $ createdb -E UNICODE evergreen\r
- $ createlang plperl evergreen\r
- $ createlang plperlu evergreen\r
- $ createlang plpgsql evergreen\r
- \r
- # adjust the paths\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen\r
- $ psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen\r
- </screen>\r
- </figure>\r
- <emphasis>Where <literal>PGSQL_VERSION</literal> is your installed PostgreSQL version (e.g. <literal>8.2</literal>).</emphasis>\r
- </step>\r
- <step>\r
- <para>\r
- <emphasis role="bold">Create new Evergreen superuser</emphasis>\r
- </para>\r
- <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL system, create the \r
- new database <systemitem class="username">evergreen</systemitem> user and assign a password:</para>\r
-<screen>\r
-# create superuser 'evergreen' and set the password\r
-<userinput>su - postgres</userinput>\r
-<userinput>createuser -P -s evergreen</userinput>\r
-<prompt>Enter password for new role:</prompt> <userinput>MYNEWPASSWORD</userinput>\r
-<prompt>Enter it again:</prompt><userinput>MYNEWPASSWORD</userinput>\r
-</screen>\r
- <emphasis>Where <literal>MYNEWPASSWORD</literal> is the password chosen.</emphasis>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section>\r
- <title>Create Database Schema</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, create the database schema and configure your system with the corresponding database authentication details for the <emphasis>evergreen</emphasis> database user that you created in the previous step.</para>\r
- <para>Enter the following commands and replace <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate values.</para>\r
- <figure>\r
- <title>Commands to create Evergreen database schema</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/Evergreen-ILS-1.4.0.6\r
- $ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
- --service all --create-schema --create-bootstrap --create-offline \\r
- --hostname HOSTNAME --port PORT \\r
- --user evergreen --password PASSWORD --database DATABASENAME\r
- </screen>\r
- </figure>\r
- <emphasis>Where, on most systems, <emphasis>HOSTNAME</emphasis> will be <emphasis role="bold">localhost</emphasis>, <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>, and <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> will be those assigned when PostgreSQL was installed in the previous step.</emphasis>\r
- <note>\r
- <para>\r
- <emphasis>If you are entering the above command on a single line, do not include the <literal>\</literal> (backslash) characters. If you are using the <command>bash</command> shell, these should only be used at the end of a line at a bash prompt to indicate that the command is continued on the next line.</emphasis>\r
- </para>\r
- </note>\r
- </section>\r
- <section>\r
- <title>Evergreen installation - (continued)</title>\r
- <para><emphasis>The remainder of the Evergreen installation procedure is identical to that for installing the latest version of Evergreen. Continue with the instructions found in</emphasis> <xref linkend="serversideinstallation-modify-apache"/>.</para>\r
- </section>\r
- </section>\r
- <section xml:id="serversideinstallation-opensrf-previous">\r
- <title>Installing OpenSRF 1.0.7 On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem></title>\r
- <para>This section describes the installation of the previous 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>\r
- <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is properly installed and configured. Do not continue with any further Evergreen installation steps until you have verified that OpenSRF has been successfully installed.</para>\r
- <note>\r
- <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) platforms. OpenSRF 1.0.7 has been tested on <systemitem class="osname">Debian Etch (4.0)</systemitem>, <systemitem class="osname">Debian Lenny</systemitem>, <systemitem class="osname">Ubuntu Hardy Heron (8.04)</systemitem>, and <systemitem class="osname">Ubuntu Intrepid Ibex (8.10)</systemitem>.</para>\r
- <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>\r
- <itemizedlist>\r
- <listitem><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.</listitem>\r
- <listitem><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.</listitem>\r
- </itemizedlist>\r
- <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>\r
- </note>\r
- <section>\r
- <title>Add the OpenSRF User</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, add the opensrf user to the system. The default shell for the new user is automatically set to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
- <figure>\r
- <title>Commands to add <systemitem class="username">opensrf</systemitem> user</title>\r
- <screen>\r
- $ su - opensrf\r
- $ useradd -m -s /bin/bash opensrf\r
- $ passwd opensrf\r
- Enter new UNIX password: ******\r
- Retype new UNIX password: ******\r
- passwd: password updated successfully\r
- $\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Download and Unpack Latest OpenSRF Version</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the latest version of OpenSRF. The latest version can be found here: <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.0.7.tar.gz"></ulink></para>\r
- <figure>\r
- <title>Commands to download and unpack OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ wget http://evergreen-ils.org/downloads/OpenSRF-1.0.7.tar.gz\r
- $ tar zxf OpenSRF-1.0.7.tar.gz\r
- </screen>\r
- </figure>\r
- <para>The new directory <filename class="directory">/home/opensrf/OpenSRF-1.0.7</filename> will be created.</para>\r
- </section>\r
- <section>\r
- <title>Install Prerequisites to Build OpenSRF</title>\r
- <para>In this section you will install and configure a set of prerequisites that will be used to build OpenSRF. In a following step you will actually build the software using the <command>make</command> utility.</para>\r
- <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 example with the keyword corresponding to the actual <systemitem class="osname">Linux</systemitem> distribution listed in the <link linkend="serversideinstallation-keywords-figure-1a">"Keywords"</link> figure below.</para>\r
- <figure>\r
- <title>Commands to install prerequisites for OpenSRF</title>\r
- <screen>\r
- $ su - root\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ make -f src/extras/Makefile.install [DISTRIBUTION]\r
- ...\r
- </screen>\r
- </figure>\r
- <table xml:id="serversideinstallation-keywords-figure-1a">\r
- <title>Keywords Targets for <application>"make"</application> Command</title>\r
- <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Keyword</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>debian-lenny</entry>\r
- <entry>for Debian Lenny (5.0)</entry>\r
- </row>\r
- <row>\r
- <entry>debian-etch</entry>\r
- <entry>for Debian Etch (4.0)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-intrepid</entry>\r
- <entry>for Intrepid (8.10)</entry>\r
- </row>\r
- <row>\r
- <entry>ubuntu-hardy</entry>\r
- <entry>for Ubuntu Hardy (8.04)</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <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>\r
- </section>\r
- <section>\r
- <title>Configure OpenSRF</title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, return to the OpenSRF build directory and use the <command>configure</command> utility to prepare for the next step of compiling and linking the software. You can include the <option>--enable-python</option> and <option>--enable-java</option> configuration options if you wish to include support for Python and Java, respectively:</para>\r
- <figure>\r
- <title>Commands to configure OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ ./configure --prefix=/openils --sysconfdir=/openils/conf\r
- $ make\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Compile, Link and Install OpenSRF</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, return to the OpenSRF build directory and use the <command>make</command> utility to compile, link and install OpenSRF:</para>\r
- <figure>\r
- <title>Commands to build, link and install OpenSRF</title>\r
- <screen>\r
- $ su - opensrf\r
- $ cd /home/opensrf/OpenSRF-1.0.7\r
- $ make install\r
- ...\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Update the System Dynamic Library Path</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. 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>\r
- <figure>\r
- <title>Commands to modify system dynamic library path</title>\r
- <screen>\r
- $ su - root\r
- $ echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf\r
- $ ldconfig\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Define Public and Private OpenSRF Domains</title>\r
- <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, 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. On a single-server system, the easiest way to define public and private domains is to define separate host names by adding entries to the file <filename>/etc/hosts</filename>.</para>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/hosts</filename> and add the following entries for our example domains:</para>\r
- <figure>\r
- <title>Example public and private domains in /etc/hosts</title>\r
- <screen>\r
- 127.0.1.2 public.localhost public\r
- 127.0.1.3 private.localhost private\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Change File Ownerships</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, change the ownership of files installed in the directory <filename class="directory">/openils</filename> to the <systemitem class="username">opensrf</systemitem> user:</para>\r
- <figure>\r
- <title>Commands to change file ownerships</title>\r
- <screen>\r
- $ chown -R opensrf:opensrf /openils\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, stop the <systemitem class="service">ejabberd</systemitem> service:</para>\r
- <figure>\r
- <title>Commands to stop the <systemitem class="service">ejabberd</systemitem> service</title>\r
- <screen>\r
- $ /etc/init.d/ejabberd stop\r
- </screen>\r
- </figure>\r
- <para>If <systemitem class="service">ejabberd</systemitem> reports that it is already stopped, it may have run into a problem starting back at the installation stage. One possible fix is to kill any remaining <systemitem class="daemon">beam</systemitem> and <systemitem class="daemon">epmd</systemitem> processes, then edit the configuration file <filename>/etc/ejabberd/ejabberd.cfg</filename> to hardcode a domain:</para>\r
- <figure>\r
- <title>Commands to recover from <systemitem class="service">ejabberd</systemitem> errors</title>\r
- <screen>\r
- $ su - root\r
- $ epmd -kill\r
- $ killall beam; killall beam.smp\r
- $ rm /var/lib/ejabberd/*\r
- $ echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd\r
- </screen>\r
- </figure>\r
- </section>\r
- <section>\r
- <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
- <para>As the <systemitem class="username">root</systemitem> user, edit the file <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
- <itemizedlist>\r
- <listitem>Change <literal>{hosts, ["localhost"]}.</literal> to <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal></listitem>\r
- <listitem>Change <literal>{max_user_sessions, 10}.</literal> to <literal>{max_user_sessions, 1000}.</literal> If you see something like this instead: <literal>{access, max_user_sessions, [{10, all}]}.</literal>, then change it to <literal>{access, max_user_sessions, [{1000, all}]}.</literal></listitem>\r
- <listitem>Change all three occurrences of <literal>max_stanza_size</literal> to <literal>2000000</literal>.</listitem>\r
- <listitem>Change both occurrences of <literal>maxrate</literal> to <literal>500000</literal>.</listitem>\r
- <listitem>Comment out the line <literal>{mod_offline, []}</literal> by placing two <literal>%</literal> comment signs in front.</listitem>\r
- </itemizedlist>\r
- </section>\r
- <section>\r
- <title>OpenSRF installation - (continued)</title>\r
- <para>\r
- <emphasis>The remainder of the OpenSRF installation procedure is identical to that for installing the latest version of OpenSRF. Continue with the instructions found in <xref linkend="serversideinstallation-opensrf-continued"/>.</emphasis>\r
- </para>\r
- </section>\r
- </section>\r
- </section>\r
- <section xml:id="serversideinstallation-postgresql">\r
- <title>Installing PostgreSQL</title>\r
- <para>In production Evergreen systems, the PostgreSQL database server may reside on the same system on which Evergreen is installed or on another standalone system so, by default, PostgreSQL is not automatically installed along with Evergreen. This section details the steps needed to manually install PostgreSQL on a <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem> system.</para>\r
- <para>If your PostgreSQL server will be on the same system as your Evergreen software, return to the previous section <xref linkend="serversideinstallation-postgresql-default"/> and follow those instructions. Otherwise, to manually install PostgreSQL on a system, continue with the instructions below.</para>\r
- <note>\r
- <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
- </note>\r
- <procedure>\r
- <step>\r
- <para>Install the application <application>"stow"</application> on your system if it is not already installed. Issue the following command as the <systemitem class="username">root</systemitem> user:</para>\r
- <figure>\r
- <title>Installing <application>"stow"</application></title>\r
- <screen>\r
- $ apt-get install stow\r
- ...\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Download, compile, and install the latest release for PostgreSQL 8.2 (which was version <literal>8.2.12</literal> at the time of this writing). As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Installing PostgreSQL</title>\r
- <screen>\r
- $ wget http://wwwmaster.postgresql.org/redir/198/h/source/v8.2.17/postgresql-8.2.17.tar.bz2\r
- $ tar xzf postgresql-8.2.17.tar.gz\r
- $ cd postgresql-8.2.17\r
- $ ./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
- ...\r
- $ make\r
- ...\r
- $ make install\r
- ...\r
- $ cd contrib\r
- $ make\r
- ...\r
- $ make install\r
- $ cd xml2\r
- $ make\r
- ...\r
- $ make install\r
- $ cd /usr/local/stow\r
- $ stow pgsql\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ adduser postgres\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ mkdir -p /usr/local/pgsql/data\r
- $ chown postgres /usr/local/pgsql/data\r
- $ su - postgres\r
- $ initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
- $ pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
- </screen>\r
- </figure>\r
- <note>\r
- <para>If an error occurs during the final step above, review the path of the home directory for the <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
- </note>\r
- </step>\r
- <step>\r
- <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values and some suggested updates for several useful parameters:</para>\r
- <table>\r
- <title>Suggested configuration values</title>\r
- <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="1.0*"/>\r
- <colspec colnum="3" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Parameter</entry>\r
- <entry>Default</entry>\r
- <entry>Suggested</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>default_statistics_target</entry>\r
- <entry>10</entry>\r
- <entry>100</entry>\r
- </row>\r
- <row>\r
- <entry>work_mem</entry>\r
- <entry>4Mb</entry>\r
- <entry>128Mb</entry>\r
- </row>\r
- <row>\r
- <entry>shared_buffers</entry>\r
- <entry>8Mb</entry>\r
- <entry>512Mb</entry>\r
- </row>\r
- <row>\r
- <entry>effective_cache_size</entry>\r
- <entry>128Mb</entry>\r
- <entry>4Gb</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS</secondary>\r
- </indexterm>\r
- <caution>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS </caution>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="serversideinstallation-apache">\r
- <title>Installing Apache</title>\r
- <section>\r
- <title>Securing Apache (httpd)</title>\r
- <para>The main consideration is to secure the directory <filename class="directory">cgi-bin</filename>. The only persons that need access to this directory are Evergreen system administrators. This directory should be restricted by both IP (to those workstations designated as Evergeen Administration systems), and by username/password.</para>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD CONTENT ON HOW TO RESTRICT APACHE BY IP AND USERNAME/PASSWORD </secondary>\r
- </indexterm>\r
- <caution>ADD CONTENT ON HOW TO RESTRICT APACHE BY IP AND USERNAME/PASSWORD </caution>\r
- <para>A user could add new libraries, re-arrange consortia, or change user groups; or a staff member could access the directory, and change his associated security group to administrative level privileges.</para>\r
- </section>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD MORE CONTENT FOR APACHE </secondary>\r
- </indexterm>\r
- <caution>ADD MORE CONTENT FOR APACHE </caution>\r
- </section>\r
- </chapter>\r
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>\r
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
- xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serversideinstallation-postgresql">\r
- <title>Installing PostgreSQL</title>\r
- <para>In production Evergreen systems, the PostgreSQL database server may reside on the same system on which Evergreen is installed or on another standalone system so, by default, PostgreSQL is not automatically installed along with Evergreen. This section details the steps needed to manually install PostgreSQL on a <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem> system.</para>\r
- <para>If your PostgreSQL server will be on the same system as your Evergreen software, return to the previous section <xref linkend="serversideinstallation-postgresql-default"/> and follow those instructions. Otherwise, to manually install PostgreSQL on a system, continue with the instructions below.</para>\r
- <note>\r
- <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
- </note>\r
- <procedure>\r
- <step>\r
- <para>Install the application <application>"stow"</application> on your system if it is not already installed. Issue the following command as the <systemitem class="username">root</systemitem> user:</para>\r
- <figure>\r
- <title>Installing <application>"stow"</application></title>\r
- <screen>\r
- $ apt-get install stow\r
- ...\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Download, compile, and install the latest release for PostgreSQL 8.2 (which was version <literal>8.2.12</literal> at the time of this writing). As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Installing PostgreSQL</title>\r
- <screen>\r
- $ wget http://wwwmaster.postgresql.org/redir/198/h/source/v8.2.17/postgresql-8.2.17.tar.bz2\r
- $ tar xzf postgresql-8.2.17.tar.gz\r
- $ cd postgresql-8.2.17\r
- $ ./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
- ...\r
- $ make\r
- ...\r
- $ make install\r
- ...\r
- $ cd contrib\r
- $ make\r
- ...\r
- $ make install\r
- $ cd xml2\r
- $ make\r
- ...\r
- $ make install\r
- $ cd /usr/local/stow\r
- $ stow pgsql\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ adduser postgres\r
- </screen>\r
- </figure>\r
- </step>\r
- <step>\r
- <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- <figure>\r
- <title>Adding <systemitem class="username">postgres</systemitem></title>\r
- <screen>\r
- $ mkdir -p /usr/local/pgsql/data\r
- $ chown postgres /usr/local/pgsql/data\r
- $ su - postgres\r
- $ initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
- $ pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
- </screen>\r
- </figure>\r
- <note>\r
- <para>If an error occurs during the final step above, review the path of the home directory for the <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
- </note>\r
- </step>\r
- <step>\r
- <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values and some suggested updates for several useful parameters:</para>\r
- <table>\r
- <title>Suggested configuration values</title>\r
- <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="1.0*"/>\r
- <colspec colnum="3" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Parameter</entry>\r
- <entry>Default</entry>\r
- <entry>Suggested</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>default_statistics_target</entry>\r
- <entry>10</entry>\r
- <entry>100</entry>\r
- </row>\r
- <row>\r
- <entry>work_mem</entry>\r
- <entry>4Mb</entry>\r
- <entry>128Mb</entry>\r
- </row>\r
- <row>\r
- <entry>shared_buffers</entry>\r
- <entry>8Mb</entry>\r
- <entry>512Mb</entry>\r
- </row>\r
- <row>\r
- <entry>effective_cache_size</entry>\r
- <entry>128Mb</entry>\r
- <entry>4Gb</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- <indexterm>\r
- <primary>ZZZ-REVIEW</primary>\r
- <secondary>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS</secondary>\r
- </indexterm>\r
- <caution>ADD CONTENT ON HOW TO UPDATE POSTRESQL PARAMETERS </caution>\r
- </step>\r
- </procedure>\r
-</chapter>\r
+++ /dev/null
-<?xml version="1.0" encoding="utf-8"?>\r
-<chapter xml:id="actiontriggers" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
- <info>\r
- <title>Action Triggers</title> \r
- </info>\r
- <para>Action Triggers were introduced to Evergreen in 1.6. They allow administrators the ability to set up actions for specific events. They are useful for notification events such as \r
- hold notifications.</para>\r
- \r
- \r
- <para>To access the Action Triggers module, select\r
- <menuchoice>\r
- <guimenu>Admin</guimenu> \r
- <guisubmenu>Local Administration</guisubmenu>\r
- <guisubmenu>Notifications / Action triggers</guisubmenu>\r
- </menuchoice>\r
- </para>\r
- <note><para>You must have Local Administrator permissions to access the Action Triggers module.</para></note>\r
- <para>You will notice four tabs on this page: <guilabel><link linkend="eventdefinitions">Event Definitions</link></guilabel>, <guilabel><link linkend="Hooks">Hooks</link></guilabel>, \r
- <guilabel><link linkend="Reactors">Reactors</link></guilabel> and <guilabel><link linkend="Validators">Validators</link></guilabel>.</para>\r
- \r
- <section xml:id="eventdefinitions">\r
- <title>Event Definitions</title>\r
- <para><guilabel>Event Definitions</guilabel> is the main tab and contains the key fields when working with action triggers. These fields include:</para>\r
- <table xml:id="eventdefinitionstable">\r
- <title>Action Trigger Event Definitions</title>\r
- <tgroup cols="2">\r
- <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
- <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Field</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry><guilabel>Owning library</guilabel></entry>\r
- <entry>The shortname of the library for which the action / trigger / hook is defined.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Name</guilabel></entry>\r
- <entry>The name of the trigger event, that links to a trigger event environment containing a set of fields \r
- that will be returned to the <link linkend="Validators">Validators</link> / <link linkend="Reactors">Reactors</link> for processing.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel><link linkend="Hooks">Hooks</link></guilabel></entry>\r
- <entry>The name of the trigger for the trigger event. The underlying action_trigger.hook table defines the Fieldmapper \r
- class in the core_type column off of which the rest of the field definitions <quote>hang</quote>. </entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Enabled</guilabel></entry>\r
- <entry>Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Processing Delay</guilabel></entry>\r
- <entry>Defines how long after a given trigger / hook event has occurred before the associated action (<quote>Reactor</quote>) \r
- will be taken.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Processing Delay Field</guilabel></entry>\r
- <entry>Defines the field associated with the event on which the processing delay is calculated. For example, the processing delay \r
- context field on the hold.capture hook (which has a core_type of ahr) is <emphasis>capture_time</emphasis>.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Processing Group Context Field</guilabel></entry>\r
- <entry>Used to batch actions based on its associated group.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel><link linkend="Validators">Validators</link></guilabel></entry>\r
- <entry>The subroutines receive the trigger environment as an argument (see the linked <emphasis>Name</emphasis> for \r
- the environment definition) and returns either <emphasis>1</emphasis> if the validator is <emphasis>true</emphasis> or <emphasis>0</emphasis> \r
- if the validator returns <emphasis>false</emphasis>.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel><link linkend="Reactors">Reactors</link></guilabel></entry>\r
- <entry>Links the action trigger to the Reactor.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Max Event Validity Delay</guilabel></entry>\r
- <entry>Define the threshold for how far back the action_trigger_runner.pl script should reach to generate \r
- a batch of events.</entry>\r
- </row>\r
- </tbody> \r
- </tgroup>\r
- </table>\r
- \r
- <procedure>\r
- <title>Creating New Action Triggers</title>\r
- <step>\r
- <para>From the top menu, select\r
- <menuchoice>\r
- <guimenu>Admin</guimenu> \r
- <guisubmenu>Local Administration</guisubmenu>\r
- <guisubmenu>Notifications / Action triggers</guisubmenu>\r
- </menuchoice>\r
- </para>\r
- </step>\r
- <step><para>Click on the <guibutton>New</guibutton> button.</para></step>\r
- <step><para>Select an <guilabel>Owning Library</guilabel>.</para></step>\r
- <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step> \r
- <step><para>Select the <guilabel>Hook</guilabel>.</para></step>\r
- <step><para>Check the <guilabel>Enabled</guilabel> check box.</para></step>\r
- \r
- <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step>\r
- <step><para>Set the <guilabel>Processing Delay</guilabel> in the appropriate format. Eg. <emphasis class="bold">7 days</emphasis> to run 7 days from the trigger event \r
- or <emphasis class="bold">00:01:00</emphasis> to run 1 hour after the <guilabel>Processing Delay Context Field</guilabel>.</para></step>\r
- <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step> \r
- <step><para>Select the <guilabel>Validator</guilabel>, <guilabel>Reactor</guilabel>, <guilabel>Failure Cleanup</guilabel> and <guilabel>Success Cleanup</guilabel>.\r
- </para></step> \r
- <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step> \r
- <step preformance="optional"><para>Enter text in the <guilabel>Template</guilabel> text box if required. These are for email messages. Here is an sample \r
- template for sending 90 day overdue notices:</para>\r
-<programlisting><![CDATA[\r
-[%- USE date -%]\r
-[%- user = target.0.usr -%]\r
-To: robert.soulliere@mohawkcollege.ca\r
-From: robert.soulliere@mohawkcollege.ca\r
-Subject: Overdue Notification\r
-\r
-Dear [% user.family_name %], [% user.first_given_name %]\r
-Our records indicate the following items are overdue.\r
-\r
-[%- USE date -%]\r
-[%- user = target.0.usr -%]\r
-To: robert.soulliere@mohawkcollege.ca\r
-From: robert.soulliere@mohawkcollege.ca\r
-Subject: Overdue Items Marked Lost\r
-\r
-Dear [% user.family_name %], [% user.first_given_name %]\r
-The following items are 90 days overdue and have been marked LOST.\r
-[%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]\r
-[% FOR circ IN target %]\r
- Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
- Barcode: [% circ.target_copy.barcode %] \r
- Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
- Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
- Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
- Library: [% circ.circ_lib.name %]\r
-[% END %]\r
-\r
-\r
-[% FOR circ IN target %]\r
- Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
- Barcode: [% circ.target_copy.barcode %] \r
- Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
- Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
- Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
- Library: [% circ.circ_lib.name %]\r
-[% END %]\r
-]]>\r
-</programlisting> \r
- </step> \r
- <step><para>Once you are satisfied with your new event trigger , click the <guibutton>Save</guibutton> button located at the bottom of the \r
- form</para></step>\r
- </procedure>\r
- <tip><para>A quick and easy way to create new action triggers is to clone an existing action trigger.</para></tip>\r
- <procedure>\r
- <title>Cloning Existing Action Triggers</title>\r
- <step>\r
- <para>Check the check box next to the action trigger you wish to clone</para>\r
- </step>\r
- <step>\r
- <para>Click the <guibutton>Clone Selected</guibutton> on the top left of the page.</para>\r
- </step>\r
- <step>\r
- <para>An editing window with open. Notice that the fields will be populated with content from the cloned action trigger. Edit as necessary and \r
- give the new action trigger a unique <guilabel>Name</guilabel>.</para>\r
- </step>\r
- <step>\r
- <para>Click <guilabel>Save</guilabel>.</para>\r
- </step>\r
- </procedure>\r
- <procedure>\r
- <title>Editing Action Triggers</title>\r
- <step>\r
- <para>Check the check box next to the action trigger you wish to delete</para>\r
- </step>\r
- <step>\r
- <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
- </step>\r
- </procedure>\r
- \r
- <note><para>Before deleting an action trigger, you should consider disabling it through the editing form. This way you can simply enable it if you decide that you would like to use \r
- the action trigger in the future.</para></note>\r
- <procedure>\r
- <title>Deleting Action Triggers</title>\r
- <step>\r
- <para>Check the check box next to the action trigger you wish to delete</para>\r
- </step>\r
- <step>\r
- <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="Hooks">\r
- <title>Hooks</title>\r
- <para><guilabel>Hooks</guilabel> define the Fieldmapper class in the core_type column off of which the rest of the field definitions <quote>hang</quote>.</para>\r
- <table xml:id="Hookstable">\r
- <title>Hooks</title>\r
- <tgroup cols="2">\r
- <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
- <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Field</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry><guilabel>Hook Key</guilabel></entry>\r
- <entry>A unique name given to the hook.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Core Type</guilabel></entry>\r
- <entry>Used to link the action trigger to the IDL class in fm_IDL.xml</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Description</guilabel></entry>\r
- <entry>Text to describe the purpose of the hook. </entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Passive</guilabel></entry>\r
- <entry>Indicates whether or not an event is created by direct user action or is circumstantial.</entry>\r
- </row>\r
- </tbody> \r
- </tgroup>\r
- </table>\r
- <para>You may also create, edit and delete Hooks but the <guilabel>Core Type</guilabel> must refer to an IDL class in the fm_IDL.xml file.</para>\r
- </section> \r
- <section xml:id="Reactors">\r
- <title>Reactors</title>\r
- <para><guilabel>Reactors</guilabel> link the trigger definition to the action to be carried out.</para>\r
- <table xml:id="Reactorstable">\r
- <title>Action Trigger Reactors</title>\r
- <tgroup cols="2">\r
- <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
- <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Field</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry><guilabel>Module Name</guilabel></entry>\r
- <entry>The name of the Module to run if the action trigger is validated. It must be defined as a subroutine in \r
- <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> or as a module\r
- in <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm</filename>.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Description</guilabel></entry>\r
- <entry>Description of the Action to be carried out.</entry>\r
- </row>\r
- </tbody> \r
- </tgroup>\r
- </table>\r
- <para>You may also create, edit and delete Reactors. Just remember that their must be an associated subroutine or module in the Reactor Perl module.</para>\r
- </section> \r
- <section xml:id="Validators">\r
- <title>Validators</title>\r
- <para><guilabel>Validators</guilabel> set the validation test to be preformed to determine whether the action trigger is executed.</para>\r
- <table xml:id="Validatorstable">\r
- <title>Action Trigger Validators</title>\r
- \r
- <tgroup cols="2">\r
- <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
- <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Field</entry>\r
- <entry>Description</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry><guilabel>Module Name</guilabel></entry>\r
- <entry>The name of the subroutine in \r
- <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> to validate the action trigger.</entry>\r
- </row>\r
- <row>\r
- <entry><guilabel>Description</guilabel></entry>\r
- <entry>Description of validation test to run.</entry>\r
- </row>\r
- </tbody> \r
- </tgroup>\r
- </table>\r
- <para>You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the <filename>Reactor.pm</filename> Perl module.</para>\r
- </section> \r
- <section xml:id="ProcessingActionTriggers"> \r
- <title>Processing Action Triggers</title>\r
- <para>To run the action triggers, an Evergreen administrator will need to run the trigger processing script <command>/openils/bin/action_trigger_runner.pl \r
- <option>--process-hooks</option> <option>--run-pending</option></command>. This should be set up as a cron job to run \r
- periodically.</para> \r
- <para>You have several options when running the script:</para>\r
- <itemizedlist>\r
- <listitem><option>--run-pending</option>: Run the pending events.</listitem>\r
- <listitem><option>--process-hooks</option>: Create hook events</listitem>\r
- <listitem><option>--osrf-config=[<varname>config_file</varname>]</option>: OpenSRF core config file. Defaults to: \r
- <filename>/openils/conf/opensrf_core.xml</filename>.</listitem>\r
- <listitem><option>--custom-filters=[<varname>filter_file</varname>]</option>: File containing a JSON Object which describes any hooks that should\r
- use a user-defined filter to find their target objects. Defaults to: <filename>/openils/conf/action_trigger_filters.json</filename></listitem>\r
- <listitem><option>--max-sleep=[<varname>seconds</varname>]</option>: When in process-hooks mode, wait up to [<varname>seconds</varname>] for the lock file to go away. \r
- Defaults to 3600 (1 hour).</listitem>\r
- <listitem><option>--hooks=hook1[,hook2,hook3,...]</option>: Define which hooks to create events for. If none are defined, it defaults to the list of hooks defined \r
- in the <option>--custom-filters</option> option.</listitem>\r
- <listitem><option>--debug-stdout</option>: Print server responses to stdout (as JSON) for debugging.</listitem>\r
- <listitem><option>--lock-file=[<varname>file_name</varname>]</option>: Sets the lock file for the process.</listitem>\r
- <listitem><option>--help</option>: Show help information.</listitem>\r
- </itemizedlist>\r
- </section> \r
-</chapter>\r
-\r
projects / contrib / Conifer.git / commitdiff