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