2.0/admin/serversideinstallation_2.0.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <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">
   3         <info>
   4                 <title>Server-side Installation of Evergreen Software</title>
   5                 <abstract>
   6                         <para>This section describes installation of the Evergreen server-side software and
   7                         its associated components.  Installation, configuration, testing and verification of
   8                         the software is straightforward if you follow some simple directions.</para>
   9                 </abstract>
  10         </info>
  11         <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
  12         stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
  13         installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
  14         system.</para>
  15         <para>The current version of the Evergreen server-side software runs as a native application on any of several
  16         well-known <systemitem class="osname">Linux</systemitem> distributions
  17         (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
  18         It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
  19         operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
  20         Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
  21         installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
  22         <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
  23         <application>"VirtualBox"</application> or <application>"VMware"</application>
  24         to emulate a <systemitem class="osname">Linux</systemitem>
  25         environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
  26         systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
  27         <application>"VMware"</application>). More information on virtualized environments can be found in
  28         <xref linkend="serversideinstallation-virtual"/>.</para>
  29         <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
  30         <para>The Evergreen server-side software has dependencies on particular versions of certain major software
  31         sub-components. Successful installation of Evergreen software requires that software versions agree with those
  32         listed here:</para>
  33         <table xml:id="serversideinstall-software-dependencies">
  34                 <?dbfo keep-together="always" ?>
  35                 <title>Evergreen Software Dependencies</title>
  36                 <indexterm>
  37                         <primary>Evergreen software dependencies</primary>
  38                 </indexterm>
  39                 <tgroup align="left" cols="3" colsep="1" rowsep="1">
  40                         <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
  41                         <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
  42                         <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
  43                         <thead>
  44                                 <row>
  45                                         <entry>Evergreen</entry>
  46                                         <entry>OpenSRF</entry>
  47                                         <entry>PostgreSQL</entry>
  48                                 </row>
  49                         </thead>
  50                         <tbody>
  51                                 <row>
  52                                         <entry>2.0</entry>
  53                                         <entry>1.6.3</entry>
  54                                         <entry>8.4</entry>
  55                                 </row>
  56                                 <row>
  57                                         <entry>1.6.1.x</entry>
  58                                         <entry>1.4.0</entry>
  59                                         <entry>8.2 / 8.3</entry>
  60                                 </row>
  61                                 <row>
  62                                         <entry>1.6.0.x</entry>
  63                                         <entry>1.2</entry>
  64                                         <entry>8.2 / 8.3</entry>
  65                                 </row>
  66                                 <row>
  67                                         <entry>1.4.x</entry>
  68                                         <entry>1.0</entry>
  69                                         <entry>8.1 / 8.2</entry>
  70                                 </row>
  71                                 <row>
  72                                         <entry>1.2.x</entry>
  73                                         <entry>0.9</entry>
  74                                         <entry>8.1 / 8.2</entry>
  75                                 </row>
  76                         </tbody>
  77                 </tgroup>
  78         </table>
  79         <section xml:id="serversideinstallation-all">
  80                 <title>Installing Server-Side Software</title>
  81                 <para>This section describes the installation of the major components of Evergreen server-side software.</para>
  82                 <para>As far as possible, you should perform the following steps in the exact order given since the
  83                 success of many steps relies on the successful completion of earlier steps. You should make backup
  84                 copies of files and environments when you are instructed to do so. In the event of installation problems
  85                 those copies can allow you to back out of a step gracefully and resume the installation from a known
  86                 state. See <xref linkend="backingup"/> for further information.</para>
  87                 <para>Of course, after you successfully complete and test the entire Evergreen installation you should
  88                 take a final snapshot backup of your system(s). This can be the first in the series of regularly
  89                 scheduled system backups that you should probably also begin.</para>
  90                 <section xml:id="serversideinstallation-opensrf-1.6.3">
  91                         <indexterm>
  92                                 <primary>OpenSRF</primary>
  93                                 <secondary>installation</secondary>
  94                         </indexterm>
  95                         <title>Installing OpenSRF 1.6.x On <systemitem class="osname">Ubuntu</systemitem> or
  96                                 <systemitem class="osname">Debian</systemitem></title>
  97                         <indexterm>
  98                                 <primary>Linux</primary>
  99                                 <secondary>Debian</secondary>
 100                         </indexterm>
 101                         <indexterm>
 102                                 <primary>Linux</primary>
 103                                 <secondary>Ubuntu</secondary>
 104                         </indexterm>
 105                         <para>This section describes the installation of the latest version of the Open Service Request
 106                         Framework (OpenSRF), a major component of the Evergreen server-side software, on
 107                         <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
 108                         systems. Evergreen software is integrated with and depends on the OpenSRF software
 109                         system.</para>
 110                         <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
 111                         properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
 112                         continue with any further Evergreen installation steps
 113                         until you have verified that OpenSRF has been successfully installed and tested.</para>
 114                         <note>
 115                                 <para>The following steps have been tested on the x86 (32-bit) architecture of
 116                                 <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
 117                                 <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
 118                                 <systemitem class="osname">Fedora 13</systemitem> and
 119                                 <systemitem class="osname">Fedora 14</systemitem>.</para>
 120                                 <para>In the following instructions, you are asked to perform certain steps as
 121                                 either the <systemitem class="username">root</systemitem> user, the
 122                                 <systemitem class="username">opensrf</systemitem> user, or the
 123                                 <systemitem class="username">postgres</systemitem> user.</para>
 124                                 <itemizedlist>
 125                                         <listitem>
 126                                                 <para><systemitem class="osname">Debian</systemitem> -- To become the
 127                                                 <systemitem class="username">root</systemitem> user, issue the command
 128                                                 <command>su -</command> and enter the password of the
 129                                                 <systemitem class="username">root</systemitem> user.</para>
 130                                         </listitem>
 131                                         <listitem>
 132                                                 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
 133                                                 <systemitem class="username">root</systemitem> user, issue the command
 134                                                 <command>sudo su -</command> and enter the password of the
 135                                                 <systemitem class="username">root</systemitem> user.</para>
 136                                         </listitem>
 137                                 </itemizedlist>
 138                                 <para>To switch from the <systemitem class="username">root</systemitem> user to a
 139                                 different user, issue the command <command>su - USERNAME</command>. For example, to
 140                                 switch from the <systemitem class="username">root</systemitem> user to the
 141                                 <systemitem class="username">opensrf</systemitem> user, issue the command
 142                                 <command>su - opensrf</command>. Once you have become a non-root user, to become
 143                                 the <systemitem class="username">root</systemitem> user again, simply issue the command
 144                                 <command>exit</command>.</para>
 145                         </note>
 146                         <procedure>
 147                                 <step>
 148                                         <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
 149                                         <para>As the <systemitem class="username">root</systemitem> user, add the
 150                                         <systemitem class="username">opensrf</systemitem> user to the system.
 151                                         In the following example, the default shell for the
 152                                         <systemitem class="username">opensrf</systemitem> user is automatically set
 153                                         to <command>/bin/bash</command> to inherit a reasonable environment:</para>
 154                                         <screen>
 155                                                 <userinput>
 156         # as the root user:
 157         useradd -m -s /bin/bash opensrf
 158         passwd opensrf</userinput>
 159                                         </screen>
 160                                 </step>
 161                                 <step>
 162                                         <title>Download and Unpack Latest OpenSRF Version</title>
 163                                         <indexterm>
 164                                                 <primary>OpenSRF</primary>
 165                                                 <secondary>download</secondary>
 166                                         </indexterm>
 167                                         <para>The latest version of OpenSRF can be found here:
 168                                         <ulink url="http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz"></ulink> .
 169                                         As the <systemitem class="username">opensrf</systemitem> user, change to
 170                                         the directory <filename class="directory">/home/opensrf</filename> then download
 171                                         and extract OpenSRF. The new subdirectory
 172                                         <filename class="directory">/home/opensrf/opensrf-1.6.3</filename> will be created:</para>
 173                                         <screen>
 174                                                 <userinput>
 175         # as the opensrf user:
 176         cd /home/opensrf
 177         wget http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz
 178         tar zxf opensrf-1.6.3.tar.gz</userinput>
 179                                         </screen>
 180                                 </step>
 181                                 <step>
 182                                         <title>Install Prerequisites to Build OpenSRF</title>
 183                                         <para>In this section you will install and configure a set of prerequisites that will be
 184                                         used to build OpenSRF. In a following step you will actually build the OpenSRF software
 185                                         using the <command>make</command> utility.</para>
 186                                         <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
 187                                         below to build the prerequisites from the software distribution that you just downloaded
 188                                         and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
 189                                         example with the keyword corresponding to the name of one of the
 190                                         <systemitem class="osname">Linux</systemitem> distributions listed in the
 191                                         distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
 192                                         For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
 193                                         enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
 194                                         <screen>
 195                                                 <userinput>
 196         # as the root user:
 197         cd /home/opensrf/opensrf-1.6.3
 198         make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
 199                                         </screen>
 200                                         <table xml:id="serversideinstallation-keywords-opensrf">
 201                                                 <?dbfo keep-together="always" ?>
 202                                                 <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
 203                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">
 204                                                         <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
 205                                                         <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
 206                                                         <thead>
 207                                                                 <row>
 208                                                                         <entry>Keyword</entry>
 209                                                                         <entry>Linux Version</entry>
 210                                                                 </row>
 211                                                         </thead>
 212                                                         <tbody>
 213                                                                 <row>
 214                                                                         <entry>debian-squeeze</entry>
 215                                                                         <entry>Debian "Squeeze" (6.0)</entry>
 216                                                                 </row>
 217                                                                 <row>
 218                                                                         <entry>debian-etch</entry>
 219                                                                         <entry>Debian "Etch" (4.0)</entry>
 220                                                                 </row>
 221                                                                 <row>
 222                                                                         <entry>debian-lenny</entry>
 223                                                                         <entry>Debian "Lenny" (5.0)</entry>
 224                                                                 </row>
 225                                                                 <row>
 226                                                                         <entry>ubuntu-hardy</entry>
 227                                                                         <entry>Ubuntu "Hardy Heron" (8.04)</entry>
 228                                                                 </row>
 229                                                                 <row>
 230                                                                         <entry>ubuntu-karmic</entry>
 231                                                                         <entry>Ubuntu "Karmic Koala" (9.10)</entry>
 232                                                                 </row>
 233                                                                 <row>
 234                                                                         <entry>ubuntu-lucid</entry>
 235                                                                         <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
 236                                                                 </row>
 237                                                                 <row>
 238                                                                         <entry>fedora13</entry>
 239                                                                         <entry>Fedora "Goddard" (13)</entry>
 240                                                                 </row>
 241                                                                 <row>
 242                                                                         <entry>fedora13</entry>
 243                                                                         <entry>Fedora "Laughlin" (14)</entry>
 244                                                                 </row>
 245                                                                 <row>
 246                                                                         <entry>centos</entry>
 247                                                                         <entry>CentOS 5</entry>
 248                                                                 </row>
 249                                                                 <row>
 250                                                                         <entry>rhel</entry>
 251                                                                         <entry>Red Hat Enterprise Linux 5</entry>
 252                                                                 </row>
 253                                                                 <row>
 254                                                                         <entry>gentoo</entry>
 255                                                                         <entry>Gentoo</entry>
 256                                                                 </row>
 257                                                         </tbody>
 258                                                 </tgroup>
 259                                         </table>
 260                                         <indexterm>
 261                                                 <primary>Linux</primary>
 262                                                 <secondary>Debian</secondary>
 263                                         </indexterm>
 264                                         <indexterm>
 265                                                 <primary>Linux</primary>
 266                                                 <secondary>Fedora</secondary>
 267                                         </indexterm>
 268                                         <indexterm>
 269                                                 <primary>Linux</primary>
 270                                                 <secondary>Ubuntu</secondary>
 271                                         </indexterm>
 272                                         <indexterm>
 273                                                 <primary>Linux</primary>
 274                                                 <secondary>CentOS</secondary>
 275                                         </indexterm>
 276                                         <indexterm>
 277                                                 <primary>Linux</primary>
 278                                                 <secondary>Red Hat</secondary>
 279                                         </indexterm>
 280                                         <indexterm>
 281                                                 <primary>Linux</primary>
 282                                                 <secondary>Gentoo</secondary>
 283                                         </indexterm>
 284                                         <para>This will install a number of packages on the system that are required by OpenSRF,
 285                                         including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
 286                                         CPAN configuration prompt to allow it to automatically configure itself to download and
 287                                         install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
 288                                         it should install prerequisite modules - say <literal>Yes</literal>.</para>
 289                                 </step>
 290                                 <step>
 291                                         <title>Build OpenSRF</title>
 292                                         <para>In this section you will configure, build and install the OpenSRF
 293                                         components that support other Evergreen services.</para>
 294                                         <substeps>
 295                                                 <step>
 296                                                         <title>Configure OpenSRF</title>
 297                                                         <indexterm>
 298                                                                 <primary>OpenSRF</primary>
 299                                                                 <secondary>configure</secondary>
 300                                                         </indexterm>
 301                                                         <para>As the <systemitem class="username">opensrf</systemitem>
 302                                                         user, return to the new OpenSRF build directory and use the
 303                                                         <command>configure</command> utility to prepare for the next
 304                                                         step of compiling and linking the software. If you wish to
 305                                                         include support for Python and Java, add the configuration
 306                                                         options <option>--enable-python</option> and
 307                                                         <option>--enable-java</option>, respectively:</para>
 308                                                         <screen>
 309                                                                 <userinput>
 310         # as the opensrf user:
 311         cd /home/opensrf/opensrf-1.6.3
 312         ./configure --prefix=/openils --sysconfdir=/openils/conf
 313         make</userinput>
 314                                                         </screen>
 315                                                         <para>This step will take several minutes to complete.</para>
 316                                                 </step>
 317                                                 <step>
 318                                                         <title>Compile, Link and Install OpenSRF</title>
 319                                                         <para>As the <systemitem class="username">root</systemitem>
 320                                                         user, return to the new OpenSRF build directory and use the
 321                                                         <command>make</command> utility to compile, link and install
 322                                                         OpenSRF:</para>
 323                                                         <screen>
 324                                                                 <userinput>
 325         # as the root user:
 326         cd /home/opensrf/opensrf-1.6.3
 327         make install</userinput>
 328                                                         </screen>
 329                                                         <para>This step will take several minutes to complete.</para>
 330                                                 </step>
 331                                                 <step>
 332                                                         <title>Update the System Dynamic Library Path</title>
 333                                                         <para>You must update the system dynamic library path to force
 334                                                         your system to recognize the newly installed libraries. As the
 335                                                         <systemitem class="username">root</systemitem> user, do this by
 336                                                         creating the new file
 337                                                         <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing two
 338                                                         new library paths, then execute the command
 339                                                         <command>ldconfig</command> to automatically read the file and
 340                                                         modify the system dynamic library path:</para>
 341                                                         <screen>
 342                                                                 <userinput>
 343         # as the root user:
 344         echo "/openils/lib"   > /etc/ld.so.conf.d/osrf.conf
 345         echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf
 346         ldconfig</userinput>
 347                                                         </screen>
 348                                                 </step>
 349                                                 <step xml:id="serversideinstallation-definedomains">
 350                                                         <title>Define Public and Private OpenSRF Domains</title>
 351                                                         <para>For security purposes, OpenSRF uses Jabber domains to separate services
 352                                                         into public and private realms. On a single-server system the easiest way to
 353                                                         define public and private OpenSRF domains is to define separate host names by
 354                                                         adding entries to the file <filename>/etc/hosts</filename>.</para>
 355                                                         <para>In the following steps we will use the example domains
 356                                                         <systemitem class="domainname">public.localhost</systemitem> for the public
 357                                                         domain and <systemitem class="domainname">private.localhost</systemitem>
 358                                                         for the private domain. In an upcoming step, you will configure two special
 359                                                         <systemitem class="service">ejabberd</systemitem> users
 360                                                         to handle communications for these two domains.</para>
 361                                                         <para>As the <systemitem class="username">root</systemitem> user, edit the file
 362                                                         <filename>/etc/hosts</filename> and add the following example domains:</para>
 363                                                         <indexterm>
 364                                                                 <primary>Jabber</primary>
 365                                                         </indexterm>
 366                                                         <screen>
 367                                                                 <userinput>
 368         # as the root user:
 369         127.0.1.2  public.localhost   public
 370         127.0.1.3  private.localhost  private</userinput>
 371                                                         </screen>
 372                                                 </step>
 373                                                 <step>
 374                                                         <title>Change File Ownerships</title>
 375                                                         <para>Finally, as the <systemitem class="username">root</systemitem>
 376                                                         user, change the ownership of all files installed in the
 377                                                         directory <filename class="directory">/openils</filename> to the
 378                                                         user <systemitem class="username">opensrf</systemitem>:</para>
 379                                                         <screen>
 380                                                                 <userinput>
 381         # as the root user:
 382         chown -R opensrf:opensrf /openils</userinput>
 383                                                         </screen>
 384                                                 </step>
 385                                         </substeps>
 386                                 </step>
 387                                 <step xml:id="stop-ejabberd-service">
 388                                         <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
 389                                         <indexterm>
 390                                                 <primary>ejabberd</primary>
 391                                         </indexterm>
 392                                         <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
 393                                         you must stop that service. As the <systemitem class="username">root</systemitem> user,
 394                                         execute the following command to stop the service:</para>
 395                                         <screen>
 396                                                 <userinput>
 397         # as the root user:
 398         /etc/init.d/ejabberd stop</userinput>
 399                                         </screen>
 400                                         <para>If <systemitem class="service">ejabberd</systemitem> reports that it
 401                                         is already stopped, there may have been a problem when it started back
 402                                         in the installation step. If there are any remaining daemon processes such as
 403                                         <systemitem class="daemon">beam</systemitem> or
 404                                         <systemitem class="daemon">epmd</systemitem>
 405                                         you may need to perform the following commands to kill them:</para>
 406                                         <screen>
 407                                                 <userinput>
 408         # as the root user:
 409         epmd -kill
 410         killall beam; killall beam.smp
 411         rm /var/lib/ejabberd/*
 412         echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
 413                                         </screen>
 414                                 </step>
 415                                 <step>
 416                                         <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
 417                                         <para>You must make several configuration changes for the
 418                                         <systemitem class="service">ejabberd</systemitem> service before
 419                                         it is started again.
 420                                         As the <systemitem class="username">root</systemitem> user, edit the file
 421                                         <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
 422                                         <substeps>
 423                                                 <step>
 424                                                         <para>Change the line:</para>
 425                                                         <literal>{hosts, ["localhost"]}.</literal>
 426                                                         <para>to instead read:</para>
 427                                                         <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
 428                                                         <para/>
 429                                                 </step>
 430                                                 <step>
 431                                                         <para>Change the line for older versions of
 432                                                         <systemitem class="service">ejabberd</systemitem>:</para>
 433                                                         <literal>{max_user_sessions, 10}</literal>
 434                                                         <para>to instead read:</para>
 435                                                         <literal>{max_user_sessions, 10000}</literal>
 436                                                         <para/>
 437                                                         <para>Change the line for newer versions of
 438                                                         <systemitem class="service">ejabberd</systemitem>:</para>
 439                                                         <literal>{access, max_user_sessions, [{10, all}]}</literal>
 440                                                         <para>to instead read:</para>
 441                                                         <literal>{access, max_user_sessions, [{10000, all}]}</literal>
 442                                                 </step>
 443                                                 <step>
 444                                                         <para>Change all three occurrences of:</para>
 445                                                         <literal>max_stanza_size</literal>
 446                                                         <para>to instead read:</para>
 447                                                         <literal>2000000</literal>
 448                                                 </step>
 449                                                 <step>
 450                                                         <para>Change both occurrences of:</para>
 451                                                         <literal>maxrate</literal>
 452                                                         <para>to instead read:</para>
 453                                                         <literal>500000</literal>
 454                                                 </step>
 455                                                 <step>
 456                                                         <para>Comment out the line:</para>
 457                                                         <literal>{mod_offline, []}</literal>
 458                                                         <para>by placing two <literal>%</literal> comment signs in front
 459                                                         so it instead reads:</para>
 460                                                         <literal>%%{mod_offline, []}</literal>
 461                                                 </step>
 462                                         </substeps>
 463                                 </step>
 464                                 <step xml:id="serversideinstallation-opensrf-continued">
 465                                         <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
 466                                         <para>As the <systemitem class="username">root</systemitem> user, restart the
 467                                         <systemitem class="service">ejabberd</systemitem> service to test the
 468                                         configuration changes and to register your users:</para>
 469                                         <screen>
 470                                                 <userinput>
 471         # as the root user:
 472         /etc/init.d/ejabberd start</userinput>
 473                                         </screen>
 474                                 </step>
 475                                 <step>
 476                                         <title>Register <systemitem class="username">router</systemitem> and
 477                                                 <systemitem class="username">opensrf</systemitem> as
 478                                                 <systemitem class="service">ejabberd</systemitem> users</title>
 479                                         <para>The two <systemitem class="service">ejabberd</systemitem> users
 480                                         <systemitem class="username">router</systemitem> and
 481                                         <systemitem class="username">opensrf</systemitem> must be registered
 482                                         and configured to manage OpenSRF router service and communications
 483                                         for the two domains <literal>public.localhost</literal> and
 484                                         <literal>private.localhost</literal> that you added to the file
 485                                         <filename>/etc/hosts</filename> in a previous step
 486                                         (see <xref linkend="serversideinstallation-definedomains"/>).
 487                                         The users include:</para>
 488                                         <itemizedlist>
 489                                                 <listitem>
 490                                                         <para>the <systemitem class="username">router</systemitem> user,
 491                                                         to whom all requests to connect to an OpenSRF service will be
 492                                                         routed;</para>
 493                                                 </listitem>
 494                                                 <listitem>
 495                                                         <para>the <systemitem class="username">opensrf</systemitem> user,
 496                                                         which clients use to connect to OpenSRF services (you may name
 497                                                         the user anything you like, but we use
 498                                                         <literal>opensrf</literal> in these examples)</para>
 499                                                 </listitem>
 500                                         </itemizedlist>
 501                                         <para>As the <systemitem class="username">root</systemitem> user, execute the
 502                                         <command>ejabberdctl</command> utility as shown below to register and create passwords
 503                                         for the users <systemitem class="username">router</systemitem> and
 504                                         <systemitem class="username">opensrf</systemitem> on each domain (remember to replace
 505                                         <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
 506                                         <screen>
 507                                                 <userinput>
 508         # as the root user:
 509         # Note: the syntax for registering a user with ejabberdctl is:
 510         #    ejabberdctl register USER DOMAIN PASSWORD
 511         ejabberdctl register router  private.localhost NEWPASSWORD
 512         ejabberdctl register router  public.localhost  NEWPASSWORD
 513         ejabberdctl register opensrf private.localhost NEWPASSWORD
 514         ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>
 515                                         </screen>
 516                                         <para>The users <systemitem class="username">router</systemitem> and
 517                                         <systemitem class="username">opensrf</systemitem> and their respective passwords
 518                                         will be used again in <xref linkend="serversideinstallation-passwords"/> when
 519                                         we modify the OpenSRF configuration file
 520                                         <filename>/openils/conf/opensrf_core.xml</filename> .</para>
 521                                         <note>
 522                                                 <para>
 523                                                 There appears to be a problem with <command>ejabberdctl</command> in
 524                                                 that it does not escape input correctly, so a password like
 525                                                 <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
 526                                                 A bug against ejabberd has been filed. To register a password using
 527                                                 <command>ejabberdctl</command> with special shell characters until such
 528                                                 time as that bug is resolved, the workaround is to specify a
 529                                                 double-escaped character at the command line, for example,
 530                                                 <literal>'0P3N\\\\$RF'</literal> .</para>
 531                                         </note>
 532                                 </step>
 533                                 <step xml:id="serversideinstallation-opensrf-createconfig">
 534                                         <title>Create OpenSRF configuration files</title>
 535                                         <para>As the <systemitem class="username">opensrf</systemitem> user,
 536                                         execute the following commands to create the new configuration files
 537                                         <filename>/openils/conf/opensrf_core.xml</filename> and
 538                                         <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
 539                                         <screen>
 540                                                 <userinput>
 541         # as the opensrf user:
 542         cd /openils/conf
 543         cp opensrf.xml.example      opensrf.xml
 544         cp opensrf_core.xml.example opensrf_core.xml</userinput>
 545                                         </screen>
 546                                 </step>
 547                                 <step xml:id="serversideinstallation-passwords">
 548                                         <title>Update usernames and passwords in the OpenSRF configuration file</title>
 549                                         <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
 550                                         OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
 551                                         and update the usernames and passwords to match the values shown in the
 552                                         following table. The left-hand side of
 553                                         <xref linkend="serversideinstallation-xpath-table-1"/> shows common XPath
 554                                         syntax to indicate the approximate position within the XML file that needs
 555                                         changes. The right-hand side of the table shows the replacement values:</para>
 556                                         <table xml:id="serversideinstallation-xpath-table-1">
 557                                                 <?dbfo keep-together="always" ?>
 558                                                 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
 559                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">
 560                                                         <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
 561                                                         <colspec colname="Value" colnum="2" colwidth="2.0*"/>
 562                                                         <thead>
 563                                                                 <row>
 564                                                                         <entry>XPath location</entry>
 565                                                                         <entry>Value</entry>
 566                                                                 </row>
 567                                                         </thead>
 568                                                         <tbody>
 569                                                                 <row>
 570                                                                         <entry>/config/opensrf/username</entry>
 571                                                                         <entry>
 572                                                                                 <systemitem class="username">opensrf</systemitem>
 573                                                                         </entry>
 574                                                                 </row>
 575                                                                 <row>
 576                                                                         <entry>/config/opensrf/passwd </entry>
 577                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
 578                                                                         password for
 579                                                                         <systemitem class="username">opensrf</systemitem> user
 580                                                                         </entry>
 581                                                                 </row>
 582                                                                 <row>
 583                                                                         <entry>/config/gateway/username</entry>
 584                                                                         <entry>
 585                                                                                 <systemitem class="username">opensrf</systemitem>
 586                                                                         </entry>
 587                                                                 </row>
 588                                                                 <row>
 589                                                                         <entry>/config/gateway/passwd</entry>
 590                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
 591                                                                         password for
 592                                                                         <systemitem class="username">opensrf</systemitem> user
 593                                                                         </entry>
 594                                                                 </row>
 595                                                                 <row>
 596                                                                         <entry>/config/routers/router/transport/username,
 597                                                                         first entry where server == public.localhost</entry>
 598                                                                         <entry>
 599                                                                                 <systemitem class="username">router</systemitem>
 600                                                                         </entry>
 601                                                                 </row>
 602                                                                 <row>
 603                                                                         <entry>/config/routers/router/transport/password,
 604                                                                         first entry where server == public.localhost</entry>
 605                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
 606                                                                         password for
 607                                                                         <systemitem class="username">router</systemitem> user
 608                                                                         </entry>
 609                                                                 </row>
 610                                                                 <row>
 611                                                                         <entry>/config/routers/router/transport/username,
 612                                                                         second entry where server == private.localhost</entry>
 613                                                                         <entry>
 614                                                                                 <systemitem class="username">router</systemitem>
 615                                                                         </entry>
 616                                                                 </row>
 617                                                                 <row>
 618                                                                         <entry>/config/routers/router/transport/password,
 619                                                                         second entry where server == private.localhost</entry>
 620                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
 621                                                                         password for
 622                                                                         <systemitem class="username">router</systemitem> user
 623                                                                         </entry>
 624                                                                 </row>
 625                                                         </tbody>
 626                                                 </tgroup>
 627                                         </table>
 628                                         <para>You may also need to modify the file to specify the domains from which
 629                                         <systemitem class="service">OpenSRF</systemitem> will accept connections,
 630                                         and to which it will make connections.
 631                                         If you are installing <application>OpenSRF</application> on a single server
 632                                         and using the <systemitem class="domainname">private.localhost</systemitem> and
 633                                         <systemitem class="domainname">public.localhost</systemitem> domains,
 634                                         these will already be set to the correct values. Otherwise, search and replace
 635                                         to match values for your own systems.</para>
 636                                 </step>
 637                                 <step>
 638                                         <title>Set the location of the persistent database</title>
 639                                         <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
 640                                         file <filename>/openils/conf/opensrf.xml</filename>, then find and verify that
 641                                         the element <literal>dbfile</literal> (near the end of the file) is set to the
 642                                         location of the persistent database. If necessary, change the default line:</para>
 643                                         <literal>/openils/var/persist.db</literal>
 644                                         <para>to instead read:</para>
 645                                         <literal>/tmp/persist.db</literal>
 646                                         <para>Following is a sample modification of that portion of the file:</para>
 647                                         <programlisting language="xml"><![CDATA[
 648 <!-- Example of an app-specific setting override -->
 649 <opensrf.persist>
 650   <app_settings>
 651     <dbfile>/tmp/persist.db</dbfile>
 652   </app_settings>
 653 </opensrf.persist>
 654 ]]></programlisting>
 655                                 </step>
 656                                 <step xml:id="serversideinstallation-srfsh">
 657                                         <title>Create configuration files for users needing <command>srfsh</command></title>
 658                                         <para>In this section you will set up a special configuration file for each user
 659                                         who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
 660                                         shell</emphasis>) utility.</para>
 661                                         <indexterm>
 662                                                 <primary>srfsh</primary>
 663                                         </indexterm>
 664                                         <para>The software installation will automatically create the utility
 665                                         <command>srfsh</command>, a command line diagnostic tool for testing and
 666                                         interacting with <application>OpenSRF</application>. It will be used
 667                                         in a future step to complete and test the Evergreen installation. See
 668                                         <xref linkend="serversideinstallation-testing"/> for further information.</para>
 669                                         <para>As the <systemitem class="username">root</systemitem> user, copy the
 670                                         sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
 671                                         to the home directory of each user who will use <command>srfsh</command>.
 672                                         For instance, do the following for the
 673                                         <systemitem class="username">opensrf</systemitem> user:</para>
 674                                         <screen>
 675                                                 <userinput>
 676         # as the root user:
 677         cp /openils/conf/srfsh.xml.example  /home/opensrf/.srfsh.xml</userinput>
 678                                         </screen>
 679                                         <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
 680                                         following changes:</para>
 681                                         <itemizedlist>
 682                                                 <listitem>
 683                                                         <para>Modify <literal>domain</literal> to be the router hostname
 684                                                         (following our domain examples,
 685                                                         <systemitem class="domainname">private.localhost</systemitem> will give
 686                                                         <command>srfsh</command> access to all OpenSRF services, while
 687                                                         <systemitem class="domainname">public.localhost</systemitem>
 688                                                         will only allow access to those OpenSRF services that are
 689                                                         publicly exposed).</para>
 690                                                 </listitem>
 691                                                 <listitem>
 692                                                         <para>Modify <literal>username</literal> and
 693                                                         <literal>password</literal> to match the
 694                                                         <literal>opensrf</literal> Jabber user for the chosen
 695                                                         domain</para>
 696                                                 </listitem>
 697                                                 <listitem>
 698                                                         <para>Modify <literal>logfile</literal> to be the full path for
 699                                                         a log file to which the user has write access</para>
 700                                                 </listitem>
 701                                                 <listitem>
 702                                                         <para>Modify <literal>loglevel</literal> as needed for testing</para>
 703                                                 </listitem>
 704                                                 <listitem>
 705                                                         <para>Change the owner of the file to match the owner of the
 706                                                         home directory</para>
 707                                                 </listitem>
 708                                         </itemizedlist>
 709                                         <para>Following is a sample of the file:</para>
 710                                         <programlisting language="xml"><![CDATA[
 711 <?xml version="1.0"?>
 712 <!-- This file follows the standard bootstrap config file layout -->
 713 <!-- found in opensrf_core.xml -->
 714 <srfsh>
 715 <router_name>router</router_name>
 716 <domain>private.localhost</domain>
 717 <username>opensrf</username>
 718 <passwd>SOMEPASSWORD</passwd>
 719 <port>5222</port>
 720 <logfile>/tmp/srfsh.log</logfile>
 721 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
 722 <loglevel>4</loglevel>
 723 </srfsh>
 724 ]]></programlisting>
 725                                 </step>
 726                                 <step>
 727                                         <title>Modify the environmental variable <envar>PATH</envar> for the
 728                                                 <systemitem class="username">opensrf</systemitem> user</title>
 729                                         <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
 730                                         environmental variable <envar>PATH</envar> by adding a new file path to the
 731                                         <systemitem class="username">opensrf</systemitem> user's shell configuration
 732                                         file <filename>~/.bashrc</filename>:</para>
 733                                         <screen>
 734                                                 <userinput>
 735         # as the opensrf user:
 736         echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
 737                                         </screen>
 738                                 </step>
 739                                 <step>
 740                                         <title>Start OpenSRF</title>
 741                                         <para>As the <systemitem class="username">root</systemitem> user, start the
 742                                         <systemitem class="service">ejabberd</systemitem> and
 743                                         <systemitem class="service">memcached</systemitem> services:</para>
 744                                         <screen>
 745                                                 <userinput>
 746         # as the root user:
 747         /etc/init.d/ejabberd start
 748         /etc/init.d/memcached start</userinput>
 749                                         </screen>
 750                                         <para>Then as the <systemitem class="username">opensrf</systemitem> user,
 751                                         start OpenSRF as follows:</para>
 752                                         <screen>
 753                                                 <userinput>
 754         # as the opensrf user:
 755         osrf_ctl.sh -l -a start_all</userinput>
 756                                         </screen>
 757                                         <para>The flag <option>-l</option> forces Evergreen to use
 758                                         <systemitem class="domainname">localhost</systemitem> (your current system)
 759                                         as the hostname. The flag <option>-a start_all</option> starts the
 760                                         OpenSRF <systemitem class="service">router</systemitem> ,
 761                                         <systemitem class="service">Perl</systemitem> , and
 762                                         <systemitem class="service">C</systemitem> services.</para>
 763                                         <itemizedlist>
 764                                                 <listitem>
 765                                                         <para>You can also start Evergreen without the
 766                                                         <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
 767                                                         utility must know the fully qualified domain name for the system
 768                                                         on which it will execute. That hostname was probably specified
 769                                                         in the configuration file <filename>opensrf.xml</filename> which
 770                                                         you configured in a previous step.</para>
 771                                                 </listitem>
 772                                                 <listitem>
 773                                                         <para>If you receive an error message similar to
 774                                                         <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
 775                                                         environment variable <envar>PATH</envar> does not include the
 776                                                         directory <filename class="directory">/openils/bin</filename>.
 777                                                         As the <systemitem class="username">opensrf</systemitem> user,
 778                                                         edit the configuration file <filename>~/.bashrc</filename> and
 779                                                         add the following line:
 780                                                         <literal>export PATH=$PATH:/openils/bin</literal></para>
 781                                                 </listitem>
 782                                         </itemizedlist>
 783                                 </step>
 784                                 <step>
 785                                         <title>Test connections to OpenSRF</title>
 786                                         <para>Once you have installed and started OpenSRF, as the
 787                                         <systemitem class="username">root</systemitem> user test your connection to
 788                                         <systemitem class="service">OpenSRF</systemitem> with the <command>srfsh</command>
 789                                         utility and try to call the <command>add</command> method on the OpenSRF
 790                                         <systemitem class="service">math</systemitem> service:</para>
 791                                         <screen>
 792                                                 <userinput>
 793         # as the root user:
 794         /openils/bin/srfsh</userinput>
 795                                                 <computeroutput>
 796         srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
 797                                                 <computeroutput>
 798         Received Data: 4
 799         ------------------------------------
 800         Request Completed Successfully
 801         Request Time in seconds: 0.007519
 802         ------------------------------------</computeroutput>
 803                                         </screen>
 804                                         <para>For other <command>srfsh</command> commands, type in
 805                                         <userinput>help</userinput> at the prompt.</para>
 806                                 </step>
 807                                 <step>
 808                                         <title>Stop OpenSRF</title>
 809                                         <para>After OpenSRF has started, you can stop it at any time by using the
 810                                         <command>osrf_ctl.sh</command> again. As the
 811                                         <systemitem class="username">opensrf</systemitem>
 812                                         user, stop OpenSRF as follows:</para>
 813                                         <screen>
 814                                                 <userinput>
 815         # as the opensrf user:
 816         osrf_ctl.sh -l -a stop_all</userinput>
 817                                         </screen>
 818                                 </step>
 819                         </procedure>
 820                 </section>
 821                 <section xml:id="serversideinstallation-ubuntudebian">
 822                         <title>Installing Evergreen 2.x On <systemitem class="osname">Ubuntu</systemitem> or
 823                                 <systemitem class="osname">Debian</systemitem></title>
 824                         <indexterm>
 825                                 <primary>Linux</primary>
 826                                 <secondary>Debian</secondary>
 827                         </indexterm>
 828                         <indexterm>
 829                                 <primary>Linux</primary>
 830                                 <secondary>Ubuntu</secondary>
 831                         </indexterm>
 832                         <para>This section outlines the installation process for the latest stable
 833                         version of Evergreen on <systemitem class="osname">Ubuntu</systemitem> or
 834                         <systemitem class="osname">Debian</systemitem> systems.  See
 835                         <xref linkend="serversideinstallation-fedora"/> for description of a similar
 836                         installation on a <systemitem class="osname">Fedora 14</systemitem> system.</para>
 837                         <para>In this section you will download, unpack, install, configure and test the Evergreen
 838                         system, including the Evergreen server and the PostgreSQL database system. You will make several
 839                         configuration changes and adjustments to the software, including updates to configure the system
 840                         for your own locale, and some updates needed to work around a few known issues.</para>
 841                         <note>
 842                                 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
 843                                 architectures. There may be differences between the Desktop and Server editions of
 844                                 <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
 845                                 edition.</para>
 846                                 <para>In the following instructions, you are asked to perform certain steps as
 847                                 either the <systemitem class="username">root</systemitem> user, the
 848                                 <systemitem class="username">opensrf</systemitem> user, or the
 849                                 <systemitem class="username">postgres</systemitem> user.</para>
 850                                 <itemizedlist>
 851                                         <listitem>
 852                                                 <para><systemitem class="osname">Debian</systemitem> -- To become the
 853                                                 <systemitem class="username">root</systemitem> user, issue the command
 854                                                 <command>su -</command> and enter the password of the
 855                                                 <systemitem class="username">root</systemitem> user.</para>
 856                                         </listitem>
 857                                         <listitem>
 858                                                 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
 859                                                 <systemitem class="username">root</systemitem> user, issue the command
 860                                                 <command>sudo su -</command> and enter the password of the
 861                                                 <systemitem class="username">root</systemitem> user.</para>
 862                                         </listitem>
 863                                 </itemizedlist>
 864                                 <para>To switch from the <systemitem class="username">root</systemitem> user to a
 865                                 different user, issue the command <command>su - USERNAME</command>. For example, to
 866                                 switch from the <systemitem class="username">root</systemitem> user to the
 867                                 <systemitem class="username">opensrf</systemitem> user, issue the command
 868                                 <command>su - opensrf</command>. Once you have become a non-root user, to become the
 869                                 <systemitem class="username">root</systemitem> user again, simply issue the command
 870                                 <command>exit</command>.</para>
 871                         </note>
 872                         <procedure>
 873                                 <step>
 874                                         <title>Install OpenSRF</title>
 875                                         <para>Evergreen software is integrated with and depends on the Open Service
 876                                         Request Framework (OpenSRF) software system. For further information on
 877                                         installing, configuring and testing OpenSRF, see
 878                                         <xref linkend="serversideinstallation-opensrf-1.6.3"/>.</para>
 879                                         <para>Follow the steps outlined in that section and run the specified tests to
 880                                         ensure that OpenSRF is properly installed and configured. Do
 881                                         <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
 882                                         any further Evergreen installation steps until you have verified that OpenSRF
 883                                         has been successfully installed and tested.</para>
 884                                 </step>
 885                                 <step>
 886                                         <title>Download and Unpack Latest Evergreen Version</title>
 887                                         <para>The latest version of Evergreen can be found here:
 888                                         <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
 889                                         As the <systemitem class="username">opensrf</systemitem> user, change to
 890                                         the directory <filename class="directory">/home/opensrf</filename> then download
 891                                         and extract Evergreen. The new subdirectory
 892                                         <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename>
 893                                         will be created:</para>
 894                                         <screen>
 895                                                 <userinput>
 896         # as the opensrf user:
 897         cd /home/opensrf
 898         wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
 899         tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
 900                                         </screen>
 901                                 </step>
 902                                 <step xml:id="serversideinstallation-installprereq">
 903                                         <title>Install Prerequisites to Build Evergreen</title>
 904                                         <para>In this section you will install and configure a set of prerequisites that will be
 905                                         used later in <xref linkend="serversideinstallation-configure"/> and
 906                                         <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
 907                                         using the <command>make</command> utility.</para>
 908                                         <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
 909                                         below to build the prerequisites from the software distribution that you just downloaded
 910                                         and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
 911                                         example with the keyword corresponding to the name of one of the
 912                                         <systemitem class="osname">Linux</systemitem> distributions listed in the in the
 913                                         distribution keywords table <xref linkend="serversideinstallation-keywords-evergreen"/>.
 914                                         For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
 915                                         enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
 916                                         ubuntu-lucid</command>.</para>
 917                                         <screen>
 918                                                 <userinput>
 919         # as the root user:
 920         cd /home/opensrf/Evergreen-ILS-2.0.4
 921         make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
 922                                         </screen>
 923
 924                                         <table xml:id="serversideinstallation-keywords-evergreen">
 925                                                 <?dbfo keep-together="always" ?>
 926                                                 <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
 927                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">
 928                                                         <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
 929                                                         <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
 930                                                         <thead>
 931                                                                 <row>
 932                                                                         <entry>Keyword</entry>
 933                                                                         <entry>Linux Version</entry>
 934                                                                 </row>
 935                                                         </thead>
 936                                                         <tbody>
 937                                                                 <row>
 938                                                                         <entry>debian-squeeze</entry>
 939                                                                         <entry>Debian "Squeeze" (6.0)</entry>
 940                                                                 </row>
 941                                                                 <row>
 942                                                                         <entry>debian-lenny</entry>
 943                                                                         <entry>Debian "Lenny" (5.0)</entry>
 944                                                                 </row>
 945                                                                 <row>
 946                                                                         <entry>ubuntu-hardy</entry>
 947                                                                         <entry>Ubuntu "Hardy Heron" (8.04)</entry>
 948                                                                 </row>
 949                                                                 <row>
 950                                                                         <entry>ubuntu-lucid</entry>
 951                                                                         <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
 952                                                                 </row>
 953                                                                 <row>
 954                                                                         <entry>fedora13</entry>
 955                                                                         <entry>Fedora "Goddard" (13)</entry>
 956                                                                 </row>
 957                                                                 <row>
 958                                                                         <entry>centos</entry>
 959                                                                         <entry>CentOS 5</entry>
 960                                                                 </row>
 961                                                                 <row>
 962                                                                         <entry>rhel</entry>
 963                                                                         <entry>Red Hat Enterprise Linux 5</entry>
 964                                                                 </row>
 965                                                         </tbody>
 966                                                 </tgroup>
 967                                         </table>
 968                                         <indexterm>
 969                                                 <primary>Linux</primary>
 970                                                 <secondary>Debian</secondary>
 971                                         </indexterm>
 972                                         <indexterm>
 973                                                 <primary>Linux</primary>
 974                                                 <secondary>Fedora</secondary>
 975                                         </indexterm>
 976                                         <indexterm>
 977                                                 <primary>Linux</primary>
 978                                                 <secondary>Ubuntu</secondary>
 979                                         </indexterm>
 980                                         <indexterm>
 981                                                 <primary>Linux</primary>
 982                                                 <secondary>CentOS</secondary>
 983                                         </indexterm>
 984                                         <indexterm>
 985                                                 <primary>Linux</primary>
 986                                                 <secondary>Red Hat</secondary>
 987                                         </indexterm>
 988                                 </step>
 989                                 <step performance="optional">
 990                                         <title>(OPTIONAL) Install the PostgreSQL Server</title>
 991                                         <indexterm>
 992                                                 <primary>databases</primary>
 993                                                 <secondary>PostgreSQL</secondary>
 994                                         </indexterm>
 995                                         <para>Since the PostgreSQL server is usually a standalone server in multi-server
 996                                         production systems, the prerequisite installer Makefile in the previous section
 997                                         (see <xref linkend="serversideinstallation-installprereq"/>)
 998                                         does not automatically install PostgreSQL. You must install the PostgreSQL server
 999                                         yourself, either on the same system as Evergreen itself or on another system.
1000                                         If your PostgreSQL server is on a different system, just skip this step.
1001                                         If your PostgreSQL server will be on the same system as your Evergreen
1002                                         software, you can install the required PostgreSQL server packages as described
1003                                         in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
1004                                         web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1005                                         for more information.</para>
1006                                         <note>
1007                                                 <para>PostgreSQL version 8.4 is the minimum supported version to work
1008                                                 with Evergreen 2.0. If you have an older version of PostgreSQL,
1009                                                 you should upgrade before installing Evergreen. To find your current version
1010                                                 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
1011                                                 user execute the command <command>psql</command>, then type
1012                                                 <userinput>SELECT version();</userinput> to get detailed information
1013                                                 about your version of PostgreSQL.</para>
1014                                         </note>
1015                                 </step>
1016                                 <step performance="optional">
1017                                         <title>Install Perl Modules on PostgreSQL Server</title>
1018                                         <para>If PostgreSQL is running on the same system as your Evergreen software,
1019                                         then the Perl modules will automatically be available. Just skip this step.
1020                                         Otherwise, continue if your PostgreSQL server is running on another system
1021                                         and install several Perl modules there. As the
1022                                         <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1023                                         is installed, then install the following Perl modules:</para>
1024                                         <screen>
1025                                                 <userinput>
1026         aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
1027         perl -MCPAN -e shell
1028                 <prompt>cpan></prompt> Business::ISBN
1029                 <prompt>cpan></prompt> install JSON::XS
1030                 <prompt>cpan></prompt> Library::CallNumber::LC
1031                 <prompt>cpan></prompt> install MARC::Record
1032                 <prompt>cpan></prompt> install MARC::File::XML
1033                 <prompt>cpan></prompt> cpan UUID::Tiny</userinput>
1034                                         </screen>
1035                                         <para>For more information on installing Perl Modules vist the official
1036                                         <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1037                                         <indexterm>
1038                                                 <primary>Perl</primary>
1039                                                 <secondary>CPAN</secondary>
1040                                         </indexterm>
1041                                 </step>
1042                                 <step>
1043                                         <title>Update the System Dynamic Library Path</title>
1044                                         <para>You must update the system dynamic library path to force your system to recognize
1045                                         the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
1046                                         do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
1047                                         containing two new library paths, then run the command <command>ldconfig</command> to
1048                                         automatically read the file and modify the system dynamic library path:</para>
1049                                         <screen>
1050                                                 <userinput>
1051         # as the root user:
1052         echo "/usr/local/lib"      > /etc/ld.so.conf.d/osrf.conf
1053         echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
1054         ldconfig</userinput>
1055                                         </screen>
1056                                 </step>
1057                                 <step performance="optional">
1058                                         <title>Restart the PostgreSQL Server</title>
1059                                         <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
1060                                         the <systemitem class="username">root</systemitem> user you must restart
1061                                         PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
1062                                         running on another system, you may skip this step.
1063                                         As the <systemitem class="username">opensrf</systemitem> user,
1064                                         execute the following command (remember to replace
1065                                         <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
1066                                         for example <literal>8.4</literal>):</para>
1067                                         <screen>
1068                                                 <userinput>
1069         # as the opensrf user:
1070         /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
1071                                         </screen>
1072                                 </step>
1073                                 <step xml:id="serversideinstallation-configure">
1074                                         <title>Configure Evergreen</title>
1075                                         <para>In this step you will use the <command>configure</command> and
1076                                         <command>make</command> utilities to configure Evergreen so it can be compiled
1077                                         and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
1078                                         <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1079                                         the Evergreen build directory and execute these commands:</para>
1080                                         <screen>
1081                                                 <userinput>
1082         # as the opensrf user:
1083         cd /home/opensrf/Evergreen-ILS-2.0.4
1084         ./configure --prefix=/openils --sysconfdir=/openils/conf
1085         make</userinput>
1086                                         </screen>
1087                                 </step>
1088                                 <step xml:id="serversideinstallation-compile">
1089                                         <title>Compile, Link and Install Evergreen</title>
1090                                         <para>In this step you will actually compile, link and install Evergreen and the
1091                                         default Evergreen Staff Client.</para>
1092                                         <para>As the <systemitem class="username">root</systemitem> user, return to the
1093                                         Evergreen build directory and use the <command>make</command> utility as shown
1094                                         below:</para>
1095                                         <screen>
1096                                                 <userinput>
1097         # as the root user:
1098         cd /home/opensrf/Evergreen-ILS-2.0.4
1099         make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
1100                                         </screen>
1101                                         <para>The Staff Client will also be automatically built, but you must remember
1102                                         to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1103                                         Staff Client you will use to connect to the Evergreen server.</para>
1104                                         <para>The above commands will create a new subdirectory
1105                                         <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
1106                                         containing the Staff Client.</para>
1107                                         <para>To complete the Staff Client installation, as the
1108                                         <systemitem class="username">root</systemitem> user execute the following commands to
1109                                         create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
1110                                         directory <filename class="directory">/openils/var/web/xul</filename> that points to the
1111                                         subdirectory <filename class="directory">/server</filename> of the new Staff Client
1112                                         build:</para>
1113                                         <screen>
1114                                                 <userinput>
1115         # as the root user:
1116         cd /openils/var/web/xul
1117         ln -sf rel_2_0_4/server server</userinput>
1118                                         </screen>
1119                                 </step>
1120                                 <step>
1121                                         <title>Copy the OpenSRF Configuration Files</title>
1122                                         <para>In this step you will replace some OpenSRF configuration files that you set up in
1123                                         <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
1124                                         tested OpenSRF.</para>
1125                                         <para>You must copy several example OpenSRF configuration files into place after first
1126                                         creating backup copies for troubleshooting purposes, then change all the file ownerships
1127                                         to <systemitem class="username">opensrf</systemitem>.
1128                                         As the <systemitem class="username">root</systemitem> user, execute the following
1129                                         commands:</para>
1130                                         <screen>
1131                                                 <userinput>
1132         # as the root user:
1133         cd /openils/conf
1134         cp opensrf.xml        opensrf.xml.BAK
1135         cp opensrf_core.xml      opensrf_core.xml.BAK
1136         cp opensrf.xml.example      opensrf.xml
1137         cp opensrf_core.xml.example opensrf_core.xml
1138         cp oils_web.xml.example     oils_web.xml
1139         chown -R opensrf:opensrf /openils/</userinput>
1140                                         </screen>
1141                                 </step>
1142                                 <step>
1143                                         <title>Create and Configure PostgreSQL Database</title>
1144                                         <indexterm>
1145                                                 <primary>databases</primary>
1146                                                 <secondary>PostgreSQL</secondary>
1147                                         </indexterm>
1148                                         <para>In this step you will create the Evergreen database. In the commands
1149                                         below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
1150                                         repository to match your PostgreSQL server
1151                                         layout. For example, if you built PostgreSQL from source the path would be
1152                                         <filename class="directory">/usr/local/share/contrib</filename> , and if you
1153                                         installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
1154                                         the path would be
1155                                         <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1156                                         <substeps>
1157                                                 <step>
1158                                                         <title>Create and configure the database</title>
1159                                                         <para>As the <systemitem class="username">postgres</systemitem>
1160                                                         user on the PostgreSQL system create the PostgreSQL database,
1161                                                         then set some internal paths:</para>
1162                                                         <screen>
1163                                                                 <userinput>
1164         # as the postgres user:
1165         createdb evergreen -E UTF8 -T template0
1166         createlang plperl   evergreen
1167         createlang plperlu  evergreen
1168         createlang plpgsql  evergreen</userinput>
1169                                                         </screen>
1170                                                         <para>Continue as the <systemitem class="username">postgres</systemitem>
1171                                                         user and execute the SQL scripts as shown below (remember to adjust the
1172                                                         paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1173                                                         your installed PostgreSQL version, for example
1174                                                         <literal>"8.4"</literal>).</para>
1175                                                         <screen>
1176                                                                 <userinput>
1177         # as the postgres user:
1178         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1179         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
1180         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
1181                                                         </screen>
1182                                                 </step>
1183                                                 <step xml:id="serversideinstallation-postgresqlcreateuser">
1184                                                         <title>Create <systemitem class="username">evergreen</systemitem>
1185                                                                 PostgreSQL user</title>
1186                                                         <para>As the <systemitem class="username">postgres</systemitem>
1187                                                         user on the PostgreSQL system, create a new PostgreSQL user
1188                                                         named <systemitem class="username">evergreen</systemitem> and
1189                                                         assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1190                                                         with an appropriate new password):</para>
1191                                                         <screen>
1192                                                                 <userinput>
1193         # as the postgres user:
1194         createuser -P -s evergreen</userinput>
1195                                                                 <computeroutput>
1196         Enter password for new role: <userinput>NEWPASSWORD</userinput>
1197         Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1198                                                         </screen>
1199                                                 </step>
1200                                                 <step>
1201                                                         <title>Create database schema</title>
1202                                                         <para>In this step you will create the database schema and configure your
1203                                                         system with the corresponding database authentication details for the
1204                                                         <emphasis>evergreen</emphasis> database user that you just created in
1205                                                         <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
1206                                                         <para>As the <systemitem class="username">root</systemitem> user, enter
1207                                                         the following commands and replace <emphasis>HOSTNAME, PORT,
1208                                                         PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1209                                                         values:</para>
1210                                                         <screen>
1211                                                                 <userinput>
1212         # as the root user:
1213         cd /home/opensrf/Evergreen-ILS-2.0.4
1214         perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1215         --service all --create-schema --create-offline \
1216         --hostname HOSTNAME --port PORT \
1217         --user evergreen --password PASSWORD \
1218         --database DATABASENAME --admin-user ADMIN-USER \
1219         --admin-pass ADMIN-PASSWORD </userinput>
1220                                                         </screen>
1221                                                         <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1222                                                         <emphasis role="bold">localhost</emphasis> and
1223                                                         <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1224                                                         Of course, values for <emphasis>PASSWORD</emphasis> and
1225                                                         <emphasis>DATABASENAME</emphasis> must match the values you used in
1226                                                         <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
1227                                                         The <option>admin-user</option> and <option>admin-pass</option> options will
1228                                                         specify the Evergreen administrator account's username and password. This was
1229                                                         changed for security reasons, it was previously admin/open-ils</para>
1230                                                         <para>As the command executes, you may see warnings similar to:
1231                                                         <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1232                                                         you may see one warning per schema) but they can be safely ignored.</para>
1233                                                         <note>If you are entering the above command on a single line, do not
1234                                                         include the <literal>\</literal> (backslash) characters. If you are using
1235                                                         the <command>bash</command> shell, these should only be used at the end of
1236                                                         a line at a <command>bash</command> prompt to indicate that the command is
1237                                                         continued on the next line.</note>
1238                                                 </step>
1239                                         </substeps>
1240                                 </step>
1241                                 <step>
1242                                         <title>Configure the Apache web server</title>
1243                                         <indexterm>
1244                                                 <primary>web server</primary>
1245                                                 <secondary>Apache</secondary>
1246                                         </indexterm>
1247                                         <para>In this step you will configure the Apache web server to support Evergreen
1248                                         software.</para>
1249                                         <para>First, you must enable some built-in Apache modules and install some
1250                                         additional Apache configuration files. Then you will create a new Security
1251                                         Certificate. Finally, you must make several changes to the Apache configuration
1252                                         file.</para>
1253                                         <substeps>
1254                                                 <step>
1255                                                         <title>Enable the required Apache Modules</title>
1256                                                         <para>As the <systemitem class="username">root</systemitem>
1257                                                         user, enable some modules in the Apache server, then copy the
1258                                                         new configuration files to the Apache server directories:</para>
1259                                                         <indexterm>
1260                                                                 <primary>Apache modules</primary>
1261                                                         </indexterm>
1262                                                         <screen>
1263                                                                 <userinput>
1264         # as the root user:
1265         a2enmod ssl     # enable mod_ssl
1266         a2enmod rewrite # enable mod_rewrite
1267         a2enmod expires # enable mod_expires</userinput>
1268                                                         </screen>
1269                                                         <para>As the commands execute, you may see warnings similar to:
1270                                                         <literal>Module SOMEMODULE already enabled</literal> but you can
1271                                                         safely ignore them.</para>
1272                                                 </step>
1273                                                 <step>
1274                                                         <title>Copy Apache configuration files</title>
1275                                                         <para>You must copy the Apache configuration files from the
1276                                                         Evergreen installation directory to the Apache directory. As the
1277                                                         <systemitem class="username">root</systemitem> user, perform the
1278                                                         following commands:</para>
1279                                                         <screen>
1280                                                                 <userinput>
1281         # as the root user:
1282         cd /home/opensrf/Evergreen-ILS-2.0.4
1283         cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/
1284         cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/
1285         cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>
1286                                                         </screen>
1287                                                 </step>
1288                                                 <step xml:id="serversideinstallation-createsslcertificate">
1289                                                         <title>Create a Security Certificate</title>
1290                                                         <para>In this step you will create a new Security Certificate (SSL Key)
1291                                                         for the Apache server using the <command>openssl</command> command. For a
1292                                                         public production server you must configure or purchase a signed SSL
1293                                                         certificate, but for now you can just use a self-signed certificate and
1294                                                         accept the warnings in the Staff Client and browser during testing and
1295                                                         development. As the <systemitem class="username">root</systemitem> user,
1296                                                         perform the following commands:</para>
1297                                                         <screen>
1298                                                                 <userinput>
1299         # as the root user:
1300         mkdir /etc/apache2/ssl
1301         cd /etc/apache2/ssl
1302         openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1303                                                         </screen>
1304                                                         <para>You will be prompted for several items of information; enter
1305                                                         the appropriate information for each item. The new files
1306                                                         <filename>server.crt</filename> and <filename>server.key</filename> will
1307                                                         be created in the directory
1308                                                         <filename class="directory">/etc/apache2/ssl</filename> .</para>
1309                                                         <note>This step generates a self-signed SSL certificate. You must install
1310                                                         a proper SSL certificate for a public production system to avoid warning
1311                                                         messages when users login to their account through the OPAC or when staff
1312                                                         login through the Staff Client. For further information on
1313                                                         installing a proper SSL certificate, see
1314                                                         <xref linkend="serversideinstallation-ssl"/>.</note>
1315                                                 </step>
1316                                                 <step xml:id="serversideinstallation-modify-apache">
1317                                                         <title>Update Apache configuration files</title>
1318                                                         <para>You must make several changes to an Apache configuration file.</para>
1319                                                         <para>As the <systemitem class="username">root</systemitem> user
1320                                                         edit the file <filename>/etc/apache2/sites-available/eg.conf</filename>
1321                                                         and make the following changes:</para>
1322                                                         <itemizedlist>
1323                                                                 <listitem>
1324                                                                         <para>In the section
1325                                                                         <literal>&lt;Directory "/openils/var/cgi-bin"></literal>
1326                                                                         replace the line:</para>
1327                                                                         <literal>Allow from 10.0.0.0/8</literal>
1328                                                                         <para>with the line:</para>
1329                                                                         <literal>Allow from all</literal>
1330                                                                         <warning>This change allows access to your configuration
1331                                                                         CGI scripts from any workstation on any network. This is
1332                                                                         only a temporary change to expedite testing and should be
1333                                                                         removed after you have finished and successfully tested
1334                                                                         the Evergreen installation. See
1335                                                                         <xref linkend="serversideinstallation-postinstallation"/>
1336                                                                         for further details on removing this change after the
1337                                                                         Evergreen installation is complete.
1338                                                                         </warning>
1339                                                                 </listitem>
1340                                                                 <listitem>
1341                                                                         <para>Comment out the line:</para>
1342                                                                         <literal>Listen 443</literal>
1343                                                                         <para>since it conflicts with the same declaration in
1344                                                                         the configuration file:</para>
1345                                                                         <para><filename>/etc/apache2/ports.conf</filename>.</para>
1346                                                                 </listitem>
1347                                                                 <listitem>
1348                                                                         <para>The following updates are needed to allow the logs
1349                                                                         to function properly, but it may break other Apache
1350                                                                         applications on your server:</para>
1351                                                                         <para>As the <systemitem class="username">root</systemitem> user, edit the Apache configuration file <filename>/etc/apache2/envvars</filename> and
1352                                                                         change the lines:</para>
1353                                                                         <screen>
1354                                                                                 <userinput>
1355         export APACHE_RUN_USER=www-data
1356         export APACHE_RUN_GROUP=www-data</userinput>
1357                                                                         </screen>
1358                                                                         <para>to instead read:</para>
1359                                                                         <screen>
1360                                                                                 <userinput>
1361         export APACHE_RUN_USER=opensrf
1362         export APACHE_RUN_GROUP=opensrf</userinput>
1363                                                                         </screen>
1364                                                                 </listitem>
1365                                                                 <listitem>
1366                                                                         <para>As the
1367                                                                         <systemitem class="username">root</systemitem> user,
1368                                                                         edit the Apache configuration file
1369                                                                         <filename>/etc/apache2/apache2.conf</filename> and
1370                                                                         modify the value for <literal>KeepAliveTimeout</literal>
1371                                                                         and <literal>MaxKeepAliveRequests</literal> to match
1372                                                                         the following:</para>
1373                                                                         <screen>
1374                                                                                 <userinput>
1375         KeepAliveTimeout       1
1376         MaxKeepAliveRequests 100</userinput>
1377                                                                         </screen>
1378                                                                 </listitem>
1379                                                                 <listitem>
1380                                                                         <para>Further configuration changes to Apache may be
1381                                                                         necessary for busy systems. These changes increase the
1382                                                                         number of Apache server processes that are started to
1383                                                                         support additional browser connections.</para>
1384                                                                         <para>As the
1385                                                                         <systemitem class="username">root</systemitem> user,
1386                                                                         edit the Apache configuration file
1387                                                                         <filename>/etc/apache2/apache2.conf</filename>, locate
1388                                                                         and modify the section related to <emphasis>prefork
1389                                                                         configuration</emphasis> to suit the load on your
1390                                                                         system:</para>
1391                                                                         <programlisting language="xml"><![CDATA[
1392 <IfModule mpm_prefork_module>
1393    StartServers    20
1394    MinSpareServers       5
1395    MaxSpareServers      15
1396    MaxClients       150
1397    MaxRequestsPerChild 10000
1398 </IfModule>
1399 ]]></programlisting>
1400                                                                 </listitem>
1401                                                         </itemizedlist>
1402                                                 </step>
1403                                                 <step>
1404                                                         <title>Enable the Evergreen web site</title>
1405                                                         <para>Finally, you must enable the Evergreen web site. As the
1406                                                         <systemitem class="username">root</systemitem> user, execute the
1407                                                         following Apache configuration commands to disable the default
1408                                                         <emphasis>It Works</emphasis> web page and enable the Evergreen
1409                                                         web site, and then restart the Apache server:</para>
1410                                                         <screen>
1411                                                                 <userinput>
1412         # as the root user:
1413         # disable/enable web sites
1414         a2dissite default
1415         a2ensite eg.conf
1416         # restart the server
1417         /etc/init.d/apache2 reload</userinput>
1418                                                         </screen>
1419                                                 </step>
1420                                         </substeps>
1421                                 </step>
1422                                 <step xml:id="serversideinstallation-opensrf-config">
1423                                         <title>Update the OpenSRF Configuration File</title>
1424                                         <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1425                                         OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1426                                         to update the Jabber usernames and passwords, and to specify the domain from
1427                                         which we will accept and to which we will make connections.</para>
1428                                         <para>If you are installing Evergreen on a single server and using the
1429                                         <systemitem class="domainname">private.localhost</systemitem> /
1430                                         <systemitem class="domainname">public.localhost</systemitem> domains,
1431                                         these will already be set to the correct values. Otherwise, search and replace
1432                                         to match your customized values.</para>
1433                                         <para>The left-hand side of  <xref linkend="serversideinstallation-xpath-table-2"/>
1434                                         shows common XPath syntax to indicate the approximate position within the XML
1435                                         file that needs changes. The right-hand side of the table shows the replacement
1436                                         values:</para>
1437                                         <table xml:id="serversideinstallation-xpath-table-2">
1438                                                 <?dbfo keep-together="always" ?>
1439                                                 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
1440                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">
1441                                                         <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
1442                                                         <colspec colname="Value" colnum="2" colwidth="2.0*"/>
1443                                                         <thead>
1444                                                                 <row>
1445                                                                         <entry>XPath location</entry>
1446                                                                         <entry>Value</entry>
1447                                                                 </row>
1448                                                         </thead>
1449                                                         <tbody>
1450                                                                 <row>
1451                                                                         <entry>/config/opensrf/username</entry>
1452                                                                         <entry>
1453                                                                                 <systemitem class="username">opensrf</systemitem>
1454                                                                         </entry>
1455                                                                 </row>
1456                                                                 <row>
1457                                                                         <entry>/config/opensrf/passwd </entry>
1458                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
1459                                                                         password for
1460                                                                         <systemitem class="username">opensrf</systemitem> user
1461                                                                         </entry>
1462                                                                 </row>
1463                                                                 <row>
1464                                                                         <entry>/config/gateway/username</entry>
1465                                                                         <entry>
1466                                                                                 <systemitem class="username">opensrf</systemitem>
1467                                                                         </entry>
1468                                                                 </row>
1469                                                                 <row>
1470                                                                         <entry>/config/gateway/passwd</entry>
1471                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
1472                                                                         password for
1473                                                                         <systemitem class="username">opensrf</systemitem> user
1474                                                                         </entry>
1475                                                                 </row>
1476                                                                 <row>
1477                                                                         <entry>/config/routers/router/transport/username,
1478                                                                         first entry where server == public.localhost</entry>
1479                                                                         <entry>
1480                                                                                 <systemitem class="username">router</systemitem>
1481                                                                         </entry>
1482                                                                 </row>
1483                                                                 <row>
1484                                                                         <entry>/config/routers/router/transport/password,
1485                                                                         first entry where server == public.localhost</entry>
1486                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
1487                                                                         password for
1488                                                                         <systemitem class="username">router</systemitem> user
1489                                                                         </entry>
1490                                                                 </row>
1491                                                                 <row>
1492                                                                         <entry>/config/routers/router/transport/username,
1493                                                                         second entry where server == private.localhost</entry>
1494                                                                         <entry>
1495                                                                                 <systemitem class="username">router</systemitem>
1496                                                                         </entry>
1497                                                                 </row>
1498                                                                 <row>
1499                                                                         <entry>/config/routers/router/transport/password,
1500                                                                         second entry where server == private.localhost</entry>
1501                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
1502                                                                         password for
1503                                                                         <systemitem class="username">router</systemitem> user
1504                                                                         </entry>
1505                                                                 </row>
1506                                                         </tbody>
1507                                                 </tgroup>
1508                                         </table>
1509                                 </step>
1510                                 <step performance="optional">
1511                                         <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
1512                                         <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
1513                                         software installation automatically created a utility named <command>srfsh</command> (surf
1514                                         shell). This is a command line diagnostic tool for testing and interacting with
1515                                         OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
1516                                         Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration
1517                                         file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
1518                                         See <xref linkend="serversideinstallation-testing"/> for further information.</para>
1519                                 </step>
1520                                 <step xml:id="serversideinstallation-opensrf-env">
1521                                         <title>Modify the OpenSRF Environment</title>
1522                                         <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
1523                                         <itemizedlist>
1524                                                 <listitem>
1525                                                         <para>As the <systemitem class="username">opensrf</systemitem> user,
1526                                                         modify the shell configuration file <filename>~/.bashrc</filename> for
1527                                                         user <systemitem class="username">opensrf</systemitem> by adding a Perl
1528                                                         environmental variable, then execute the shell configuration file to load
1529                                                         the new variables into your current environment.</para>
1530                                                         <screen>
1531                                                                 <userinput>
1532         # as the opensrf user:
1533         echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
1534         . ~/.bashrc</userinput>
1535                                                         </screen>
1536                                                         <note>In a multi-server environment, you must add any
1537                                                         modifications to <filename>~/.bashrc</filename> to the top of the file
1538                                                         <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &amp;&amp;
1539                                                         return </literal>. This will allow headless (scripted) logins to load the
1540                                                         correct environment.</note>
1541                                                 </listitem>
1542                                         </itemizedlist>
1543                                 </step>
1544                                 <step performance="optional">
1545                                         <title>(OPTIONAL) Enable and Disable Language Localizations</title>
1546                                         <para>You can load translations such as Armenian (hy-AM), Canadian French
1547                                         (fr-CA), and others into the database to complete the translations available in
1548                                         the OPAC and Staff Client. For further information, see
1549                                         <xref linkend="languagesandlocalization"/>.</para>
1550                                 </step>
1551                         </procedure>
1552                 </section>
1553                 <section xml:id="serversideinstallation-fedora">
1554                         <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
1555                                 <systemitem class="osname">Fedora 14</systemitem></title>
1556                         <indexterm>
1557                                 <primary>Linux</primary>
1558                                 <secondary>Fedora</secondary>
1559                         </indexterm>
1560                         <para>This section outlines the installation process for the latest stable version of
1561                         Evergreen on a <systemitem class="osname">Fedora 14</systemitem> system.
1562                         See <xref linkend="serversideinstallation-ubuntudebian"/> for description of a
1563                         similar installation on <systemitem class="osname">Ubuntu</systemitem> or
1564                         <systemitem class="osname">Debian</systemitem> systems.</para>
1565                         <para>In the following section you will download, unpack, install, configure and test the Evergreen
1566                         system, including the Evergreen server and the PostgreSQL database system. You will make several
1567                         configuration changes and adjustments to the software, including updates to configure the system
1568                         for your own locale, and some updates needed to work around a few known issues.</para>
1569                         <note>
1570                                 <para>The following steps have been tested on the x86 (32-bit) and x86_64
1571                                 (64-bit) architecture of a <systemitem class="osname">Fedora 14</systemitem>
1572                                 image as of 2011-01-27.</para>
1573                                 <para>In the following instructions, you are asked to perform certain steps as
1574                                 either the <systemitem class="username">root</systemitem> user, the
1575                                 <systemitem class="username">opensrf</systemitem> user, or the
1576                                 <systemitem class="username">postgres</systemitem> user.</para>
1577                                 <itemizedlist>
1578                                         <listitem>
1579                                                 <para><systemitem class="osname">Fedora</systemitem> -- To become the
1580                                                 <systemitem class="username">root</systemitem> user, issue the command
1581                                                 <command>su -</command> and enter the password of the
1582                                                 <systemitem class="username">root</systemitem> user.</para>
1583                                         </listitem>
1584                                 </itemizedlist>
1585                                 <para>To switch from the <systemitem class="username">root</systemitem> user to a
1586                                 different user, issue the command <command>su - USERNAME</command>. For example, to
1587                                 switch from the <systemitem class="username">root</systemitem> user to the
1588                                 <systemitem class="username">opensrf</systemitem> user, issue the command
1589                                 <command>su - opensrf</command>. Once you have become a non-root user, to become the
1590                                 <systemitem class="username">root</systemitem> user again, simply issue the command
1591                                 <command>exit</command>.</para>
1592                         </note>
1593                         <procedure>
1594                                 <step xml:id="serversideinstallation-opensrf-2.0">
1595                                         <title>Install OpenSRF</title>
1596                                         <para>Evergreen software is integrated with and depends on the Open Service
1597                                         Request Framework (OpenSRF) software system. For further information on
1598                                         installing, configuring and testing OpenSRF, see
1599                                         <xref linkend="serversideinstallation-opensrf-1.6.3"/>.</para>
1600                                         <para>Follow the steps outlined in that section and run the specified tests to
1601                                         ensure that OpenSRF is properly installed and configured. Do
1602                                         <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
1603                                         any further Evergreen installation steps until you have verified that OpenSRF
1604                                         has been successfully installed and tested.</para>
1605                                 </step>
1606                                 <step>
1607                                         <title>Download and Unpack Latest Evergreen Version</title>
1608                                         <para>The latest version of Evergreen can be found here:
1609                                         <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
1610                                         As the <systemitem class="username">opensrf</systemitem> user, change to
1611                                         the directory <filename class="directory">/home/opensrf</filename> then
1612                                         download and extract Evergreen. The new subdirectory
1613                                         <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename>
1614                                         will be created:</para>
1615                                         <screen>
1616                                                 <userinput>
1617         # as the opensrf user:
1618         cd /home/opensrf
1619         wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
1620         tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
1621                                         </screen>
1622                                 </step>
1623                                 <step xml:id="serversideinstallation-installprereq-2.0">
1624                                         <title>Install Prerequisites to Build Evergreen</title>
1625                                         <para>In this section you will install and configure a set of prerequisites that will be
1626                                         used later in <xref linkend="serversideinstallation-configure-2.0"/> and
1627                                         <xref linkend="serversideinstallation-compile-2.0"/> to build the Evergreen software
1628                                         using the <command>make</command> utility.</para>
1629                                         <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
1630                                         below to build the prerequisites from the software distribution that you just downloaded
1631                                         and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
1632                                         example with the keyword corresponding to the name of one of the
1633                                         <systemitem class="osname">Linux</systemitem> distributions listed in the following
1634                                         distribution list. For example, to install the prerequisites for
1635                                         <systemitem class="osname">Fedora 13</systemitem> or
1636                                         <systemitem class="osname">Fedora 14</systemitem>, you would enter the command:
1637                                         <command>make -f Open-ILS/src/extras/Makefile.install fedora13</command>.</para>
1638                                         <screen>
1639                                                 <userinput>
1640         # as the root user:
1641         cd /home/opensrf/Evergreen-ILS-2.0.4
1642         make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
1643                                         </screen>
1644                                 </step>
1645                                 <step performance="optional">
1646                                         <title>(OPTIONAL) Install the PostgreSQL Server</title>
1647                                         <indexterm>
1648                                                 <primary>databases</primary>
1649                                                 <secondary>PostgreSQL</secondary>
1650                                         </indexterm>
1651                                         <para>Since the PostgreSQL server is usually a standalone server in multi-server
1652                                         production systems, the prerequisite installer Makefile in the previous section
1653                                         (see <xref linkend="serversideinstallation-installprereq-2.0"/>)
1654                                         does not automatically install PostgreSQL. You must install the PostgreSQL server
1655                                         yourself, either on the same system as Evergreen itself or on another system.
1656                                         If your PostgreSQL server is on a different system, just skip this step.
1657                                         If your PostgreSQL server will be on the same system as your Evergreen
1658                                         software, you can install the required PostgreSQL server packages as described
1659                                         in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
1660                                         web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1661                                         for more information.</para>
1662                                         <note>
1663                                                 <para>PostgreSQL version 8.4 is the minimum supported version to work
1664                                                 with Evergreen 2.0. If you have an older version of PostgreSQL,
1665                                                 you should upgrade before installing Evergreen. To find your current version
1666                                                 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
1667                                                 user execute the command <command>psql</command>, then type
1668                                                 <userinput>SELECT version();</userinput> to get detailed information
1669                                                 about your version of PostgreSQL.</para>
1670                                         </note>
1671                                 </step>
1672                                 <step performance="optional">
1673                                         <title>Install Perl Modules on PostgreSQL Server</title>
1674                                         <para>If PostgreSQL is running on the same system as your Evergreen software,
1675                                         then the Perl modules will automatically be available. Just skip this step.
1676                                         Otherwise, continue if your PostgreSQL server is running on another system,
1677                                         and install several Perl modules there. As the
1678                                         <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1679                                         is installed, then install the following Perl modules:</para>
1680                                         <screen>
1681                                                 <userinput>
1682         yum install gcc
1683         perl -MCPAN -e shell
1684                 <prompt>cpan></prompt> install JSON::XS
1685                 <prompt>cpan></prompt> install MARC::Record
1686                 <prompt>cpan></prompt> install MARC::File::XML</userinput>
1687                                         </screen>
1688                                         <para>For more information on installing Perl Modules vist the official
1689                                         <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1690                                         <indexterm>
1691                                                 <primary>Perl</primary>
1692                                                 <secondary>CPAN</secondary>
1693                                         </indexterm>
1694                                 </step>
1695                                 <step xml:id="serversideinstallation-configure-2.0">
1696                                         <title>Configure Evergreen</title>
1697                                         <para>In this step you will use the <command>configure</command> and
1698                                         <command>make</command> utilities to configure Evergreen so it can be compiled
1699                                         and linked later in <xref linkend="serversideinstallation-compile-2.0"/>.</para>
1700                                         <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1701                                         the Evergreen build directory and execute these commands:</para>
1702                                         <screen>
1703                                                 <userinput>
1704         # as the opensrf user:
1705         cd /home/opensrf/Evergreen-ILS-2.0.4
1706         ./configure --prefix=/openils --sysconfdir=/openils/conf
1707         make</userinput>
1708                                         </screen>
1709                                 </step>
1710                                 <step xml:id="serversideinstallation-compile-2.0">
1711                                         <title>Compile, Link and Install Evergreen</title>
1712                                         <para>In this step you will actually compile, link and install Evergreen and the
1713                                         default Evergreen Staff Client.</para>
1714                                         <para>As the <systemitem class="username">root</systemitem> user, return to the
1715                                         Evergreen build directory and use the <command>make</command> utility as shown
1716                                         below:</para>
1717                                         <screen>
1718                                                 <userinput>
1719         # as the root user:
1720         cd /home/opensrf/Evergreen-ILS-2.0.4
1721         make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
1722                                         </screen>
1723                                         <para>The Staff Client will also be automatically built, but you must remember
1724                                         to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1725                                         Staff Client you will use to connect to the Evergreen server.</para>
1726                                         <para>The above commands will create a new subdirectory
1727                                         <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
1728                                         containing the Staff Client.</para>
1729                                         <para>To complete the Staff Client installation, as the
1730                                         <systemitem class="username">root</systemitem> user execute the following commands
1731                                         to create a symbolic link named <emphasis>server</emphasis> in the head of the
1732                                         Staff Client directory <filename class="directory">/openils/var/web/xul</filename>
1733                                         that points to the subdirectory <filename class="directory">/server</filename>
1734                                         of the new Staff Client build:</para>
1735                                         <screen>
1736                                                 <userinput>
1737         # as the root user:
1738         cd /openils/var/web/xul
1739         ln -sf rel_2_0_4/server server</userinput>
1740                                         </screen>
1741                                 </step>
1742                                 <step>
1743                                         <title>Copy the OpenSRF Configuration Files</title>
1744                                         <para>In this step you will replace some OpenSRF configuration files that you set up
1745                                         earlier in <xref linkend="serversideinstallation-opensrf-2.0"/> when you installed
1746                                         and tested OpenSRF.</para>
1747                                         <para>You must copy several example OpenSRF configuration files into place after first
1748                                         creating backup copies for troubleshooting purposes, then change all the file ownerships
1749                                         to <systemitem class="username">opensrf</systemitem>.
1750                                         As the <systemitem class="username">root</systemitem> user, execute the following
1751                                         commands:</para>
1752                                         <screen>
1753                                                 <userinput>
1754         # as the root user:
1755         cd /openils/conf
1756         cp opensrf.xml        opensrf.xml.BAK
1757         cp opensrf_core.xml      opensrf_core.xml.BAK
1758         cp opensrf.xml.example      opensrf.xml
1759         cp opensrf_core.xml.example opensrf_core.xml
1760         cp oils_web.xml.example     oils_web.xml
1761         chown -R opensrf:opensrf /openils/</userinput>
1762                                         </screen>
1763                                 </step>
1764                                 <step>
1765                                         <title>Create and Configure PostgreSQL Database</title>
1766                                         <indexterm>
1767                                                 <primary>databases</primary>
1768                                                 <secondary>PostgreSQL</secondary>
1769                                         </indexterm>
1770                                         <para>In this step you will create the Evergreen database. In the
1771                                         commands below, remember to adjust the path of the
1772                                         <emphasis role="bold">contrib</emphasis> repository to match your
1773                                         PostgreSQL server layout. For example, if you built PostgreSQL from
1774                                         source the path would be
1775                                         <filename class="directory">/usr/local/share/contrib</filename>
1776                                         , and if you installed the PostgreSQL 8.4 server packages on
1777                                         <systemitem class="osname">Ubuntu</systemitem>, the path would be
1778                                         <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1779                                         <substeps>
1780                                                 <step>
1781                                                         <title>Start the PostgreSQL service</title>
1782                                                         <para>As the <systemitem class="username">root</systemitem>
1783                                                         user on the PostgreSQL system, initialize the PostgreSQL cluster
1784                                                         and start the PostgreSQL service:</para>
1785                                                         <screen>
1786                                                                 <userinput>
1787         # as the root user:
1788         service initdb postgresql
1789         /etc/init.d/postgresql start</userinput>
1790                                                         </screen>
1791                                                 </step>
1792                                                 <step>
1793                                                         <title>Create and configure the database</title>
1794                                                         <para>As the <systemitem class="username">postgres</systemitem>
1795                                                         user on the PostgreSQL system create the PostgreSQL database,
1796                                                         then set some internal paths:</para>
1797                                                         <screen>
1798                                                                 <userinput>
1799         # as the postgres user:
1800         createdb evergreen -E UTF8 -T template0
1801         createlang plperl   evergreen
1802         createlang plperlu  evergreen
1803         createlang plpgsql  evergreen</userinput>
1804                                                         </screen>
1805                                                         <para>Continue as the <systemitem class="username">postgres</systemitem>
1806                                                         user and execute the SQL scripts as shown below (remember to adjust the
1807                                                         paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1808                                                         your installed PostgreSQL version, for example
1809                                                         <literal>"8.4"</literal>).</para>
1810                                                         <screen>
1811                                                                 <userinput>
1812         # as the postgres user:
1813         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1814         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
1815         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
1816                                                         </screen>
1817                                                 </step>
1818                                                 <step xml:id="serversideinstallation-postgresqlcreateuser-2.0">
1819                                                         <title>Create <systemitem class="username">evergreen</systemitem>
1820                                                                 PostgreSQL user</title>
1821                                                         <para>As the <systemitem class="username">postgres</systemitem>
1822                                                         user on the PostgreSQL system, create a new PostgreSQL user
1823                                                         named <systemitem class="username">evergreen</systemitem> and
1824                                                         assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1825                                                         with an appropriate new password):</para>
1826                                                         <screen>
1827                                                                 <userinput>
1828         # as the postgres user:
1829         createuser -P -s evergreen</userinput>
1830                                                                 <computeroutput>
1831         Enter password for new role: <userinput>NEWPASSWORD</userinput>
1832         Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1833                                                         </screen>
1834                                                 </step>
1835                                                 <step>
1836                                                         <title>Enable IPv4 and IPv6 connections</title>
1837                                                         <para>As the root user, enable IPv4 and IPv6 connections to the
1838                                                         PostgreSQL server. For a single-server instance, enable
1839                                                         password-protected connections from the Evergreen user to the
1840                                                         Evergreen database on localhost by adding the following lines to
1841                                                         <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
1842                                                         <screen>
1843                                                                 <userinput>
1844         # as the root user:
1845
1846         # IPv4 local connections:
1847         host    evergreen     evergreen  127.0.0.1/32     md5
1848         # IPv6 local connections:
1849         host    evergreen     evergreen  ::1/128               md5</userinput>
1850                                                         </screen>
1851                                                         <para>Then, as the root user, restart the PostgreSQL server to
1852                                                         make that configuration take effect:</para>
1853                                                         <screen>
1854                                                                 <userinput>
1855         # as the root user:
1856         /etc/init.d/postgresql restart</userinput>
1857                                                         </screen>
1858                                                 </step>
1859                                                 <step>
1860                                                         <title>Create database schema</title>
1861                                                         <para>In this step you will create the database schema and configure your
1862                                                         system with the corresponding database authentication details for the
1863                                                         <emphasis>evergreen</emphasis> database user that you just created in
1864                                                         <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.</para>
1865                                                         <para>As the <systemitem class="username">root</systemitem> user, enter
1866                                                         the following commands and replace <emphasis>HOSTNAME, PORT,
1867                                                         PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1868                                                         values:</para>
1869                                                         <screen>
1870                                                                 <userinput>
1871         # as the root user:
1872         cd /home/opensrf/Evergreen-ILS-2.0.4
1873         perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1874         --service all --create-schema --create-offline \
1875         --hostname HOSTNAME --port PORT \
1876         --user evergreen --password PASSWORD \
1877         --database DATABASENAME --admin-user ADMIN-USER \
1878         --admin-pass ADMIN-PASSWORD </userinput>
1879                                                         </screen>
1880                                                         <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1881                                                         <emphasis role="bold">localhost</emphasis> and
1882                                                         <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.