Made three small grammar fixes inside the EG 1.6 serveradministration.xml file
[working/Evergreen.git] / 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-2.0.0">
91                         <indexterm>
92                                 <primary>OpenSRF</primary>
93                                 <secondary>installation</secondary>
94                         </indexterm>
95                         <title>Installing OpenSRF 2.0.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-2.0.0.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-2.0.0</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-2.0.0.tar.gz
178         tar zxf opensrf-2.0.0.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-2.0.0
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-2.0.0
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-2.0.0
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-2.0.0"/>.</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.7.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.7</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.7.tar.gz
899         tar zxf Evergreen-ILS-2.0.7.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 following
913                                         distribution list.
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.7
921         make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
922                                         </screen>
923                                 </step>
924                                 <step performance="optional">
925                                         <title>(OPTIONAL) Install the PostgreSQL Server</title>
926                                         <indexterm>
927                                                 <primary>databases</primary>
928                                                 <secondary>PostgreSQL</secondary>
929                                         </indexterm>
930                                         <para>Since the PostgreSQL server is usually a standalone server in multi-server
931                                         production systems, the prerequisite installer Makefile in the previous section
932                                         (see <xref linkend="serversideinstallation-installprereq"/>)
933                                         does not automatically install PostgreSQL. You must install the PostgreSQL server
934                                         yourself, either on the same system as Evergreen itself or on another system.
935                                         If your PostgreSQL server is on a different system, just skip this step.
936                                         If your PostgreSQL server will be on the same system as your Evergreen
937                                         software, you can install the required PostgreSQL server packages as described
938                                         in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official 
939                                         web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
940                                         for more information.</para>
941                                         <note>
942                                                 <para>PostgreSQL version 8.4 is the minimum supported version to work 
943                                                 with Evergreen 2.0. If you have an older version of PostgreSQL, 
944                                                 you should upgrade before installing Evergreen. To find your current version 
945                                                 of PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
946                                                 user execute the command <command>psql</command>, then type 
947                                                 <userinput>SELECT version();</userinput> to get detailed information 
948                                                 about your version of PostgreSQL.</para>
949                                         </note>
950                                 </step>
951                                 <step performance="optional">
952                                         <title>Install Perl Modules on PostgreSQL Server</title>
953                                         <para>If PostgreSQL is running on the same system as your Evergreen software,
954                                         then the Perl modules will automatically be available. Just skip this step.
955                                         Otherwise, continue if your PostgreSQL server is running on another system
956                                         and install several Perl modules there. As the 
957                                         <systemitem class="username">root</systemitem> user, ensure the gcc compiler
958                                         is installed, then install the following Perl modules:</para>
959                                         <screen>
960                                                 <userinput>
961         aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
962         perl -MCPAN -e shell
963                 <prompt>cpan></prompt> Business::ISBN
964                 <prompt>cpan></prompt> install JSON::XS
965                 <prompt>cpan></prompt> Library::CallNumber::LC
966                 <prompt>cpan></prompt> install MARC::Record
967                 <prompt>cpan></prompt> install MARC::File::XML
968                 <prompt>cpan></prompt> cpan UUID::Tiny</userinput>
969                                         </screen>
970                                         <para>For more information on installing Perl Modules vist the official
971                                         <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
972                                         <indexterm>
973                                                 <primary>Perl</primary>
974                                                 <secondary>CPAN</secondary>
975                                         </indexterm>
976                                 </step>
977                                 <step>
978                                         <title>Update the System Dynamic Library Path</title>
979                                         <para>You must update the system dynamic library path to force your system to recognize
980                                         the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
981                                         do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
982                                         containing two new library paths, then run the command <command>ldconfig</command> to
983                                         automatically read the file and modify the system dynamic library path:</para>
984                                         <screen>
985                                                 <userinput>
986         # as the root user:
987         echo "/usr/local/lib"      > /etc/ld.so.conf.d/osrf.conf
988         echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
989         ldconfig</userinput>
990                                         </screen>
991                                 </step>
992                                 <step performance="optional">
993                                         <title>Restart the PostgreSQL Server</title>
994                                         <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
995                                         the <systemitem class="username">root</systemitem> user you must restart
996                                         PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
997                                         running on another system, you may skip this step.
998                                         As the <systemitem class="username">opensrf</systemitem> user,
999                                         execute the following command (remember to replace
1000                                         <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
1001                                         for example <literal>8.4</literal>):</para>
1002                                         <screen>
1003                                                 <userinput>
1004         # as the opensrf user:
1005         /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
1006                                         </screen>
1007                                 </step>
1008                                 <step xml:id="serversideinstallation-configure">
1009                                         <title>Configure Evergreen</title>
1010                                         <para>In this step you will use the <command>configure</command> and
1011                                         <command>make</command> utilities to configure Evergreen so it can be compiled
1012                                         and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
1013                                         <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1014                                         the Evergreen build directory and execute these commands:</para>
1015                                         <screen>
1016                                                 <userinput>
1017         # as the opensrf user:
1018         cd /home/opensrf/Evergreen-ILS-2.0.7
1019         ./configure --prefix=/openils --sysconfdir=/openils/conf
1020         make</userinput>
1021                                         </screen>
1022                                 </step>
1023                                 <step xml:id="serversideinstallation-compile">
1024                                         <title>Compile, Link and Install Evergreen</title>
1025                                         <para>In this step you will actually compile, link and install Evergreen and the 
1026                                         default Evergreen Staff Client.</para>
1027                                         <para>As the <systemitem class="username">root</systemitem> user, return to the
1028                                         Evergreen build directory and use the <command>make</command> utility as shown
1029                                         below:</para>
1030                                         <screen>
1031                                                 <userinput>
1032         # as the root user:
1033         cd /home/opensrf/Evergreen-ILS-2.0.7
1034         make STAFF_CLIENT_BUILD_ID=rel_2_0_7 install</userinput>
1035                                         </screen>
1036                                         <para>The Staff Client will also be automatically built, but you must remember
1037                                         to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the 
1038                                         Staff Client you will use to connect to the Evergreen server.</para>
1039                                         <para>The above commands will create a new subdirectory
1040                                         <filename class="directory">/openils/var/web/xul/rel_2_0_7</filename> 
1041                                         containing the Staff Client.</para>
1042                                         <para>To complete the Staff Client installation, as the
1043                                         <systemitem class="username">root</systemitem> user execute the following commands to
1044                                         create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
1045                                         directory <filename class="directory">/openils/var/web/xul</filename> that points to the
1046                                         subdirectory <filename class="directory">/server</filename> of the new Staff Client
1047                                         build:</para>
1048                                         <screen>
1049                                                 <userinput>
1050         # as the root user:
1051         cd /openils/var/web/xul
1052         ln -sf rel_2_0_7/server server</userinput>
1053                                         </screen>
1054                                 </step>
1055                                 <step>
1056                                         <title>Copy the OpenSRF Configuration Files</title>
1057                                         <para>In this step you will replace some OpenSRF configuration files that you set up in
1058                                         <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
1059                                         tested OpenSRF.</para>
1060                                         <para>You must copy several example OpenSRF configuration files into place after first
1061                                         creating backup copies for troubleshooting purposes, then change all the file ownerships
1062                                         to <systemitem class="username">opensrf</systemitem>.
1063                                         As the <systemitem class="username">root</systemitem> user, execute the following
1064                                         commands:</para>
1065                                         <screen>
1066                                                 <userinput>
1067         # as the root user:
1068         cd /openils/conf
1069         cp opensrf.xml        opensrf.xml.BAK
1070         cp opensrf_core.xml      opensrf_core.xml.BAK
1071         cp opensrf.xml.example      opensrf.xml
1072         cp opensrf_core.xml.example opensrf_core.xml
1073         cp oils_web.xml.example     oils_web.xml
1074         chown -R opensrf:opensrf /openils/</userinput>
1075                                         </screen>
1076                                 </step>
1077                                 <step>
1078                                         <title>Create and Configure PostgreSQL Database</title>
1079                                         <indexterm>
1080                                                 <primary>databases</primary>
1081                                                 <secondary>PostgreSQL</secondary>
1082                                         </indexterm>
1083                                         <para>In this step you will create the Evergreen database. In the commands
1084                                         below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
1085                                         repository to match your PostgreSQL server
1086                                         layout. For example, if you built PostgreSQL from source the path would be
1087                                         <filename class="directory">/usr/local/share/contrib</filename> , and if you
1088                                         installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
1089                                         the path would be 
1090                                         <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1091                                         <substeps>
1092                                                 <step>
1093                                                         <title>Create and configure the database</title>
1094                                                         <para>As the <systemitem class="username">postgres</systemitem>
1095                                                         user on the PostgreSQL system create the PostgreSQL database,
1096                                                         then set some internal paths:</para>
1097                                                         <screen>
1098                                                                 <userinput>
1099         # as the postgres user:
1100         createdb evergreen -E UTF8 -T template0
1101         createlang plperl   evergreen
1102         createlang plperlu  evergreen
1103         createlang plpgsql  evergreen</userinput>
1104                                                         </screen>
1105                                                         <para>Continue as the <systemitem class="username">postgres</systemitem> 
1106                                                         user and execute the SQL scripts as shown below (remember to adjust the
1107                                                         paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1108                                                         your installed PostgreSQL version, for example
1109                                                         <literal>"8.4"</literal>).</para>
1110                                                         <screen>
1111                                                                 <userinput>
1112         # as the postgres user:
1113         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1114         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
1115         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
1116                                                         </screen>
1117                                                 </step>
1118                                                 <step xml:id="serversideinstallation-postgresqlcreateuser">
1119                                                         <title>Create <systemitem class="username">evergreen</systemitem>
1120                                                                 PostgreSQL user</title>
1121                                                         <para>As the <systemitem class="username">postgres</systemitem>
1122                                                         user on the PostgreSQL system, create a new PostgreSQL user
1123                                                         named <systemitem class="username">evergreen</systemitem> and
1124                                                         assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1125                                                         with an appropriate new password):</para>
1126                                                         <screen>
1127                                                                 <userinput>
1128         # as the postgres user:
1129         createuser -P -s evergreen</userinput>
1130                                                                 <computeroutput>
1131         Enter password for new role: <userinput>NEWPASSWORD</userinput>
1132         Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1133                                                         </screen>
1134                                                 </step>
1135                                                 <step>
1136                                                         <title>Create database schema</title>
1137                                                         <para>In this step you will create the database schema and configure your
1138                                                         system with the corresponding database authentication details for the
1139                                                         <emphasis>evergreen</emphasis> database user that you just created in
1140                                                         <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
1141                                                         <para>As the <systemitem class="username">root</systemitem> user, enter
1142                                                         the following commands and replace <emphasis>HOSTNAME, PORT,
1143                                                         PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1144                                                         values:</para>
1145                                                         <screen>
1146                                                                 <userinput>
1147         # as the root user:
1148         cd /home/opensrf/Evergreen-ILS-2.0.7
1149         perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1150         --service all --create-schema --create-offline \
1151         --hostname HOSTNAME --port PORT \
1152         --user evergreen --password PASSWORD \
1153         --database DATABASENAME --admin-user ADMIN-USER \ 
1154         --admin-pass ADMIN-PASSWORD </userinput>
1155                                                         </screen>
1156                                                         <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1157                                                         <emphasis role="bold">localhost</emphasis> and
1158                                                         <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1159                                                         Of course, values for <emphasis>PASSWORD</emphasis> and
1160                                                         <emphasis>DATABASENAME</emphasis> must match the values you used in 
1161                                                         <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
1162                                                         The <option>admin-user</option> and <option>admin-pass</option> options will 
1163                                                         specify the Evergreen administrator account's username and password. This was 
1164                                                         changed for security reasons, it was previously admin/open-ils</para>
1165                                                         <para>As the command executes, you may see warnings similar to:
1166                                                         <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1167                                                         you may see one warning per schema) but they can be safely ignored.</para>
1168                                                         <note>If you are entering the above command on a single line, do not
1169                                                         include the <literal>\</literal> (backslash) characters. If you are using
1170                                                         the <command>bash</command> shell, these should only be used at the end of
1171                                                         a line at a <command>bash</command> prompt to indicate that the command is
1172                                                         continued on the next line.</note>
1173                                                 </step>
1174                                         </substeps>
1175                                 </step>
1176                                 <step>
1177                                         <title>Configure the Apache web server</title>
1178                                         <indexterm>
1179                                                 <primary>web server</primary>
1180                                                 <secondary>Apache</secondary>
1181                                         </indexterm>
1182                                         <para>In this step you will configure the Apache web server to support Evergreen
1183                                         software.</para>
1184                                         <para>First, you must enable some built-in Apache modules and install some
1185                                         additional Apache configuration files. Then you will create a new Security
1186                                         Certificate. Finally, you must make several changes to the Apache configuration
1187                                         file.</para>
1188                                         <substeps>
1189                                                 <step>
1190                                                         <title>Enable the required Apache Modules</title>
1191                                                         <para>As the <systemitem class="username">root</systemitem>
1192                                                         user, enable some modules in the Apache server, then copy the
1193                                                         new configuration files to the Apache server directories:</para>
1194                                                         <indexterm>
1195                                                                 <primary>Apache modules</primary>
1196                                                         </indexterm>
1197                                                         <screen>
1198                                                                 <userinput>
1199         # as the root user:
1200         a2enmod ssl     # enable mod_ssl
1201         a2enmod rewrite # enable mod_rewrite
1202         a2enmod expires # enable mod_expires</userinput>
1203                                                         </screen>
1204                                                         <para>As the commands execute, you may see warnings similar to:
1205                                                         <literal>Module SOMEMODULE already enabled</literal> but you can
1206                                                         safely ignore them.</para>
1207                                                 </step>
1208                                                 <step>
1209                                                         <title>Copy Apache configuration files</title>
1210                                                         <para>You must copy the Apache configuration files from the
1211                                                         Evergreen installation directory to the Apache directory. As the
1212                                                         <systemitem class="username">root</systemitem> user, perform the
1213                                                         following commands:</para>
1214                                                         <screen>
1215                                                                 <userinput>
1216         # as the root user:
1217         cd /home/opensrf/Evergreen-ILS-2.0.7
1218         cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/
1219         cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/
1220         cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>
1221                                                         </screen>
1222                                                 </step>
1223                                                 <step xml:id="serversideinstallation-createsslcertificate">
1224                                                         <title>Create a Security Certificate</title>
1225                                                         <para>In this step you will create a new Security Certificate (SSL Key)
1226                                                         for the Apache server using the <command>openssl</command> command. For a
1227                                                         public production server you must configure or purchase a signed SSL
1228                                                         certificate, but for now you can just use a self-signed certificate and
1229                                                         accept the warnings in the Staff Client and browser during testing and
1230                                                         development. As the <systemitem class="username">root</systemitem> user,
1231                                                         perform the following commands:</para>
1232                                                         <screen>
1233                                                                 <userinput>
1234         # as the root user:
1235         mkdir /etc/apache2/ssl
1236         cd /etc/apache2/ssl
1237         openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1238                                                         </screen>
1239                                                         <para>You will be prompted for several items of information; enter
1240                                                         the appropriate information for each item. The new files
1241                                                         <filename>server.crt</filename> and <filename>server.key</filename> will
1242                                                         be created in the directory 
1243                                                         <filename class="directory">/etc/apache2/ssl</filename> .</para>
1244                                                         <note>This step generates a self-signed SSL certificate. You must install
1245                                                         a proper SSL certificate for a public production system to avoid warning
1246                                                         messages when users login to their account through the OPAC or when staff
1247                                                         login through the Staff Client. For further information on
1248                                                         installing a proper SSL certificate, see 
1249                                                         <xref linkend="serversideinstallation-ssl"/>.</note>
1250                                                 </step>
1251                                                 <step xml:id="serversideinstallation-modify-apache">
1252                                                         <title>Update Apache configuration files</title>
1253                                                         <para>You must make several changes to an Apache configuration file.</para>
1254                                                         <para>As the <systemitem class="username">root</systemitem> user
1255                                                         edit the file <filename>/etc/apache2/sites-available/eg.conf</filename> 
1256                                                         and make the following changes:</para>
1257                                                         <itemizedlist>
1258                                                                 <listitem>
1259                                                                         <para>In the section
1260                                                                         <literal>&lt;Directory "/openils/var/cgi-bin"></literal>
1261                                                                         replace the line:</para>
1262                                                                         <literal>Allow from 10.0.0.0/8</literal>
1263                                                                         <para>with the line:</para>
1264                                                                         <literal>Allow from all</literal>
1265                                                                         <warning>This change allows access to your configuration
1266                                                                         CGI scripts from any workstation on any network. This is
1267                                                                         only a temporary change to expedite testing and should be
1268                                                                         removed after you have finished and successfully tested
1269                                                                         the Evergreen installation. See 
1270                                                                         <xref linkend="serversideinstallation-postinstallation"/> 
1271                                                                         for further details on removing this change after the
1272                                                                         Evergreen installation is complete.
1273                                                                         </warning>
1274                                                                 </listitem>
1275                                                                 <listitem>
1276                                                                         <para>Comment out the line:</para>
1277                                                                         <literal>Listen 443</literal>
1278                                                                         <para>since it conflicts with the same declaration in 
1279                                                                         the configuration file:</para>
1280                                                                         <para><filename>/etc/apache2/ports.conf</filename>.</para>
1281                                                                 </listitem>
1282                                                                 <listitem>
1283                                                                         <para>The following updates are needed to allow the logs
1284                                                                         to function properly, but it may break other Apache
1285                                                                         applications on your server:</para>
1286                                                                         <para>Edit the Apache configuration file and
1287                                                                         change the lines:</para>
1288                                                                         <screen>
1289                                                                                 <userinput>export APACHE_RUN_USER=www-data</userinput>
1290                                                                                 <userinput>export APACHE_RUN_GROUP=www-data</userinput>
1291                                                                         </screen>
1292                                                                         <para>to instead read:</para>
1293                                                                         <screen>
1294                                                                                 <userinput>
1295         export APACHE_RUN_USER=opensrf
1296         export APACHE_RUN_GROUP=opensrf</userinput>
1297                                                                         </screen>
1298                                                                 </listitem>
1299                                                                 <listitem>
1300                                                                         <para>As the 
1301                                                                         <systemitem class="username">root</systemitem> user,
1302                                                                         edit the Apache configuration file
1303                                                                         <filename>/etc/apache2/apache2.conf</filename> and
1304                                                                         modify the value for <literal>KeepAliveTimeout</literal>
1305                                                                         and <literal>MaxKeepAliveRequests</literal> to match
1306                                                                         the following:</para>
1307                                                                         <screen>
1308                                                                                 <userinput>
1309         KeepAliveTimeout       1
1310         MaxKeepAliveRequests 100</userinput>
1311                                                                         </screen>
1312                                                                 </listitem>
1313                                                                 <listitem>
1314                                                                         <para>Further configuration changes to Apache may be
1315                                                                         necessary for busy systems. These changes increase the
1316                                                                         number of Apache server processes that are started to
1317                                                                         support additional browser connections.</para>
1318                                                                         <para>As the 
1319                                                                         <systemitem class="username">root</systemitem> user, 
1320                                                                         edit the Apache configuration file
1321                                                                         <filename>/etc/apache2/apache2.conf</filename>, locate 
1322                                                                         and modify the section related to <emphasis>prefork
1323                                                                         configuration</emphasis> to suit the load on your
1324                                                                         system:</para>
1325                                                                         <programlisting language="xml"><![CDATA[
1326 <IfModule mpm_prefork_module>
1327    StartServers    20
1328    MinSpareServers       5
1329    MaxSpareServers      15
1330    MaxClients       150
1331    MaxRequestsPerChild 10000
1332 </IfModule>
1333 ]]></programlisting>
1334                                                                 </listitem>
1335                                                         </itemizedlist>
1336                                                 </step>
1337                                                 <step>
1338                                                         <title>Enable the Evergreen web site</title>
1339                                                         <para>Finally, you must enable the Evergreen web site. As the
1340                                                         <systemitem class="username">root</systemitem> user, execute the
1341                                                         following Apache configuration commands to disable the default
1342                                                         <emphasis>It Works</emphasis> web page and enable the Evergreen
1343                                                         web site, and then restart the Apache server:</para>
1344                                                         <screen>
1345                                                                 <userinput>
1346         # as the root user:
1347         # disable/enable web sites
1348         a2dissite default
1349         a2ensite eg.conf
1350         # restart the server
1351         /etc/init.d/apache2 reload</userinput>
1352                                                         </screen>
1353                                                 </step>
1354                                         </substeps>
1355                                 </step>
1356                                 <step xml:id="serversideinstallation-opensrf-config">
1357                                         <title>Update the OpenSRF Configuration File</title>
1358                                         <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1359                                         OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1360                                         to update the Jabber usernames and passwords, and to specify the domain from
1361                                         which we will accept and to which we will make connections.</para>
1362                                         <para>If you are installing Evergreen on a single server and using the
1363                                         <systemitem class="domainname">private.localhost</systemitem> / 
1364                                         <systemitem class="domainname">public.localhost</systemitem> domains, 
1365                                         these will already be set to the correct values. Otherwise, search and replace
1366                                         to match your customized values.</para>
1367                                         <para>The left-hand side of  <xref linkend="serversideinstallation-xpath-table-2"/>
1368                                         shows common XPath syntax to indicate the approximate position within the XML
1369                                         file that needs changes. The right-hand side of the table shows the replacement
1370                                         values:</para>
1371                                         <table xml:id="serversideinstallation-xpath-table-2">
1372                                                 <?dbfo keep-together="always" ?>
1373                                                 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
1374                                                 <tgroup align="left" cols="2" colsep="1" rowsep="1">
1375                                                         <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
1376                                                         <colspec colname="Value" colnum="2" colwidth="2.0*"/>
1377                                                         <thead>
1378                                                                 <row>
1379                                                                         <entry>XPath location</entry>
1380                                                                         <entry>Value</entry>
1381                                                                 </row>
1382                                                         </thead>
1383                                                         <tbody>
1384                                                                 <row>
1385                                                                         <entry>/config/opensrf/username</entry>
1386                                                                         <entry>
1387                                                                                 <systemitem class="username">opensrf</systemitem>
1388                                                                         </entry>
1389                                                                 </row>
1390                                                                 <row>
1391                                                                         <entry>/config/opensrf/passwd </entry>
1392                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
1393                                                                         password for
1394                                                                         <systemitem class="username">opensrf</systemitem> user
1395                                                                         </entry>
1396                                                                 </row>
1397                                                                 <row>
1398                                                                         <entry>/config/gateway/username</entry>
1399                                                                         <entry>
1400                                                                                 <systemitem class="username">opensrf</systemitem>
1401                                                                         </entry>
1402                                                                 </row>
1403                                                                 <row>
1404                                                                         <entry>/config/gateway/passwd</entry>
1405                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
1406                                                                         password for
1407                                                                         <systemitem class="username">opensrf</systemitem> user
1408                                                                         </entry>
1409                                                                 </row>
1410                                                                 <row>
1411                                                                         <entry>/config/routers/router/transport/username,
1412                                                                         first entry where server == public.localhost</entry>
1413                                                                         <entry>
1414                                                                                 <systemitem class="username">router</systemitem>
1415                                                                         </entry>
1416                                                                 </row>
1417                                                                 <row>
1418                                                                         <entry>/config/routers/router/transport/password,
1419                                                                         first entry where server == public.localhost</entry>
1420                                                                         <entry><systemitem class="domainname">public.localhost</systemitem>
1421                                                                         password for
1422                                                                         <systemitem class="username">router</systemitem> user
1423                                                                         </entry>
1424                                                                 </row>
1425                                                                 <row>
1426                                                                         <entry>/config/routers/router/transport/username,
1427                                                                         second entry where server == private.localhost</entry>
1428                                                                         <entry>
1429                                                                                 <systemitem class="username">router</systemitem>
1430                                                                         </entry>
1431                                                                 </row>
1432                                                                 <row>
1433                                                                         <entry>/config/routers/router/transport/password,
1434                                                                         second entry where server == private.localhost</entry>
1435                                                                         <entry><systemitem class="domainname">private.localhost</systemitem>
1436                                                                         password for
1437                                                                         <systemitem class="username">router</systemitem> user
1438                                                                         </entry>
1439                                                                 </row>
1440                                                         </tbody>
1441                                                 </tgroup>
1442                                         </table>
1443                                 </step>
1444                                 <step performance="optional">
1445                                         <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
1446                                         <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
1447                                         software installation automatically created a utility named <command>srfsh</command> (surf
1448                                         shell). This is a command line diagnostic tool for testing and interacting with
1449                                         OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
1450                                         Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration 
1451                                         file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
1452                                         See <xref linkend="serversideinstallation-testing"/> for further information.</para>
1453                                 </step>
1454                                 <step xml:id="serversideinstallation-opensrf-env">
1455                                         <title>Modify the OpenSRF Environment</title>
1456                                         <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
1457                                         <itemizedlist>
1458                                                 <listitem>
1459                                                         <para>As the <systemitem class="username">opensrf</systemitem> user,
1460                                                         modify the shell configuration file <filename>~/.bashrc</filename> for
1461                                                         user <systemitem class="username">opensrf</systemitem> by adding a Perl
1462                                                         environmental variable, then execute the shell configuration file to load
1463                                                         the new variables into your current environment.</para>
1464                                                         <screen>
1465                                                                 <userinput>
1466         # as the opensrf user:
1467         echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
1468         . ~/.bashrc</userinput>
1469                                                         </screen>
1470                                                         <note>In a multi-server environment, you must add any
1471                                                         modifications to <filename>~/.bashrc</filename> to the top of the file
1472                                                         <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &amp;&amp;
1473                                                         return </literal>. This will allow headless (scripted) logins to load the
1474                                                         correct environment.</note>
1475                                                 </listitem>
1476                                         </itemizedlist>
1477                                 </step>
1478                                 <step performance="optional">
1479                                         <title>(OPTIONAL) Enable and Disable Language Localizations</title>
1480                                         <para>You can load translations such as Armenian (hy-AM), Canadian French
1481                                         (fr-CA), and others into the database to complete the translations available in
1482                                         the OPAC and Staff Client. For further information, see
1483                                         <xref linkend="languagesandlocalization"/>.</para>
1484                                 </step>
1485                         </procedure>
1486                 </section>
1487                 <section xml:id="serversideinstallation-fedora">
1488                         <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
1489                                 <systemitem class="osname">Fedora 14</systemitem></title>
1490                         <indexterm>
1491                                 <primary>Linux</primary>
1492                                 <secondary>Fedora</secondary>
1493                         </indexterm>
1494                         <para>This section outlines the installation process for the latest stable version of
1495                         Evergreen on a <systemitem class="osname">Fedora 14</systemitem> system.  
1496                         See <xref linkend="serversideinstallation-ubuntudebian"/> for description of a 
1497                         similar installation on <systemitem class="osname">Ubuntu</systemitem> or 
1498                         <systemitem class="osname">Debian</systemitem> systems.</para>
1499                         <para>In the following section you will download, unpack, install, configure and test the Evergreen
1500                         system, including the Evergreen server and the PostgreSQL database system. You will make several
1501                         configuration changes and adjustments to the software, including updates to configure the system
1502                         for your own locale, and some updates needed to work around a few known issues.</para>
1503                         <note>
1504                                 <para>The following steps have been tested on the x86 (32-bit) and x86_64
1505                                 (64-bit) architecture of a <systemitem class="osname">Fedora 14</systemitem>
1506                                 image as of 2011-01-27.</para>
1507                                 <para>In the following instructions, you are asked to perform certain steps as 
1508                                 either the <systemitem class="username">root</systemitem> user, the 
1509                                 <systemitem class="username">opensrf</systemitem> user, or the 
1510                                 <systemitem class="username">postgres</systemitem> user.</para>
1511                                 <itemizedlist>
1512                                         <listitem>
1513                                                 <para><systemitem class="osname">Fedora</systemitem> -- To become the
1514                                                 <systemitem class="username">root</systemitem> user, issue the command
1515                                                 <command>su -</command> and enter the password of the 
1516                                                 <systemitem class="username">root</systemitem> user.</para>
1517                                         </listitem>
1518                                 </itemizedlist>
1519                                 <para>To switch from the <systemitem class="username">root</systemitem> user to a
1520                                 different user, issue the command <command>su - USERNAME</command>. For example, to
1521                                 switch from the <systemitem class="username">root</systemitem> user to the 
1522                                 <systemitem class="username">opensrf</systemitem> user, issue the command 
1523                                 <command>su - opensrf</command>. Once you have become a non-root user, to become the
1524                                 <systemitem class="username">root</systemitem> user again, simply issue the command
1525                                 <command>exit</command>.</para>
1526                         </note>
1527                         <procedure>
1528                                 <step xml:id="serversideinstallation-opensrf-2.0">
1529                                         <title>Install OpenSRF</title>
1530                                         <para>Evergreen software is integrated with and depends on the Open Service
1531                                         Request Framework (OpenSRF) software system. For further information on
1532                                         installing, configuring and testing OpenSRF, see 
1533                                         <xref linkend="serversideinstallation-opensrf-2.0.0"/>.</para>
1534                                         <para>Follow the steps outlined in that section and run the specified tests to
1535                                         ensure that OpenSRF is properly installed and configured. Do 
1536                                         <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
1537                                         any further Evergreen installation steps until you have verified that OpenSRF
1538                                         has been successfully installed and tested.</para>
1539                                 </step>
1540                                 <step>
1541                                         <title>Download and Unpack Latest Evergreen Version</title>
1542                                         <para>The latest version of Evergreen can be found here:
1543                                         <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz"></ulink> .
1544                                         As the <systemitem class="username">opensrf</systemitem> user, change to
1545                                         the directory <filename class="directory">/home/opensrf</filename> then 
1546                                         download and extract Evergreen. The new subdirectory
1547                                         <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.7</filename> 
1548                                         will be created:</para>
1549                                         <screen>
1550                                                 <userinput>
1551         # as the opensrf user:
1552         cd /home/opensrf
1553         wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz
1554         tar zxf Evergreen-ILS-2.0.7.tar.gz</userinput>
1555                                         </screen>
1556                                 </step>
1557                                 <step xml:id="serversideinstallation-installprereq-2.0">
1558                                         <title>Install Prerequisites to Build Evergreen</title>
1559                                         <para>In this section you will install and configure a set of prerequisites that will be
1560                                         used later in <xref linkend="serversideinstallation-configure-2.0"/> and 
1561                                         <xref linkend="serversideinstallation-compile-2.0"/> to build the Evergreen software 
1562                                         using the <command>make</command> utility.</para>
1563                                         <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
1564                                         below to build the prerequisites from the software distribution that you just downloaded
1565                                         and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
1566                                         example with the keyword corresponding to the name of one of the 
1567                                         <systemitem class="osname">Linux</systemitem> distributions listed in the following
1568                                         distribution list. For example, to install the prerequisites for
1569                                         <systemitem class="osname">Fedora 13</systemitem> or
1570                                         <systemitem class="osname">Fedora 14</systemitem>, you would enter the command:
1571                                         <command>make -f Open-ILS/src/extras/Makefile.install fedora13</command>.</para>
1572                                         <screen>
1573                                                 <userinput>
1574         # as the root user:
1575         cd /home/opensrf/Evergreen-ILS-2.0.7
1576         make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
1577                                         </screen>
1578                                 </step>
1579                                 <step performance="optional">
1580                                         <title>(OPTIONAL) Install the PostgreSQL Server</title>
1581                                         <indexterm>
1582                                                 <primary>databases</primary>
1583                                                 <secondary>PostgreSQL</secondary>
1584                                         </indexterm>
1585                                         <para>Since the PostgreSQL server is usually a standalone server in multi-server
1586                                         production systems, the prerequisite installer Makefile in the previous section
1587                                         (see <xref linkend="serversideinstallation-installprereq-2.0"/>)
1588                                         does not automatically install PostgreSQL. You must install the PostgreSQL server
1589                                         yourself, either on the same system as Evergreen itself or on another system.
1590                                         If your PostgreSQL server is on a different system, just skip this step.
1591                                         If your PostgreSQL server will be on the same system as your Evergreen
1592                                         software, you can install the required PostgreSQL server packages as described
1593                                         in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official 
1594                                         web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1595                                         for more information.</para>
1596                                         <note>
1597                                                 <para>PostgreSQL version 8.4 is the minimum supported version to work 
1598                                                 with Evergreen 2.0. If you have an older version of PostgreSQL, 
1599                                                 you should upgrade before installing Evergreen. To find your current version 
1600                                                 of PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
1601                                                 user execute the command <command>psql</command>, then type 
1602                                                 <userinput>SELECT version();</userinput> to get detailed information 
1603                                                 about your version of PostgreSQL.</para>
1604                                         </note>
1605                                 </step>
1606                                 <step performance="optional">
1607                                         <title>Install Perl Modules on PostgreSQL Server</title>
1608                                         <para>If PostgreSQL is running on the same system as your Evergreen software,
1609                                         then the Perl modules will automatically be available. Just skip this step.
1610                                         Otherwise, continue if your PostgreSQL server is running on another system,
1611                                         and install several Perl modules there. As the 
1612                                         <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1613                                         is installed, then install the following Perl modules:</para>
1614                                         <screen>
1615                                                 <userinput>
1616         yum install gcc
1617         perl -MCPAN -e shell
1618                 <prompt>cpan></prompt> install JSON::XS
1619                 <prompt>cpan></prompt> install MARC::Record
1620                 <prompt>cpan></prompt> install MARC::File::XML</userinput>
1621                                         </screen>
1622                                         <para>For more information on installing Perl Modules vist the official
1623                                         <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1624                                         <indexterm>
1625                                                 <primary>Perl</primary>
1626                                                 <secondary>CPAN</secondary>
1627                                         </indexterm>
1628                                 </step>
1629                                 <step xml:id="serversideinstallation-configure-2.0">
1630                                         <title>Configure Evergreen</title>
1631                                         <para>In this step you will use the <command>configure</command> and
1632                                         <command>make</command> utilities to configure Evergreen so it can be compiled
1633                                         and linked later in <xref linkend="serversideinstallation-compile-2.0"/>.</para>
1634                                         <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1635                                         the Evergreen build directory and execute these commands:</para>
1636                                         <screen>
1637                                                 <userinput>
1638         # as the opensrf user:
1639         cd /home/opensrf/Evergreen-ILS-2.0.7
1640         ./configure --prefix=/openils --sysconfdir=/openils/conf
1641         make</userinput>
1642                                         </screen>
1643                                 </step>
1644                                 <step xml:id="serversideinstallation-compile-2.0">
1645                                         <title>Compile, Link and Install Evergreen</title>
1646                                         <para>In this step you will actually compile, link and install Evergreen and the 
1647                                         default Evergreen Staff Client.</para>
1648                                         <para>As the <systemitem class="username">root</systemitem> user, return to the
1649                                         Evergreen build directory and use the <command>make</command> utility as shown
1650                                         below:</para>
1651                                         <screen>
1652                                                 <userinput>
1653         # as the root user:
1654         cd /home/opensrf/Evergreen-ILS-2.0.7
1655         make STAFF_CLIENT_BUILD_ID=rel_2_0_7 install</userinput>
1656                                         </screen>
1657                                         <para>The Staff Client will also be automatically built, but you must remember
1658                                         to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the 
1659                                         Staff Client you will use to connect to the Evergreen server.</para>
1660                                         <para>The above commands will create a new subdirectory
1661                                         <filename class="directory">/openils/var/web/xul/rel_2_0_7</filename> 
1662                                         containing the Staff Client.</para>
1663                                         <para>To complete the Staff Client installation, as the
1664                                         <systemitem class="username">root</systemitem> user execute the following commands
1665                                         to create a symbolic link named <emphasis>server</emphasis> in the head of the
1666                                         Staff Client directory <filename class="directory">/openils/var/web/xul</filename> 
1667                                         that points to the subdirectory <filename class="directory">/server</filename>
1668                                         of the new Staff Client build:</para>
1669                                         <screen>
1670                                                 <userinput>
1671         # as the root user:
1672         cd /openils/var/web/xul
1673         ln -sf rel_2_0_7/server server</userinput>
1674                                         </screen>
1675                                 </step>
1676                                 <step>
1677                                         <title>Copy the OpenSRF Configuration Files</title>
1678                                         <para>In this step you will replace some OpenSRF configuration files that you set up
1679                                         earlier in <xref linkend="serversideinstallation-opensrf-2.0"/> when you installed
1680                                         and tested OpenSRF.</para>
1681                                         <para>You must copy several example OpenSRF configuration files into place after first
1682                                         creating backup copies for troubleshooting purposes, then change all the file ownerships
1683                                         to <systemitem class="username">opensrf</systemitem>.
1684                                         As the <systemitem class="username">root</systemitem> user, execute the following
1685                                         commands:</para>
1686                                         <screen>
1687                                                 <userinput>
1688         # as the root user:
1689         cd /openils/conf
1690         cp opensrf.xml        opensrf.xml.BAK
1691         cp opensrf_core.xml      opensrf_core.xml.BAK
1692         cp opensrf.xml.example      opensrf.xml
1693         cp opensrf_core.xml.example opensrf_core.xml
1694         cp oils_web.xml.example     oils_web.xml
1695         chown -R opensrf:opensrf /openils/</userinput>
1696                                         </screen>
1697                                 </step>
1698                                 <step>
1699                                         <title>Create and Configure PostgreSQL Database</title>
1700                                         <indexterm>
1701                                                 <primary>databases</primary>
1702                                                 <secondary>PostgreSQL</secondary>
1703                                         </indexterm>
1704                                         <para>In this step you will create the Evergreen database. In the
1705                                         commands below, remember to adjust the path of the 
1706                                         <emphasis role="bold">contrib</emphasis> repository to match your 
1707                                         PostgreSQL server layout. For example, if you built PostgreSQL from
1708                                         source the path would be 
1709                                         <filename class="directory">/usr/local/share/contrib</filename> 
1710                                         , and if you installed the PostgreSQL 8.4 server packages on 
1711                                         <systemitem class="osname">Ubuntu</systemitem>, the path would be 
1712                                         <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1713                                         <substeps>
1714                                                 <step>
1715                                                         <title>Start the PostgreSQL service</title>
1716                                                         <para>As the <systemitem class="username">root</systemitem>
1717                                                         user on the PostgreSQL system, initialize the PostgreSQL cluster
1718                                                         and start the PostgreSQL service:</para>
1719                                                         <screen>
1720                                                                 <userinput>
1721         # as the root user:
1722         service initdb postgresql
1723         /etc/init.d/postgresql start</userinput>
1724                                                         </screen>
1725                                                 </step>
1726                                                 <step>
1727                                                         <title>Create and configure the database</title>
1728                                                         <para>As the <systemitem class="username">postgres</systemitem> 
1729                                                         user on the PostgreSQL system create the PostgreSQL database,
1730                                                         then set some internal paths:</para>
1731                                                         <screen>
1732                                                                 <userinput>
1733         # as the postgres user:
1734         createdb evergreen -E UTF8 -T template0
1735         createlang plperl   evergreen
1736         createlang plperlu  evergreen
1737         createlang plpgsql  evergreen</userinput>
1738                                                         </screen>
1739                                                         <para>Continue as the <systemitem class="username">postgres</systemitem> 
1740                                                         user and execute the SQL scripts as shown below (remember to adjust the 
1741                                                         paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1742                                                         your installed PostgreSQL version, for example
1743                                                         <literal>"8.4"</literal>).</para>
1744                                                         <screen>
1745                                                                 <userinput>
1746         # as the postgres user:
1747         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1748         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
1749         psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
1750                                                         </screen>
1751                                                 </step>
1752                                                 <step xml:id="serversideinstallation-postgresqlcreateuser-2.0">
1753                                                         <title>Create <systemitem class="username">evergreen</systemitem>
1754                                                                 PostgreSQL user</title>
1755                                                         <para>As the <systemitem class="username">postgres</systemitem>
1756                                                         user on the PostgreSQL system, create a new PostgreSQL user
1757                                                         named <systemitem class="username">evergreen</systemitem> and
1758                                                         assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1759                                                         with an appropriate new password):</para>
1760                                                         <screen>
1761                                                                 <userinput>
1762         # as the postgres user:
1763         createuser -P -s evergreen</userinput>
1764                                                                 <computeroutput>
1765         Enter password for new role: <userinput>NEWPASSWORD</userinput>
1766         Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1767                                                         </screen>
1768                                                 </step>
1769                                                 <step>
1770                                                         <title>Enable IPv4 and IPv6 connections</title>
1771                                                         <para>As the root user, enable IPv4 and IPv6 connections to the
1772                                                         PostgreSQL server. For a single-server instance, enable
1773                                                         password-protected connections from the Evergreen user to the
1774                                                         Evergreen database on localhost by adding the following lines to
1775                                                         <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
1776                                                         <screen>
1777                                                                 <userinput>
1778         # as the root user:
1779
1780         # IPv4 local connections:
1781         host    evergreen     evergreen  127.0.0.1/32     md5
1782         # IPv6 local connections:
1783         host    evergreen     evergreen  ::1/128               md5</userinput>
1784                                                         </screen>
1785                                                         <para>Then, as the root user, restart the PostgreSQL server to
1786                                                         make that configuration take effect:</para>
1787                                                         <screen>
1788                                                                 <userinput>
1789         # as the root user:
1790         /etc/init.d/postgresql restart</userinput>
1791                                                         </screen>
1792                                                 </step>
1793                                                 <step>
1794                                                         <title>Create database schema</title>
1795                                                         <para>In this step you will create the database schema and configure your
1796                                                         system with the corresponding database authentication details for the
1797                                                         <emphasis>evergreen</emphasis> database user that you just created in
1798                                                         <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.</para>
1799                                                         <para>As the <systemitem class="username">root</systemitem> user, enter
1800                                                         the following commands and replace <emphasis>HOSTNAME, PORT,
1801                                                         PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1802                                                         values:</para>
1803                                                         <screen>
1804                                                                 <userinput>
1805         # as the root user:
1806         cd /home/opensrf/Evergreen-ILS-2.0.7
1807         perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1808         --service all --create-schema --create-offline \
1809         --hostname HOSTNAME --port PORT \
1810         --user evergreen --password PASSWORD \
1811         --database DATABASENAME --admin-user ADMIN-USER \ 
1812         --admin-pass ADMIN-PASSWORD </userinput>
1813                                                         </screen>
1814                                                         <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1815                                                         <emphasis role="bold">localhost</emphasis> and
1816                                                         <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1817                                                         Of course, values for <emphasis>PASSWORD</emphasis> and
1818                                                         <emphasis>DATABASENAME</emphasis> must match the values you used in 
1819                                                         <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.
1820                                                         The <option>admin-user</option> and <option>admin-pass</option> options will 
1821                                                         specify the Evergreen administrator account's username and password. This was 
1822                                                         changed for security reasons, it was previously admin/open-ils</para>
1823                                                         <para>As the command executes, you may see warnings similar to:
1824                                                         <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1825                                                         you may see one warning per schema) but they can be safely ignored.</para>
1826                                                         <note>If you are entering the above command on a single line, do not
1827                                                         include the <literal>\</literal> (backslash) characters. If you are using
1828                                                         the <command>bash</command> shell, these should only be used at the end of
1829                                                         a line at a <command>bash</command> prompt to indicate that the command is
1830                                                         continued on the next line.</note>
1831                                                 </step>
1832                                         </substeps>
1833                                 </step>
1834                                 <step>
1835                                         <title>Configure the Apache web server</title>
1836                                         <indexterm>
1837                                                 <primary>web server</primary>
1838                                                 <secondary>Apache</secondary>
1839                                         </indexterm>
1840                                         <para>In this step you will configure the Apache web server to support Evergreen
1841                                         software.</para>
1842                                         <para>First, you must install some additional Apache configuration files. Then you will
1843                                         create a new Security Certificate. Finally, you must make several changes to Apache
1844                                         configuration files.</para>
1845                                         <substeps>
1846                                                 <step>
1847                                                         <title>Copy Apache configuration files</title>
1848                                                         <para>You must copy the Apache configuration files from the
1849                                                         Evergreen installation directory to the Apache directory. As the
1850                                                         <systemitem class="username">root</systemitem> user, perform the
1851                                                         following commands:</para>
1852                                                         <screen>
1853                                                                 <userinput>
1854         # as the root user:
1855         cd /home/opensrf/Evergreen-ILS-2.0.7
1856         cp Open-ILS/examples/apache/eg.conf     /etc/httpd/conf.d/
1857         cp Open-ILS/examples/apache/eg_vhost.conf  /etc/httpd/
1858         cp Open-ILS/examples/apache/startup.pl     /etc/httpd/</userinput>
1859                                                         </screen>
1860                                                 </step>
1861                                                 <step xml:id="serversideinstallation-createsslcertificate-2.0">
1862                                                         <title>Create a Security Certificate</title>
1863                                                         <para>In this step you will create a new Security Certificate (SSL Key)
1864                                                         for the Apache server using the <command>openssl</command> command. For a
1865                                                         public production server you must configure or purchase a signed SSL
1866                                                         certificate, but for now you can just use a self-signed certificate and
1867                                                         accept the warnings in the Staff Client and browser during testing and
1868                                                         development. As the <systemitem class="username">root</systemitem> user,
1869                                                         perform the following commands:</para>
1870                                                         <screen>
1871                                                                 <userinput>
1872         # as the root user:
1873         mkdir /etc/httpd/ssl
1874         cd /etc/httpd/ssl
1875         openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1876                                                         </screen>
1877                                                         <para>You will be prompted for several items of information; enter
1878                                                         the appropriate information for each item. The new files
1879                                                         <filename>server.crt</filename> and <filename>server.key</filename> will
1880                                                         be created in the directory 
1881                                                         <filename class="directory">/etc/httpd/ssl</filename> .</para>
1882                                                         <note>This step generates a self-signed SSL certificate. You must install
1883                                                         a proper SSL certificate for a public production system to avoid warning
1884                                                         messages when users login to their account through the OPAC or when staff