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">
4 <title>Server-side Installation of Evergreen Software</title>
6 <para>This section describes installation of the Evergreen server-side software and
7 its associated components. Installation, configuration, testing and verification of
8 the software is straightforward if you follow some simple directions.</para>
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
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
33 <table xml:id="serversideinstall-software-dependencies">
34 <?dbfo keep-together="always" ?>
35 <title>Evergreen Software Dependencies</title>
37 <primary>Evergreen software dependencies</primary>
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*"/>
45 <entry>Evergreen</entry>
46 <entry>OpenSRF</entry>
47 <entry>PostgreSQL</entry>
57 <entry>1.6.1.x</entry>
59 <entry>8.2 / 8.3</entry>
62 <entry>1.6.0.x</entry>
64 <entry>8.2 / 8.3</entry>
69 <entry>8.1 / 8.2</entry>
74 <entry>8.1 / 8.2</entry>
79 <section xml:id="serversideinstallation-all">
80 <title>Installing Server-Side Software</title>
81 <para>This section describes the installation of the major components of Evergreen server-side software.</para>
82 <para>As far as possible, you should perform the following steps in the exact order given since the
83 success of many steps relies on the successful completion of earlier steps. You should make backup
84 copies of files and environments when you are instructed to do so. In the event of installation problems
85 those copies can allow you to back out of a step gracefully and resume the installation from a known
86 state. See <xref linkend="backingup"/> for further information.</para>
87 <para>Of course, after you successfully complete and test the entire Evergreen installation you should
88 take a final snapshot backup of your system(s). This can be the first in the series of regularly
89 scheduled system backups that you should probably also begin.</para>
90 <section xml:id="serversideinstallation-opensrf-1.6.3">
92 <primary>OpenSRF</primary>
93 <secondary>installation</secondary>
95 <title>Installing OpenSRF 1.6.x On <systemitem class="osname">Ubuntu</systemitem> or
96 <systemitem class="osname">Debian</systemitem></title>
98 <primary>Linux</primary>
99 <secondary>Debian</secondary>
102 <primary>Linux</primary>
103 <secondary>Ubuntu</secondary>
105 <para>This section describes the installation of the latest version of the Open Service Request
106 Framework (OpenSRF), a major component of the Evergreen server-side software, on
107 <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
108 systems. Evergreen software is integrated with and depends on the OpenSRF software
110 <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
111 properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
112 continue with any further Evergreen installation steps
113 until you have verified that OpenSRF has been successfully installed and tested.</para>
115 <para>The following steps have been tested on the x86 (32-bit) architecture of
116 <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
117 <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
118 <systemitem class="osname">Fedora 13</systemitem> and
119 <systemitem class="osname">Fedora 14</systemitem>.</para>
120 <para>In the following instructions, you are asked to perform certain steps as
121 either the <systemitem class="username">root</systemitem> user, the
122 <systemitem class="username">opensrf</systemitem> user, or the
123 <systemitem class="username">postgres</systemitem> user.</para>
126 <para><systemitem class="osname">Debian</systemitem> -- To become the
127 <systemitem class="username">root</systemitem> user, issue the command
128 <command>su -</command> and enter the password of the
129 <systemitem class="username">root</systemitem> user.</para>
132 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
133 <systemitem class="username">root</systemitem> user, issue the command
134 <command>sudo su -</command> and enter the password of the
135 <systemitem class="username">root</systemitem> user.</para>
138 <para>To switch from the <systemitem class="username">root</systemitem> user to a
139 different user, issue the command <command>su - USERNAME</command>. For example, to
140 switch from the <systemitem class="username">root</systemitem> user to the
141 <systemitem class="username">opensrf</systemitem> user, issue the command
142 <command>su - opensrf</command>. Once you have become a non-root user, to become
143 the <systemitem class="username">root</systemitem> user again, simply issue the command
144 <command>exit</command>.</para>
148 <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
149 <para>As the <systemitem class="username">root</systemitem> user, add the
150 <systemitem class="username">opensrf</systemitem> user to the system.
151 In the following example, the default shell for the
152 <systemitem class="username">opensrf</systemitem> user is automatically set
153 to <command>/bin/bash</command> to inherit a reasonable environment:</para>
157 useradd -m -s /bin/bash opensrf
158 passwd opensrf</userinput>
162 <title>Download and Unpack Latest OpenSRF Version</title>
164 <primary>OpenSRF</primary>
165 <secondary>download</secondary>
167 <para>The latest version of OpenSRF can be found here:
168 <ulink url="http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz"></ulink> .
169 As the <systemitem class="username">opensrf</systemitem> user, change to
170 the directory <filename class="directory">/home/opensrf</filename> then download
171 and extract OpenSRF. The new subdirectory
172 <filename class="directory">/home/opensrf/opensrf-1.6.3</filename> will be created:</para>
175 # as the opensrf user:
177 wget http://evergreen-ils.org/downloads/opensrf-1.6.3.tar.gz
178 tar zxf opensrf-1.6.3.tar.gz</userinput>
182 <title>Install Prerequisites to Build OpenSRF</title>
183 <para>In this section you will install and configure a set of prerequisites that will be
184 used to build OpenSRF. In a following step you will actually build the OpenSRF software
185 using the <command>make</command> utility.</para>
186 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
187 below to build the prerequisites from the software distribution that you just downloaded
188 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
189 example with the keyword corresponding to the name of one of the
190 <systemitem class="osname">Linux</systemitem> distributions listed in the
191 distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
192 For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
193 enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
197 cd /home/opensrf/opensrf-1.6.3
198 make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
200 <table xml:id="serversideinstallation-keywords-opensrf">
201 <?dbfo keep-together="always" ?>
202 <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
203 <tgroup align="left" cols="2" colsep="1" rowsep="1">
204 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
205 <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
208 <entry>Keyword</entry>
209 <entry>Linux Version</entry>
214 <entry>debian-squeeze</entry>
215 <entry>Debian "Squeeze" (6.0)</entry>
218 <entry>debian-etch</entry>
219 <entry>Debian "Etch" (4.0)</entry>
222 <entry>debian-lenny</entry>
223 <entry>Debian "Lenny" (5.0)</entry>
226 <entry>ubuntu-hardy</entry>
227 <entry>Ubuntu "Hardy Heron" (8.04)</entry>
230 <entry>ubuntu-karmic</entry>
231 <entry>Ubuntu "Karmic Koala" (9.10)</entry>
234 <entry>ubuntu-lucid</entry>
235 <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
238 <entry>fedora13</entry>
239 <entry>Fedora "Goddard" (13)</entry>
242 <entry>fedora13</entry>
243 <entry>Fedora "Laughlin" (14)</entry>
246 <entry>centos</entry>
247 <entry>CentOS 5</entry>
251 <entry>Red Hat Enterprise Linux 5</entry>
254 <entry>gentoo</entry>
255 <entry>Gentoo</entry>
261 <primary>Linux</primary>
262 <secondary>Debian</secondary>
265 <primary>Linux</primary>
266 <secondary>Fedora</secondary>
269 <primary>Linux</primary>
270 <secondary>Ubuntu</secondary>
273 <primary>Linux</primary>
274 <secondary>CentOS</secondary>
277 <primary>Linux</primary>
278 <secondary>Red Hat</secondary>
281 <primary>Linux</primary>
282 <secondary>Gentoo</secondary>
284 <para>This will install a number of packages on the system that are required by OpenSRF,
285 including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
286 CPAN configuration prompt to allow it to automatically configure itself to download and
287 install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
288 it should install prerequisite modules - say <literal>Yes</literal>.</para>
291 <title>Build OpenSRF</title>
292 <para>In this section you will configure, build and install the OpenSRF
293 components that support other Evergreen services.</para>
296 <title>Configure OpenSRF</title>
298 <primary>OpenSRF</primary>
299 <secondary>configure</secondary>
301 <para>As the <systemitem class="username">opensrf</systemitem>
302 user, return to the new OpenSRF build directory and use the
303 <command>configure</command> utility to prepare for the next
304 step of compiling and linking the software. If you wish to
305 include support for Python and Java, add the configuration
306 options <option>--enable-python</option> and
307 <option>--enable-java</option>, respectively:</para>
310 # as the opensrf user:
311 cd /home/opensrf/opensrf-1.6.3
312 ./configure --prefix=/openils --sysconfdir=/openils/conf
315 <para>This step will take several minutes to complete.</para>
318 <title>Compile, Link and Install OpenSRF</title>
319 <para>As the <systemitem class="username">root</systemitem>
320 user, return to the new OpenSRF build directory and use the
321 <command>make</command> utility to compile, link and install
326 cd /home/opensrf/opensrf-1.6.3
327 make install</userinput>
329 <para>This step will take several minutes to complete.</para>
332 <title>Update the System Dynamic Library Path</title>
333 <para>You must update the system dynamic library path to force
334 your system to recognize the newly installed libraries. As the
335 <systemitem class="username">root</systemitem> user, do this by
336 creating the new file
337 <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing two
338 new library paths, then execute the command
339 <command>ldconfig</command> to automatically read the file and
340 modify the system dynamic library path:</para>
344 echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
345 echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
349 <step xml:id="serversideinstallation-definedomains">
350 <title>Define Public and Private OpenSRF Domains</title>
351 <para>For security purposes, OpenSRF uses Jabber domains to separate services
352 into public and private realms. On a single-server system the easiest way to
353 define public and private OpenSRF domains is to define separate host names by
354 adding entries to the file <filename>/etc/hosts</filename>.</para>
355 <para>In the following steps we will use the example domains
356 <systemitem class="domainname">public.localhost</systemitem> for the public
357 domain and <systemitem class="domainname">private.localhost</systemitem>
358 for the private domain. In an upcoming step, you will configure two special
359 <systemitem class="service">ejabberd</systemitem> users
360 to handle communications for these two domains.</para>
361 <para>As the <systemitem class="username">root</systemitem> user, edit the file
362 <filename>/etc/hosts</filename> and add the following example domains:</para>
364 <primary>Jabber</primary>
369 127.0.1.2 public.localhost public
370 127.0.1.3 private.localhost private</userinput>
374 <title>Change File Ownerships</title>
375 <para>Finally, as the <systemitem class="username">root</systemitem>
376 user, change the ownership of all files installed in the
377 directory <filename class="directory">/openils</filename> to the
378 user <systemitem class="username">opensrf</systemitem>:</para>
382 chown -R opensrf:opensrf /openils</userinput>
387 <step xml:id="stop-ejabberd-service">
388 <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
390 <primary>ejabberd</primary>
392 <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
393 you must stop that service. As the <systemitem class="username">root</systemitem> user,
394 execute the following command to stop the service:</para>
398 /etc/init.d/ejabberd stop</userinput>
400 <para>If <systemitem class="service">ejabberd</systemitem> reports that it
401 is already stopped, there may have been a problem when it started back
402 in the installation step. If there are any remaining daemon processes such as
403 <systemitem class="daemon">beam</systemitem> or
404 <systemitem class="daemon">epmd</systemitem>
405 you may need to perform the following commands to kill them:</para>
410 killall beam; killall beam.smp
411 rm /var/lib/ejabberd/*
412 echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
416 <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
417 <para>You must make several configuration changes for the
418 <systemitem class="service">ejabberd</systemitem> service before
420 As the <systemitem class="username">root</systemitem> user, edit the file
421 <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
424 <para>Change the line:</para>
425 <literal>{hosts, ["localhost"]}.</literal>
426 <para>to instead read:</para>
427 <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
431 <para>Change the line for older versions of
432 <systemitem class="service">ejabberd</systemitem>:</para>
433 <literal>{max_user_sessions, 10}</literal>
434 <para>to instead read:</para>
435 <literal>{max_user_sessions, 10000}</literal>
437 <para>Change the line for newer versions of
438 <systemitem class="service">ejabberd</systemitem>:</para>
439 <literal>{access, max_user_sessions, [{10, all}]}</literal>
440 <para>to instead read:</para>
441 <literal>{access, max_user_sessions, [{10000, all}]}</literal>
444 <para>Change all three occurrences of:</para>
445 <literal>max_stanza_size</literal>
446 <para>to instead read:</para>
447 <literal>2000000</literal>
450 <para>Change both occurrences of:</para>
451 <literal>maxrate</literal>
452 <para>to instead read:</para>
453 <literal>500000</literal>
456 <para>Comment out the line:</para>
457 <literal>{mod_offline, []}</literal>
458 <para>by placing two <literal>%</literal> comment signs in front
459 so it instead reads:</para>
460 <literal>%%{mod_offline, []}</literal>
464 <step xml:id="serversideinstallation-opensrf-continued">
465 <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
466 <para>As the <systemitem class="username">root</systemitem> user, restart the
467 <systemitem class="service">ejabberd</systemitem> service to test the
468 configuration changes and to register your users:</para>
472 /etc/init.d/ejabberd start</userinput>
476 <title>Register <systemitem class="username">router</systemitem> and
477 <systemitem class="username">opensrf</systemitem> as
478 <systemitem class="service">ejabberd</systemitem> users</title>
479 <para>The two <systemitem class="service">ejabberd</systemitem> users
480 <systemitem class="username">router</systemitem> and
481 <systemitem class="username">opensrf</systemitem> must be registered
482 and configured to manage OpenSRF router service and communications
483 for the two domains <literal>public.localhost</literal> and
484 <literal>private.localhost</literal> that you added to the file
485 <filename>/etc/hosts</filename> in a previous step
486 (see <xref linkend="serversideinstallation-definedomains"/>).
487 The users include:</para>
490 <para>the <systemitem class="username">router</systemitem> user,
491 to whom all requests to connect to an OpenSRF service will be
495 <para>the <systemitem class="username">opensrf</systemitem> user,
496 which clients use to connect to OpenSRF services (you may name
497 the user anything you like, but we use
498 <literal>opensrf</literal> in these examples)</para>
501 <para>As the <systemitem class="username">root</systemitem> user, execute the
502 <command>ejabberdctl</command> utility as shown below to register and create passwords
503 for the users <systemitem class="username">router</systemitem> and
504 <systemitem class="username">opensrf</systemitem> on each domain (remember to replace
505 <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
509 # Note: the syntax for registering a user with ejabberdctl is:
510 # ejabberdctl register USER DOMAIN PASSWORD
511 ejabberdctl register router private.localhost NEWPASSWORD
512 ejabberdctl register router public.localhost NEWPASSWORD
513 ejabberdctl register opensrf private.localhost NEWPASSWORD
514 ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
516 <para>The users <systemitem class="username">router</systemitem> and
517 <systemitem class="username">opensrf</systemitem> and their respective passwords
518 will be used again in <xref linkend="serversideinstallation-passwords"/> when
519 we modify the OpenSRF configuration file
520 <filename>/openils/conf/opensrf_core.xml</filename> .</para>
523 There appears to be a problem with <command>ejabberdctl</command> in
524 that it does not escape input correctly, so a password like
525 <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
526 A bug against ejabberd has been filed. To register a password using
527 <command>ejabberdctl</command> with special shell characters until such
528 time as that bug is resolved, the workaround is to specify a
529 double-escaped character at the command line, for example,
530 <literal>'0P3N\\\\$RF'</literal> .</para>
533 <step xml:id="serversideinstallation-opensrf-createconfig">
534 <title>Create OpenSRF configuration files</title>
535 <para>As the <systemitem class="username">opensrf</systemitem> user,
536 execute the following commands to create the new configuration files
537 <filename>/openils/conf/opensrf_core.xml</filename> and
538 <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
541 # as the opensrf user:
543 cp opensrf.xml.example opensrf.xml
544 cp opensrf_core.xml.example opensrf_core.xml</userinput>
547 <step xml:id="serversideinstallation-passwords">
548 <title>Update usernames and passwords in the OpenSRF configuration file</title>
549 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
550 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
551 and update the usernames and passwords to match the values shown in the
552 following table. The left-hand side of
553 <xref linkend="serversideinstallation-xpath-table-1"/> shows common XPath
554 syntax to indicate the approximate position within the XML file that needs
555 changes. The right-hand side of the table shows the replacement values:</para>
556 <table xml:id="serversideinstallation-xpath-table-1">
557 <?dbfo keep-together="always" ?>
558 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
559 <tgroup align="left" cols="2" colsep="1" rowsep="1">
560 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
561 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
564 <entry>XPath location</entry>
570 <entry>/config/opensrf/username</entry>
572 <systemitem class="username">opensrf</systemitem>
576 <entry>/config/opensrf/passwd </entry>
577 <entry><systemitem class="domainname">private.localhost</systemitem>
579 <systemitem class="username">opensrf</systemitem> user
583 <entry>/config/gateway/username</entry>
585 <systemitem class="username">opensrf</systemitem>
589 <entry>/config/gateway/passwd</entry>
590 <entry><systemitem class="domainname">public.localhost</systemitem>
592 <systemitem class="username">opensrf</systemitem> user
596 <entry>/config/routers/router/transport/username,
597 first entry where server == public.localhost</entry>
599 <systemitem class="username">router</systemitem>
603 <entry>/config/routers/router/transport/password,
604 first entry where server == public.localhost</entry>
605 <entry><systemitem class="domainname">public.localhost</systemitem>
607 <systemitem class="username">router</systemitem> user
611 <entry>/config/routers/router/transport/username,
612 second entry where server == private.localhost</entry>
614 <systemitem class="username">router</systemitem>
618 <entry>/config/routers/router/transport/password,
619 second entry where server == private.localhost</entry>
620 <entry><systemitem class="domainname">private.localhost</systemitem>
622 <systemitem class="username">router</systemitem> user
628 <para>You may also need to modify the file to specify the domains from which
629 <systemitem class="service">OpenSRF</systemitem> will accept connections,
630 and to which it will make connections.
631 If you are installing <application>OpenSRF</application> on a single server
632 and using the <systemitem class="domainname">private.localhost</systemitem> and
633 <systemitem class="domainname">public.localhost</systemitem> domains,
634 these will already be set to the correct values. Otherwise, search and replace
635 to match values for your own systems.</para>
638 <title>Set the location of the persistent database</title>
639 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
640 file <filename>/openils/conf/opensrf.xml</filename>, then find and verify that
641 the element <literal>dbfile</literal> (near the end of the file) is set to the
642 location of the persistent database. If necessary, change the default line:</para>
643 <literal>/openils/var/persist.db</literal>
644 <para>to instead read:</para>
645 <literal>/tmp/persist.db</literal>
646 <para>Following is a sample modification of that portion of the file:</para>
647 <programlisting language="xml"><![CDATA[
648 <!-- Example of an app-specific setting override -->
651 <dbfile>/tmp/persist.db</dbfile>
656 <step xml:id="serversideinstallation-srfsh">
657 <title>Create configuration files for users needing <command>srfsh</command></title>
658 <para>In this section you will set up a special configuration file for each user
659 who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
660 shell</emphasis>) utility.</para>
662 <primary>srfsh</primary>
664 <para>The software installation will automatically create the utility
665 <command>srfsh</command>, a command line diagnostic tool for testing and
666 interacting with <application>OpenSRF</application>. It will be used
667 in a future step to complete and test the Evergreen installation. See
668 <xref linkend="serversideinstallation-testing"/> for further information.</para>
669 <para>As the <systemitem class="username">root</systemitem> user, copy the
670 sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
671 to the home directory of each user who will use <command>srfsh</command>.
672 For instance, do the following for the
673 <systemitem class="username">opensrf</systemitem> user:</para>
677 cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>
679 <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
680 following changes:</para>
683 <para>Modify <literal>domain</literal> to be the router hostname
684 (following our domain examples,
685 <systemitem class="domainname">private.localhost</systemitem> will give
686 <command>srfsh</command> access to all OpenSRF services, while
687 <systemitem class="domainname">public.localhost</systemitem>
688 will only allow access to those OpenSRF services that are
689 publicly exposed).</para>
692 <para>Modify <literal>username</literal> and
693 <literal>password</literal> to match the
694 <literal>opensrf</literal> Jabber user for the chosen
698 <para>Modify <literal>logfile</literal> to be the full path for
699 a log file to which the user has write access</para>
702 <para>Modify <literal>loglevel</literal> as needed for testing</para>
705 <para>Change the owner of the file to match the owner of the
706 home directory</para>
709 <para>Following is a sample of the file:</para>
710 <programlisting language="xml"><![CDATA[
711 <?xml version="1.0"?>
712 <!-- This file follows the standard bootstrap config file layout -->
713 <!-- found in opensrf_core.xml -->
715 <router_name>router</router_name>
716 <domain>private.localhost</domain>
717 <username>opensrf</username>
718 <passwd>SOMEPASSWORD</passwd>
720 <logfile>/tmp/srfsh.log</logfile>
721 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
722 <loglevel>4</loglevel>
727 <title>Modify the environmental variable <envar>PATH</envar> for the
728 <systemitem class="username">opensrf</systemitem> user</title>
729 <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
730 environmental variable <envar>PATH</envar> by adding a new file path to the
731 <systemitem class="username">opensrf</systemitem> user's shell configuration
732 file <filename>~/.bashrc</filename>:</para>
735 # as the opensrf user:
736 echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
740 <title>Start OpenSRF</title>
741 <para>As the <systemitem class="username">root</systemitem> user, start the
742 <systemitem class="service">ejabberd</systemitem> and
743 <systemitem class="service">memcached</systemitem> services:</para>
747 /etc/init.d/ejabberd start
748 /etc/init.d/memcached start</userinput>
750 <para>Then as the <systemitem class="username">opensrf</systemitem> user,
751 start OpenSRF as follows:</para>
754 # as the opensrf user:
755 osrf_ctl.sh -l -a start_all</userinput>
757 <para>The flag <option>-l</option> forces Evergreen to use
758 <systemitem class="domainname">localhost</systemitem> (your current system)
759 as the hostname. The flag <option>-a start_all</option> starts the
760 OpenSRF <systemitem class="service">router</systemitem> ,
761 <systemitem class="service">Perl</systemitem> , and
762 <systemitem class="service">C</systemitem> services.</para>
765 <para>You can also start Evergreen without the
766 <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
767 utility must know the fully qualified domain name for the system
768 on which it will execute. That hostname was probably specified
769 in the configuration file <filename>opensrf.xml</filename> which
770 you configured in a previous step.</para>
773 <para>If you receive an error message similar to
774 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
775 environment variable <envar>PATH</envar> does not include the
776 directory <filename class="directory">/openils/bin</filename>.
777 As the <systemitem class="username">opensrf</systemitem> user,
778 edit the configuration file <filename>~/.bashrc</filename> and
779 add the following line:
780 <literal>export PATH=$PATH:/openils/bin</literal></para>
785 <title>Test connections to OpenSRF</title>
786 <para>Once you have installed and started OpenSRF, as the
787 <systemitem class="username">root</systemitem> user test your connection to
788 <systemitem class="service">OpenSRF</systemitem> with the <command>srfsh</command>
789 utility and try to call the <command>add</command> method on the OpenSRF
790 <systemitem class="service">math</systemitem> service:</para>
794 /openils/bin/srfsh</userinput>
796 srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
799 ------------------------------------
800 Request Completed Successfully
801 Request Time in seconds: 0.007519
802 ------------------------------------</computeroutput>
804 <para>For other <command>srfsh</command> commands, type in
805 <userinput>help</userinput> at the prompt.</para>
808 <title>Stop OpenSRF</title>
809 <para>After OpenSRF has started, you can stop it at any time by using the
810 <command>osrf_ctl.sh</command> again. As the
811 <systemitem class="username">opensrf</systemitem>
812 user, stop OpenSRF as follows:</para>
815 # as the opensrf user:
816 osrf_ctl.sh -l -a stop_all</userinput>
821 <section xml:id="serversideinstallation-ubuntudebian">
822 <title>Installing Evergreen 2.x On <systemitem class="osname">Ubuntu</systemitem> or
823 <systemitem class="osname">Debian</systemitem></title>
825 <primary>Linux</primary>
826 <secondary>Debian</secondary>
829 <primary>Linux</primary>
830 <secondary>Ubuntu</secondary>
832 <para>This section outlines the installation process for the latest stable
833 version of Evergreen on <systemitem class="osname">Ubuntu</systemitem> or
834 <systemitem class="osname">Debian</systemitem> systems. See
835 <xref linkend="serversideinstallation-fedora"/> for description of a similar
836 installation on a <systemitem class="osname">Fedora 14</systemitem> system.</para>
837 <para>In this section you will download, unpack, install, configure and test the Evergreen
838 system, including the Evergreen server and the PostgreSQL database system. You will make several
839 configuration changes and adjustments to the software, including updates to configure the system
840 for your own locale, and some updates needed to work around a few known issues.</para>
842 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
843 architectures. There may be differences between the Desktop and Server editions of
844 <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
846 <para>In the following instructions, you are asked to perform certain steps as
847 either the <systemitem class="username">root</systemitem> user, the
848 <systemitem class="username">opensrf</systemitem> user, or the
849 <systemitem class="username">postgres</systemitem> user.</para>
852 <para><systemitem class="osname">Debian</systemitem> -- To become the
853 <systemitem class="username">root</systemitem> user, issue the command
854 <command>su -</command> and enter the password of the
855 <systemitem class="username">root</systemitem> user.</para>
858 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
859 <systemitem class="username">root</systemitem> user, issue the command
860 <command>sudo su -</command> and enter the password of the
861 <systemitem class="username">root</systemitem> user.</para>
864 <para>To switch from the <systemitem class="username">root</systemitem> user to a
865 different user, issue the command <command>su - USERNAME</command>. For example, to
866 switch from the <systemitem class="username">root</systemitem> user to the
867 <systemitem class="username">opensrf</systemitem> user, issue the command
868 <command>su - opensrf</command>. Once you have become a non-root user, to become the
869 <systemitem class="username">root</systemitem> user again, simply issue the command
870 <command>exit</command>.</para>
874 <title>Install OpenSRF</title>
875 <para>Evergreen software is integrated with and depends on the Open Service
876 Request Framework (OpenSRF) software system. For further information on
877 installing, configuring and testing OpenSRF, see
878 <xref linkend="serversideinstallation-opensrf-1.6.3"/>.</para>
879 <para>Follow the steps outlined in that section and run the specified tests to
880 ensure that OpenSRF is properly installed and configured. Do
881 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
882 any further Evergreen installation steps until you have verified that OpenSRF
883 has been successfully installed and tested.</para>
886 <title>Download and Unpack Latest Evergreen Version</title>
887 <para>The latest version of Evergreen can be found here:
888 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
889 As the <systemitem class="username">opensrf</systemitem> user, change to
890 the directory <filename class="directory">/home/opensrf</filename> then download
891 and extract Evergreen. The new subdirectory
892 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename>
893 will be created:</para>
896 # as the opensrf user:
898 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
899 tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
902 <step xml:id="serversideinstallation-installprereq">
903 <title>Install Prerequisites to Build Evergreen</title>
904 <para>In this section you will install and configure a set of prerequisites that will be
905 used later in <xref linkend="serversideinstallation-configure"/> and
906 <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
907 using the <command>make</command> utility.</para>
908 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
909 below to build the prerequisites from the software distribution that you just downloaded
910 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
911 example with the keyword corresponding to the name of one of the
912 <systemitem class="osname">Linux</systemitem> distributions listed in the following
914 For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
915 enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
916 ubuntu-lucid</command>.</para>
920 cd /home/opensrf/Evergreen-ILS-2.0.4
921 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
924 <step performance="optional">
925 <title>(OPTIONAL) Install the PostgreSQL Server</title>
927 <primary>databases</primary>
928 <secondary>PostgreSQL</secondary>
930 <para>Since the PostgreSQL server is usually a standalone server in multi-server
931 production systems, the prerequisite installer Makefile in the previous section
932 (see <xref linkend="serversideinstallation-installprereq"/>)
933 does not automatically install PostgreSQL. You must install the PostgreSQL server
934 yourself, either on the same system as Evergreen itself or on another system.
935 If your PostgreSQL server is on a different system, just skip this step.
936 If your PostgreSQL server will be on the same system as your Evergreen
937 software, you can install the required PostgreSQL server packages as described
938 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
939 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
940 for more information.</para>
942 <para>PostgreSQL version 8.4 is the minimum supported version to work
943 with Evergreen 2.0. If you have an older version of PostgreSQL,
944 you should upgrade before installing Evergreen. To find your current version
945 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
946 user execute the command <command>psql</command>, then type
947 <userinput>SELECT version();</userinput> to get detailed information
948 about your version of PostgreSQL.</para>
951 <step performance="optional">
952 <title>Install Perl Modules on PostgreSQL Server</title>
953 <para>If PostgreSQL is running on the same system as your Evergreen software,
954 then the Perl modules will automatically be available. Just skip this step.
955 Otherwise, continue if your PostgreSQL server is running on another system
956 and install several Perl modules there. As the
957 <systemitem class="username">root</systemitem> user, ensure the gcc compiler
958 is installed, then install the following Perl modules:</para>
961 aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
963 <prompt>cpan></prompt> Business::ISBN
964 <prompt>cpan></prompt> install JSON::XS
965 <prompt>cpan></prompt> Library::CallNumber::LC
966 <prompt>cpan></prompt> install MARC::Record
967 <prompt>cpan></prompt> install MARC::File::XML
968 <prompt>cpan></prompt> cpan UUID::Tiny</userinput>
970 <para>For more information on installing Perl Modules vist the official
971 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
973 <primary>Perl</primary>
974 <secondary>CPAN</secondary>
978 <title>Update the System Dynamic Library Path</title>
979 <para>You must update the system dynamic library path to force your system to recognize
980 the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
981 do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
982 containing two new library paths, then run the command <command>ldconfig</command> to
983 automatically read the file and modify the system dynamic library path:</para>
987 echo "/usr/local/lib" > /etc/ld.so.conf.d/osrf.conf
988 echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
992 <step performance="optional">
993 <title>Restart the PostgreSQL Server</title>
994 <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
995 the <systemitem class="username">root</systemitem> user you must restart
996 PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
997 running on another system, you may skip this step.
998 As the <systemitem class="username">opensrf</systemitem> user,
999 execute the following command (remember to replace
1000 <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
1001 for example <literal>8.4</literal>):</para>
1004 # as the opensrf user:
1005 /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
1008 <step xml:id="serversideinstallation-configure">
1009 <title>Configure Evergreen</title>
1010 <para>In this step you will use the <command>configure</command> and
1011 <command>make</command> utilities to configure Evergreen so it can be compiled
1012 and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
1013 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1014 the Evergreen build directory and execute these commands:</para>
1017 # as the opensrf user:
1018 cd /home/opensrf/Evergreen-ILS-2.0.4
1019 ./configure --prefix=/openils --sysconfdir=/openils/conf
1023 <step xml:id="serversideinstallation-compile">
1024 <title>Compile, Link and Install Evergreen</title>
1025 <para>In this step you will actually compile, link and install Evergreen and the
1026 default Evergreen Staff Client.</para>
1027 <para>As the <systemitem class="username">root</systemitem> user, return to the
1028 Evergreen build directory and use the <command>make</command> utility as shown
1033 cd /home/opensrf/Evergreen-ILS-2.0.4
1034 make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
1036 <para>The Staff Client will also be automatically built, but you must remember
1037 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1038 Staff Client you will use to connect to the Evergreen server.</para>
1039 <para>The above commands will create a new subdirectory
1040 <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
1041 containing the Staff Client.</para>
1042 <para>To complete the Staff Client installation, as the
1043 <systemitem class="username">root</systemitem> user execute the following commands to
1044 create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
1045 directory <filename class="directory">/openils/var/web/xul</filename> that points to the
1046 subdirectory <filename class="directory">/server</filename> of the new Staff Client
1051 cd /openils/var/web/xul
1052 ln -sf rel_2_0_4/server server</userinput>
1056 <title>Copy the OpenSRF Configuration Files</title>
1057 <para>In this step you will replace some OpenSRF configuration files that you set up in
1058 <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
1059 tested OpenSRF.</para>
1060 <para>You must copy several example OpenSRF configuration files into place after first
1061 creating backup copies for troubleshooting purposes, then change all the file ownerships
1062 to <systemitem class="username">opensrf</systemitem>.
1063 As the <systemitem class="username">root</systemitem> user, execute the following
1069 cp opensrf.xml opensrf.xml.BAK
1070 cp opensrf_core.xml opensrf_core.xml.BAK
1071 cp opensrf.xml.example opensrf.xml
1072 cp opensrf_core.xml.example opensrf_core.xml
1073 cp oils_web.xml.example oils_web.xml
1074 chown -R opensrf:opensrf /openils/</userinput>
1078 <title>Create and Configure PostgreSQL Database</title>
1080 <primary>databases</primary>
1081 <secondary>PostgreSQL</secondary>
1083 <para>In this step you will create the Evergreen database. In the commands
1084 below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
1085 repository to match your PostgreSQL server
1086 layout. For example, if you built PostgreSQL from source the path would be
1087 <filename class="directory">/usr/local/share/contrib</filename> , and if you
1088 installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
1090 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1093 <title>Create and configure the database</title>
1094 <para>As the <systemitem class="username">postgres</systemitem>
1095 user on the PostgreSQL system create the PostgreSQL database,
1096 then set some internal paths:</para>
1099 # as the postgres user:
1100 createdb evergreen -E UTF8 -T template0
1101 createlang plperl evergreen
1102 createlang plperlu evergreen
1103 createlang plpgsql evergreen</userinput>
1105 <para>Continue as the <systemitem class="username">postgres</systemitem>
1106 user and execute the SQL scripts as shown below (remember to adjust the
1107 paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1108 your installed PostgreSQL version, for example
1109 <literal>"8.4"</literal>).</para>
1112 # as the postgres user:
1113 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1114 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
1115 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
1118 <step xml:id="serversideinstallation-postgresqlcreateuser">
1119 <title>Create <systemitem class="username">evergreen</systemitem>
1120 PostgreSQL user</title>
1121 <para>As the <systemitem class="username">postgres</systemitem>
1122 user on the PostgreSQL system, create a new PostgreSQL user
1123 named <systemitem class="username">evergreen</systemitem> and
1124 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1125 with an appropriate new password):</para>
1128 # as the postgres user:
1129 createuser -P -s evergreen</userinput>
1131 Enter password for new role: <userinput>NEWPASSWORD</userinput>
1132 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1136 <title>Create database schema</title>
1137 <para>In this step you will create the database schema and configure your
1138 system with the corresponding database authentication details for the
1139 <emphasis>evergreen</emphasis> database user that you just created in
1140 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
1141 <para>As the <systemitem class="username">root</systemitem> user, enter
1142 the following commands and replace <emphasis>HOSTNAME, PORT,
1143 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1148 cd /home/opensrf/Evergreen-ILS-2.0.4
1149 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1150 --service all --create-schema --create-offline \
1151 --hostname HOSTNAME --port PORT \
1152 --user evergreen --password PASSWORD \
1153 --database DATABASENAME --admin-user ADMIN-USER \
1154 --admin-pass ADMIN-PASSWORD </userinput>
1156 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1157 <emphasis role="bold">localhost</emphasis> and
1158 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1159 Of course, values for <emphasis>PASSWORD</emphasis> and
1160 <emphasis>DATABASENAME</emphasis> must match the values you used in
1161 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
1162 The <option>admin-user</option> and <option>admin-pass</option> options will
1163 specify the Evergreen administrator account's username and password. This was
1164 changed for security reasons, it was previously admin/open-ils</para>
1165 <para>As the command executes, you may see warnings similar to:
1166 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1167 you may see one warning per schema) but they can be safely ignored.</para>
1168 <note>If you are entering the above command on a single line, do not
1169 include the <literal>\</literal> (backslash) characters. If you are using
1170 the <command>bash</command> shell, these should only be used at the end of
1171 a line at a <command>bash</command> prompt to indicate that the command is
1172 continued on the next line.</note>
1177 <title>Configure the Apache web server</title>
1179 <primary>web server</primary>
1180 <secondary>Apache</secondary>
1182 <para>In this step you will configure the Apache web server to support Evergreen
1184 <para>First, you must enable some built-in Apache modules and install some
1185 additional Apache configuration files. Then you will create a new Security
1186 Certificate. Finally, you must make several changes to the Apache configuration
1190 <title>Enable the required Apache Modules</title>
1191 <para>As the <systemitem class="username">root</systemitem>
1192 user, enable some modules in the Apache server, then copy the
1193 new configuration files to the Apache server directories:</para>
1195 <primary>Apache modules</primary>
1200 a2enmod ssl # enable mod_ssl
1201 a2enmod rewrite # enable mod_rewrite
1202 a2enmod expires # enable mod_expires</userinput>
1204 <para>As the commands execute, you may see warnings similar to:
1205 <literal>Module SOMEMODULE already enabled</literal> but you can
1206 safely ignore them.</para>
1209 <title>Copy Apache configuration files</title>
1210 <para>You must copy the Apache configuration files from the
1211 Evergreen installation directory to the Apache directory. As the
1212 <systemitem class="username">root</systemitem> user, perform the
1213 following commands:</para>
1217 cd /home/opensrf/Evergreen-ILS-2.0.4
1218 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/
1219 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
1220 cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
1223 <step xml:id="serversideinstallation-createsslcertificate">
1224 <title>Create a Security Certificate</title>
1225 <para>In this step you will create a new Security Certificate (SSL Key)
1226 for the Apache server using the <command>openssl</command> command. For a
1227 public production server you must configure or purchase a signed SSL
1228 certificate, but for now you can just use a self-signed certificate and
1229 accept the warnings in the Staff Client and browser during testing and
1230 development. As the <systemitem class="username">root</systemitem> user,
1231 perform the following commands:</para>
1235 mkdir /etc/apache2/ssl
1237 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1239 <para>You will be prompted for several items of information; enter
1240 the appropriate information for each item. The new files
1241 <filename>server.crt</filename> and <filename>server.key</filename> will
1242 be created in the directory
1243 <filename class="directory">/etc/apache2/ssl</filename> .</para>
1244 <note>This step generates a self-signed SSL certificate. You must install
1245 a proper SSL certificate for a public production system to avoid warning
1246 messages when users login to their account through the OPAC or when staff
1247 login through the Staff Client. For further information on
1248 installing a proper SSL certificate, see
1249 <xref linkend="serversideinstallation-ssl"/>.</note>
1251 <step xml:id="serversideinstallation-modify-apache">
1252 <title>Update Apache configuration files</title>
1253 <para>You must make several changes to an Apache configuration file.</para>
1254 <para>As the <systemitem class="username">root</systemitem> user
1255 edit the file <filename>/etc/apache2/sites-available/eg.conf</filename>
1256 and make the following changes:</para>
1259 <para>In the section
1260 <literal><Directory "/openils/var/cgi-bin"></literal>
1261 replace the line:</para>
1262 <literal>Allow from 10.0.0.0/8</literal>
1263 <para>with the line:</para>
1264 <literal>Allow from all</literal>
1265 <warning>This change allows access to your configuration
1266 CGI scripts from any workstation on any network. This is
1267 only a temporary change to expedite testing and should be
1268 removed after you have finished and successfully tested
1269 the Evergreen installation. See
1270 <xref linkend="serversideinstallation-postinstallation"/>
1271 for further details on removing this change after the
1272 Evergreen installation is complete.
1276 <para>Comment out the line:</para>
1277 <literal>Listen 443</literal>
1278 <para>since it conflicts with the same declaration in
1279 the configuration file:</para>
1280 <para><filename>/etc/apache2/ports.conf</filename>.</para>
1283 <para>The following updates are needed to allow the logs
1284 to function properly, but it may break other Apache
1285 applications on your server:</para>
1286 <para>Edit the Apache configuration file and
1287 change the lines:</para>
1289 <userinput>export APACHE_RUN_USER=www-data</userinput>
1290 <userinput>export APACHE_RUN_GROUP=www-data</userinput>
1292 <para>to instead read:</para>
1295 export APACHE_RUN_USER=opensrf
1296 export APACHE_RUN_GROUP=opensrf</userinput>
1301 <systemitem class="username">root</systemitem> user,
1302 edit the Apache configuration file
1303 <filename>/etc/apache2/apache2.conf</filename> and
1304 modify the value for <literal>KeepAliveTimeout</literal>
1305 and <literal>MaxKeepAliveRequests</literal> to match
1306 the following:</para>
1310 MaxKeepAliveRequests 100</userinput>
1314 <para>Further configuration changes to Apache may be
1315 necessary for busy systems. These changes increase the
1316 number of Apache server processes that are started to
1317 support additional browser connections.</para>
1319 <systemitem class="username">root</systemitem> user,
1320 edit the Apache configuration file
1321 <filename>/etc/apache2/apache2.conf</filename>, locate
1322 and modify the section related to <emphasis>prefork
1323 configuration</emphasis> to suit the load on your
1325 <programlisting language="xml"><![CDATA[
1326 <IfModule mpm_prefork_module>
1331 MaxRequestsPerChild 10000
1333 ]]></programlisting>
1338 <title>Enable the Evergreen web site</title>
1339 <para>Finally, you must enable the Evergreen web site. As the
1340 <systemitem class="username">root</systemitem> user, execute the
1341 following Apache configuration commands to disable the default
1342 <emphasis>It Works</emphasis> web page and enable the Evergreen
1343 web site, and then restart the Apache server:</para>
1347 # disable/enable web sites
1350 # restart the server
1351 /etc/init.d/apache2 reload</userinput>
1356 <step xml:id="serversideinstallation-opensrf-config">
1357 <title>Update the OpenSRF Configuration File</title>
1358 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1359 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1360 to update the Jabber usernames and passwords, and to specify the domain from
1361 which we will accept and to which we will make connections.</para>
1362 <para>If you are installing Evergreen on a single server and using the
1363 <systemitem class="domainname">private.localhost</systemitem> /
1364 <systemitem class="domainname">public.localhost</systemitem> domains,
1365 these will already be set to the correct values. Otherwise, search and replace
1366 to match your customized values.</para>
1367 <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
1368 shows common XPath syntax to indicate the approximate position within the XML
1369 file that needs changes. The right-hand side of the table shows the replacement
1371 <table xml:id="serversideinstallation-xpath-table-2">
1372 <?dbfo keep-together="always" ?>
1373 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
1374 <tgroup align="left" cols="2" colsep="1" rowsep="1">
1375 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
1376 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
1379 <entry>XPath location</entry>
1380 <entry>Value</entry>
1385 <entry>/config/opensrf/username</entry>
1387 <systemitem class="username">opensrf</systemitem>
1391 <entry>/config/opensrf/passwd </entry>
1392 <entry><systemitem class="domainname">private.localhost</systemitem>
1394 <systemitem class="username">opensrf</systemitem> user
1398 <entry>/config/gateway/username</entry>
1400 <systemitem class="username">opensrf</systemitem>
1404 <entry>/config/gateway/passwd</entry>
1405 <entry><systemitem class="domainname">public.localhost</systemitem>
1407 <systemitem class="username">opensrf</systemitem> user
1411 <entry>/config/routers/router/transport/username,
1412 first entry where server == public.localhost</entry>
1414 <systemitem class="username">router</systemitem>
1418 <entry>/config/routers/router/transport/password,
1419 first entry where server == public.localhost</entry>
1420 <entry><systemitem class="domainname">public.localhost</systemitem>
1422 <systemitem class="username">router</systemitem> user
1426 <entry>/config/routers/router/transport/username,
1427 second entry where server == private.localhost</entry>
1429 <systemitem class="username">router</systemitem>
1433 <entry>/config/routers/router/transport/password,
1434 second entry where server == private.localhost</entry>
1435 <entry><systemitem class="domainname">private.localhost</systemitem>
1437 <systemitem class="username">router</systemitem> user
1444 <step performance="optional">
1445 <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
1446 <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
1447 software installation automatically created a utility named <command>srfsh</command> (surf
1448 shell). This is a command line diagnostic tool for testing and interacting with
1449 OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
1450 Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration
1451 file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
1452 See <xref linkend="serversideinstallation-testing"/> for further information.</para>
1454 <step xml:id="serversideinstallation-opensrf-env">
1455 <title>Modify the OpenSRF Environment</title>
1456 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
1459 <para>As the <systemitem class="username">opensrf</systemitem> user,
1460 modify the shell configuration file <filename>~/.bashrc</filename> for
1461 user <systemitem class="username">opensrf</systemitem> by adding a Perl
1462 environmental variable, then execute the shell configuration file to load
1463 the new variables into your current environment.</para>
1466 # as the opensrf user:
1467 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
1468 . ~/.bashrc</userinput>
1470 <note>In a multi-server environment, you must add any
1471 modifications to <filename>~/.bashrc</filename> to the top of the file
1472 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
1473 return </literal>. This will allow headless (scripted) logins to load the
1474 correct environment.</note>
1478 <step performance="optional">
1479 <title>(OPTIONAL) Enable and Disable Language Localizations</title>
1480 <para>You can load translations such as Armenian (hy-AM), Canadian French
1481 (fr-CA), and others into the database to complete the translations available in
1482 the OPAC and Staff Client. For further information, see
1483 <xref linkend="languagesandlocalization"/>.</para>
1487 <section xml:id="serversideinstallation-fedora">
1488 <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
1489 <systemitem class="osname">Fedora 14</systemitem></title>
1491 <primary>Linux</primary>
1492 <secondary>Fedora</secondary>
1494 <para>This section outlines the installation process for the latest stable version of
1495 Evergreen on a <systemitem class="osname">Fedora 14</systemitem> system.
1496 See <xref linkend="serversideinstallation-ubuntudebian"/> for description of a
1497 similar installation on <systemitem class="osname">Ubuntu</systemitem> or
1498 <systemitem class="osname">Debian</systemitem> systems.</para>
1499 <para>In the following section you will download, unpack, install, configure and test the Evergreen
1500 system, including the Evergreen server and the PostgreSQL database system. You will make several
1501 configuration changes and adjustments to the software, including updates to configure the system
1502 for your own locale, and some updates needed to work around a few known issues.</para>
1504 <para>The following steps have been tested on the x86 (32-bit) and x86_64
1505 (64-bit) architecture of a <systemitem class="osname">Fedora 14</systemitem>
1506 image as of 2011-01-27.</para>
1507 <para>In the following instructions, you are asked to perform certain steps as
1508 either the <systemitem class="username">root</systemitem> user, the
1509 <systemitem class="username">opensrf</systemitem> user, or the
1510 <systemitem class="username">postgres</systemitem> user.</para>
1513 <para><systemitem class="osname">Fedora</systemitem> -- To become the
1514 <systemitem class="username">root</systemitem> user, issue the command
1515 <command>su -</command> and enter the password of the
1516 <systemitem class="username">root</systemitem> user.</para>
1519 <para>To switch from the <systemitem class="username">root</systemitem> user to a
1520 different user, issue the command <command>su - USERNAME</command>. For example, to
1521 switch from the <systemitem class="username">root</systemitem> user to the
1522 <systemitem class="username">opensrf</systemitem> user, issue the command
1523 <command>su - opensrf</command>. Once you have become a non-root user, to become the
1524 <systemitem class="username">root</systemitem> user again, simply issue the command
1525 <command>exit</command>.</para>
1528 <step xml:id="serversideinstallation-opensrf-2.0">
1529 <title>Install OpenSRF</title>
1530 <para>Evergreen software is integrated with and depends on the Open Service
1531 Request Framework (OpenSRF) software system. For further information on
1532 installing, configuring and testing OpenSRF, see
1533 <xref linkend="serversideinstallation-opensrf-1.6.3"/>.</para>
1534 <para>Follow the steps outlined in that section and run the specified tests to
1535 ensure that OpenSRF is properly installed and configured. Do
1536 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
1537 any further Evergreen installation steps until you have verified that OpenSRF
1538 has been successfully installed and tested.</para>
1541 <title>Download and Unpack Latest Evergreen Version</title>
1542 <para>The latest version of Evergreen can be found here:
1543 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
1544 As the <systemitem class="username">opensrf</systemitem> user, change to
1545 the directory <filename class="directory">/home/opensrf</filename> then
1546 download and extract Evergreen. The new subdirectory
1547 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename>
1548 will be created:</para>
1551 # as the opensrf user:
1553 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
1554 tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
1557 <step xml:id="serversideinstallation-installprereq-2.0">
1558 <title>Install Prerequisites to Build Evergreen</title>
1559 <para>In this section you will install and configure a set of prerequisites that will be
1560 used later in <xref linkend="serversideinstallation-configure-2.0"/> and
1561 <xref linkend="serversideinstallation-compile-2.0"/> to build the Evergreen software
1562 using the <command>make</command> utility.</para>
1563 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
1564 below to build the prerequisites from the software distribution that you just downloaded
1565 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
1566 example with the keyword corresponding to the name of one of the
1567 <systemitem class="osname">Linux</systemitem> distributions listed in the following
1568 distribution list. For example, to install the prerequisites for
1569 <systemitem class="osname">Fedora 13</systemitem> or
1570 <systemitem class="osname">Fedora 14</systemitem>, you would enter the command:
1571 <command>make -f Open-ILS/src/extras/Makefile.install fedora13</command>.</para>
1575 cd /home/opensrf/Evergreen-ILS-2.0.4
1576 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
1579 <step performance="optional">
1580 <title>(OPTIONAL) Install the PostgreSQL Server</title>
1582 <primary>databases</primary>
1583 <secondary>PostgreSQL</secondary>
1585 <para>Since the PostgreSQL server is usually a standalone server in multi-server
1586 production systems, the prerequisite installer Makefile in the previous section
1587 (see <xref linkend="serversideinstallation-installprereq-2.0"/>)
1588 does not automatically install PostgreSQL. You must install the PostgreSQL server
1589 yourself, either on the same system as Evergreen itself or on another system.
1590 If your PostgreSQL server is on a different system, just skip this step.
1591 If your PostgreSQL server will be on the same system as your Evergreen
1592 software, you can install the required PostgreSQL server packages as described
1593 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
1594 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1595 for more information.</para>
1597 <para>PostgreSQL version 8.4 is the minimum supported version to work
1598 with Evergreen 2.0. If you have an older version of PostgreSQL,
1599 you should upgrade before installing Evergreen. To find your current version
1600 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
1601 user execute the command <command>psql</command>, then type
1602 <userinput>SELECT version();</userinput> to get detailed information
1603 about your version of PostgreSQL.</para>
1606 <step performance="optional">
1607 <title>Install Perl Modules on PostgreSQL Server</title>
1608 <para>If PostgreSQL is running on the same system as your Evergreen software,
1609 then the Perl modules will automatically be available. Just skip this step.
1610 Otherwise, continue if your PostgreSQL server is running on another system,
1611 and install several Perl modules there. As the
1612 <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1613 is installed, then install the following Perl modules:</para>
1617 perl -MCPAN -e shell
1618 <prompt>cpan></prompt> install JSON::XS
1619 <prompt>cpan></prompt> install MARC::Record
1620 <prompt>cpan></prompt> install MARC::File::XML</userinput>
1622 <para>For more information on installing Perl Modules vist the official
1623 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1625 <primary>Perl</primary>
1626 <secondary>CPAN</secondary>
1629 <step xml:id="serversideinstallation-configure-2.0">
1630 <title>Configure Evergreen</title>
1631 <para>In this step you will use the <command>configure</command> and
1632 <command>make</command> utilities to configure Evergreen so it can be compiled
1633 and linked later in <xref linkend="serversideinstallation-compile-2.0"/>.</para>
1634 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1635 the Evergreen build directory and execute these commands:</para>
1638 # as the opensrf user:
1639 cd /home/opensrf/Evergreen-ILS-2.0.4
1640 ./configure --prefix=/openils --sysconfdir=/openils/conf
1644 <step xml:id="serversideinstallation-compile-2.0">
1645 <title>Compile, Link and Install Evergreen</title>
1646 <para>In this step you will actually compile, link and install Evergreen and the
1647 default Evergreen Staff Client.</para>
1648 <para>As the <systemitem class="username">root</systemitem> user, return to the
1649 Evergreen build directory and use the <command>make</command> utility as shown
1654 cd /home/opensrf/Evergreen-ILS-2.0.4
1655 make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
1657 <para>The Staff Client will also be automatically built, but you must remember
1658 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1659 Staff Client you will use to connect to the Evergreen server.</para>
1660 <para>The above commands will create a new subdirectory
1661 <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
1662 containing the Staff Client.</para>
1663 <para>To complete the Staff Client installation, as the
1664 <systemitem class="username">root</systemitem> user execute the following commands
1665 to create a symbolic link named <emphasis>server</emphasis> in the head of the
1666 Staff Client directory <filename class="directory">/openils/var/web/xul</filename>
1667 that points to the subdirectory <filename class="directory">/server</filename>
1668 of the new Staff Client build:</para>
1672 cd /openils/var/web/xul
1673 ln -sf rel_2_0_4/server server</userinput>
1677 <title>Copy the OpenSRF Configuration Files</title>
1678 <para>In this step you will replace some OpenSRF configuration files that you set up
1679 earlier in <xref linkend="serversideinstallation-opensrf-2.0"/> when you installed
1680 and tested OpenSRF.</para>
1681 <para>You must copy several example OpenSRF configuration files into place after first
1682 creating backup copies for troubleshooting purposes, then change all the file ownerships
1683 to <systemitem class="username">opensrf</systemitem>.
1684 As the <systemitem class="username">root</systemitem> user, execute the following
1690 cp opensrf.xml opensrf.xml.BAK
1691 cp opensrf_core.xml opensrf_core.xml.BAK
1692 cp opensrf.xml.example opensrf.xml
1693 cp opensrf_core.xml.example opensrf_core.xml
1694 cp oils_web.xml.example oils_web.xml
1695 chown -R opensrf:opensrf /openils/</userinput>
1699 <title>Create and Configure PostgreSQL Database</title>
1701 <primary>databases</primary>
1702 <secondary>PostgreSQL</secondary>
1704 <para>In this step you will create the Evergreen database. In the
1705 commands below, remember to adjust the path of the
1706 <emphasis role="bold">contrib</emphasis> repository to match your
1707 PostgreSQL server layout. For example, if you built PostgreSQL from
1708 source the path would be
1709 <filename class="directory">/usr/local/share/contrib</filename>
1710 , and if you installed the PostgreSQL 8.4 server packages on
1711 <systemitem class="osname">Ubuntu</systemitem>, the path would be
1712 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1715 <title>Start the PostgreSQL service</title>
1716 <para>As the <systemitem class="username">root</systemitem>
1717 user on the PostgreSQL system, initialize the PostgreSQL cluster
1718 and start the PostgreSQL service:</para>
1722 service initdb postgresql
1723 /etc/init.d/postgresql start</userinput>
1727 <title>Create and configure the database</title>
1728 <para>As the <systemitem class="username">postgres</systemitem>
1729 user on the PostgreSQL system create the PostgreSQL database,
1730 then set some internal paths:</para>
1733 # as the postgres user:
1734 createdb evergreen -E UTF8 -T template0
1735 createlang plperl evergreen
1736 createlang plperlu evergreen
1737 createlang plpgsql evergreen</userinput>
1739 <para>Continue as the <systemitem class="username">postgres</systemitem>
1740 user and execute the SQL scripts as shown below (remember to adjust the
1741 paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1742 your installed PostgreSQL version, for example
1743 <literal>"8.4"</literal>).</para>
1746 # as the postgres user:
1747 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1748 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
1749 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
1752 <step xml:id="serversideinstallation-postgresqlcreateuser-2.0">
1753 <title>Create <systemitem class="username">evergreen</systemitem>
1754 PostgreSQL user</title>
1755 <para>As the <systemitem class="username">postgres</systemitem>
1756 user on the PostgreSQL system, create a new PostgreSQL user
1757 named <systemitem class="username">evergreen</systemitem> and
1758 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1759 with an appropriate new password):</para>
1762 # as the postgres user:
1763 createuser -P -s evergreen</userinput>
1765 Enter password for new role: <userinput>NEWPASSWORD</userinput>
1766 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1770 <title>Enable IPv4 and IPv6 connections</title>
1771 <para>As the root user, enable IPv4 and IPv6 connections to the
1772 PostgreSQL server. For a single-server instance, enable
1773 password-protected connections from the Evergreen user to the
1774 Evergreen database on localhost by adding the following lines to
1775 <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
1780 # IPv4 local connections:
1781 host evergreen evergreen 127.0.0.1/32 md5
1782 # IPv6 local connections:
1783 host evergreen evergreen ::1/128 md5</userinput>
1785 <para>Then, as the root user, restart the PostgreSQL server to
1786 make that configuration take effect:</para>
1790 /etc/init.d/postgresql restart</userinput>
1794 <title>Create database schema</title>
1795 <para>In this step you will create the database schema and configure your
1796 system with the corresponding database authentication details for the
1797 <emphasis>evergreen</emphasis> database user that you just created in
1798 <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.</para>
1799 <para>As the <systemitem class="username">root</systemitem> user, enter
1800 the following commands and replace <emphasis>HOSTNAME, PORT,
1801 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1806 cd /home/opensrf/Evergreen-ILS-2.0.4
1807 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1808 --service all --create-schema --create-offline \
1809 --hostname HOSTNAME --port PORT \
1810 --user evergreen --password PASSWORD \
1811 --database DATABASENAME --admin-user ADMIN-USER \
1812 --admin-pass ADMIN-PASSWORD </userinput>
1814 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1815 <emphasis role="bold">localhost</emphasis> and
1816 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1817 Of course, values for <emphasis>PASSWORD</emphasis> and
1818 <emphasis>DATABASENAME</emphasis> must match the values you used in
1819 <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.
1820 The <option>admin-user</option> and <option>admin-pass</option> options will
1821 specify the Evergreen administrator account's username and password. This was
1822 changed for security reasons, it was previously admin/open-ils</para>
1823 <para>As the command executes, you may see warnings similar to:
1824 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1825 you may see one warning per schema) but they can be safely ignored.</para>
1826 <note>If you are entering the above command on a single line, do not
1827 include the <literal>\</literal> (backslash) characters. If you are using
1828 the <command>bash</command> shell, these should only be used at the end of
1829 a line at a <command>bash</command> prompt to indicate that the command is
1830 continued on the next line.</note>
1835 <title>Configure the Apache web server</title>
1837 <primary>web server</primary>
1838 <secondary>Apache</secondary>
1840 <para>In this step you will configure the Apache web server to support Evergreen
1842 <para>First, you must install some additional Apache configuration files. Then you will
1843 create a new Security Certificate. Finally, you must make several changes to Apache
1844 configuration files.</para>
1847 <title>Copy Apache configuration files</title>
1848 <para>You must copy the Apache configuration files from the
1849 Evergreen installation directory to the Apache directory. As the
1850 <systemitem class="username">root</systemitem> user, perform the
1851 following commands:</para>
1855 cd /home/opensrf/Evergreen-ILS-2.0.4
1856 cp Open-ILS/examples/apache/eg.conf /etc/httpd/conf.d/
1857 cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
1858 cp Open-ILS/examples/apache/startup.pl /etc/httpd/</userinput>
1861 <step xml:id="serversideinstallation-createsslcertificate-2.0">
1862 <title>Create a Security Certificate</title>
1863 <para>In this step you will create a new Security Certificate (SSL Key)
1864 for the Apache server using the <command>openssl</command> command. For a
1865 public production server you must configure or purchase a signed SSL
1866 certificate, but for now you can just use a self-signed certificate and
1867 accept the warnings in the Staff Client and browser during testing and
1868 development. As the <systemitem class="username">root</systemitem> user,
1869 perform the following commands:</para>
1873 mkdir /etc/httpd/ssl
1875 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1877 <para>You will be prompted for several items of information; enter
1878 the appropriate information for each item. The new files
1879 <filename>server.crt</filename> and <filename>server.key</filename> will
1880 be created in the directory
1881 <filename class="directory">/etc/httpd/ssl</filename> .</para>
1882 <note>This step generates a self-signed SSL certificate. You must install
1883 a proper SSL certificate for a public production system to avoid warning
1884 messages when users login to their account through the OPAC or when staff
1885 login through the Staff Client. For further information on
1886 installing a proper SSL certificate, see
1887 <xref linkend="serversideinstallation-ssl"/>.</note>
1889 <step xml:id="serversideinstallation-modify-apache-2.0">
1890 <title>Update Apache configuration files</title>
1891 <para>You must make several changes to two Apache configuration files.</para>
1892 <para>As the <systemitem class="username">root</systemitem>
1893 user, edit the file <filename>/etc/httpd/conf.d/eg.conf</filename>
1894 and make the following changes:</para>
1897 <para>Change all instances of <literal>apache2</literal>
1898 to <literal>httpd</literal> .</para>
1901 <para>In the section
1902 <literal><Directory "/openils/var/cgi-bin"></literal>
1903 replace the line:</para>
1904 <literal>Allow from 10.0.0.0/8</literal>
1905 <para>with the line:</para>
1906 <literal>Allow from all</literal>
1907 <warning>This change allows access to your configuration
1908 CGI scripts from any workstation on any network. This is
1909 only a temporary change to expedite testing and should be
1910 removed after you have finished and successfully tested
1911 the Evergreen installation. See
1912 <xref linkend="serversideinstallation-postinstallation"/>
1913 for further details on removing this change after the
1914 Evergreen installation is complete.
1918 <para>Comment out the line:</para>
1919 <literal>Listen 443</literal>
1920 <para>since it conflicts with the same declaration in
1921 the configuration file:</para>
1922 <para><filename>/etc/httpd/conf.d/ssl.conf</filename>.</para>
1926 As the <systemitem class="username">root</systemitem> user, edit the
1927 Apache configuration file <filename>/etc/httpd/conf.d/httpd.conf</filename>
1928 and make the following changes:</para>
1931 Change <literal>User apache</literal> to
1932 <literal>User opensrf</literal></listitem>
1934 Change <literal>KeepAlive</literal> to
1935 <literal>On</literal></listitem>
1937 Change <literal>KeepAliveTimeout</literal> to
1938 <literal>1</literal></listitem>
1944 <title>Update the System Dynamic Library Path</title>
1945 <para>You must update the system dynamic library path to force your
1946 system to recognize the library <literal>dbdpgsql.so</literal>. As the
1947 <systemitem class="username">root</systemitem> user, do this by creating
1948 the new file <filename>/etc/ld.so.conf.d/eg.conf</filename> containing two
1949 new library paths, then run the command <command>ldconfig</command> to
1950 automatically read the file and modify the system dynamic library
1955 echo "/usr/lib/dbd" > /etc/ld.so.conf.d/eg.conf
1956 echo "/usr/lib64/dbd/" >> /etc/ld.so.conf.d/eg.conf
1957 ldconfig</userinput>
1960 <step xml:id="serversideinstallation-opensrf-config-2.0">
1961 <title>Update the OpenSRF Configuration File</title>
1962 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1963 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1964 and update the Jabber usernames and passwords, and specify the domain from
1965 which we will accept and to which we will make connections.</para>
1966 <para>If you are installing Evergreen on a single server and using the
1967 <systemitem class="domainname">private.localhost</systemitem> /
1968 <systemitem class="domainname">public.localhost</systemitem> domains,
1969 these will already be set to the correct values. Otherwise, search and replace
1970 to match your customized values.</para>
1971 <para>See the table <xref linkend="serversideinstallation-xpath-table-2"/>
1972 for examples of the XPath syntax you will find in this XML file. The syntax
1973 indicates the approximate position within the file that needs changes.</para>
1975 <step xml:id="serversideinstallation-opensrf-env-2.0">
1976 <title>Modify the OpenSRF Environment</title>
1977 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
1980 <para>As the <systemitem class="username">opensrf</systemitem> user,
1981 modify the shell configuration file <filename>~/.bashrc</filename> for
1982 user <systemitem class="username">opensrf</systemitem> by adding a Perl
1983 environmental variable, then execute the shell configuration file to load
1984 the new variables into your current environment:</para>
1987 # as the opensrf user:
1988 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
1989 . ~/.bashrc</userinput>
1991 <note>In a multi-server environment, you must add any
1992 modifications to <filename>~/.bashrc</filename> to the top of the file
1993 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
1994 return </literal>. This will allow headless (scripted) logins to load the
1995 correct environment.</note>
2000 <title>Configuring Fedora Security</title>
2001 <para><systemitem class="osname">Fedora</systemitem> is a very secure
2002 system out of the box, including a very restrictive firewall and an
2003 automatically enabled set of SELinux system policies to prevent
2004 unauthorized access to system resources. Unfortunately, these secure
2005 system policies can interfere with the normal operation of
2006 applications like Evergreen.</para>
2007 <para>Until a person with the required SELinux skills can offer a
2008 nuanced set of policies appropriate for Evergreen, the simplest way to
2009 test and develop against a <systemitem class="osname">Fedora</systemitem>
2010 server is to completely disable the firewall and SELinux policies.</para>
2013 <title>Disabling the Fedora firewall</title>
2014 <para>To disable the <systemitem class="osname">Fedora</systemitem>
2015 firewall until your next reboot, issue the
2016 following command as the root user:</para>
2020 /etc/init.d/iptables stop</userinput>
2022 <para>To disable the <systemitem class="osname">Fedora</systemitem>
2023 firewall permanently, issue the following
2024 command as the root user:</para>
2028 chkconfig iptables off</userinput>
2030 <para>This change will take effect when you reboot your system.</para>
2033 <title>Disabling the SELinux policies</title>
2034 <para>To disable the SELinux policies until your next reboot, issue
2035 the following command as the root user:</para>
2039 /usr/sbin/setenforce 0</userinput>
2041 <para>To disable the SELinux policies permanently, as the root user
2042 edit the file <filename>/etc/sysconfig/selinux</filename> and make the
2043 following change:</para>
2047 SELINUX=permissive</userinput>
2049 <para>This change will take effect when you reboot your system.</para>
2055 <section xml:id="serversideinstallation-starting">
2056 <title>Starting Evergreen</title>
2057 <para>In this section you will learn how to start the Evergreen services.
2058 For completeness, instructions for stopping Evergreen can be found later in
2059 <xref linkend="serversideinstallation-stopping"/>.</para>
2062 <para>As the <systemitem class="username">root</systemitem> user,
2063 start the <systemitem class="service">ejabberd</systemitem>,
2064 <systemitem class="service">memcached</systemitem>, and
2065 <systemitem class="service">PostgreSQL</systemitem> services
2066 (if they aren't already running) as follows:</para>
2070 /etc/init.d/ejabberd start
2071 /etc/init.d/memcached start
2072 /etc/init.d/postgresql start</userinput>
2076 <para>If you want to have these services run automatically every time
2077 you boot your server, issue the following commands as the root
2082 chkconfig --levels 2345 ejabberd on
2083 chkconfig --levels 2345 memcached on
2084 chkconfig --levels 2345 postgresql on</userinput>
2088 <para>As the <systemitem class="username">opensrf</systemitem> user,
2089 start the OpenSRF <systemitem class="service">router</systemitem> ,
2090 <systemitem class="service">Perl</systemitem>, and <systemitem class="service">C</systemitem> services. The <option>-l</option> flag in
2091 the following command is only necessary if you want to force Evergreen to
2092 treat the hostname as <literal>'localhost'</literal>. You should not
2093 use the '-l' flag if you configured <filename>opensrf.xml</filename>
2094 using the real hostname of your machine as returned by: <literal>perl
2095 -ENet::Domain 'print Net::Domain::hostfqdn() . “\n”;'</literal> .
2096 As the opensrf user, execute this command:</para>
2099 # as the opensrf user:
2100 osrf_ctl.sh -l -a start_all</userinput>
2104 <para>If you receive an error message similar to
2105 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
2106 environment variable <envar>PATH</envar> does not include the
2107 directory <filename class="directory">/openils/bin</filename>.
2108 As the <systemitem class="username">opensrf</systemitem> user,
2109 edit the configuration file <filename>~/.bashrc</filename> and
2110 add the following line:
2111 <literal>export PATH=$PATH:/openils/bin</literal></para>
2114 <para>If you receive an error message similar to <emphasis>Can't
2115 locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
2116 aborted</emphasis>, then your environment variable
2117 <emphasis role="bold">PERL5LIB</emphasis> does not include the
2118 directory <filename class="directory">/openils/lib/perl5</filename>.
2119 This should have been set by <filename>~/.bashrc</filename> when you
2120 logged in as the <systemitem class="username">opensrf</systemitem>
2121 user, but you can manually set it using the following command:
2122 <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
2127 <para>In this step you will generate the Web files needed by the Staff Client
2128 and catalog, as well as update the proximity of locations in the Organizational
2129 Unit tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
2130 <para>You must do this the first time you start Evergreen and after making any
2131 changes to the library hierarchy.</para>
2132 <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
2133 following command and review the results as shown in this example:</para>
2136 # as the opensrf user:
2138 ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
2140 Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
2141 Updating fieldmapper
2142 Updating web_fieldmapper
2144 removing OrgTree from the cache for locale hy-AM...
2145 removing OrgTree from the cache for locale cs-CZ...
2146 removing OrgTree from the cache for locale en-CA...
2147 removing OrgTree from the cache for locale en-US...
2148 removing OrgTree from the cache for locale fr-CA...
2149 removing OrgTree from the cache for locale ru-RU...
2150 Updating OrgTree HTML
2151 Updating locales selection HTML
2152 Updating Search Groups
2153 Refreshing proximity of org units
2154 Successfully updated the organization proximity
2155 Done</computeroutput>
2159 <para>As the <systemitem class="username">root</systemitem> user, restart the
2160 Apache Web server:</para>
2164 /etc/init.d/httpd restart</userinput>
2166 <note>If the Apache Web server was running when you started the OpenSRF
2167 services, you might not be able to successfully log into the OPAC or Staff
2168 Client until the Apache Web server has been restarted.</note>
2172 <section xml:id="serversideinstallation-testing">
2173 <title>Testing Your Evergreen Installation</title>
2174 <para>This section describes several simple tests you can perform to verify that the Evergreen
2175 server-side software has been installed and configured properly and is running as
2177 <simplesect xml:id="serversideinstallation-testing-connections">
2178 <title>Testing Connections to Evergreen</title>
2179 <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
2180 <command>srfsh</command> application and try logging onto the Evergreen server using the default
2181 administrator username and password. Following is sample output generated by executing
2182 <command>srfsh</command> after a successful Evergreen installation. For help with
2183 <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
2184 As the <systemitem class="username">opensrf</systemitem> user,
2185 execute the following command and review the results as shown in this example to test
2186 your Evergreen connection:</para>
2189 # as the opensrf user:
2190 /openils/bin/srfsh</userinput>
2192 srfsh% <userinput>login admin open-ils</userinput>
2193 Received Data: "250bf1518c7527a03249858687714376"
2194 ------------------------------------
2195 Request Completed Successfully
2196 Request Time in seconds: 0.045286
2197 ------------------------------------
2200 "textcode":"SUCCESS",
2203 "stacktrace":"oils_auth.c:304",
2205 "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
2209 ------------------------------------
2210 Request Completed Successfully
2211 Request Time in seconds: 1.336568
2212 ------------------------------------</computeroutput>
2214 <para>If this does not work, try the following:</para>
2217 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
2218 utility <filename>settings-tester.pl</filename> to review your Evergreen
2219 installation for any system configuration problems:</para>
2222 # as the opensrf user:
2224 ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
2226 <para>If the output of <command>settings-tester.pl</command> does not help
2227 you find the problem, please do not make any significant changes to your
2228 configuration.</para>
2231 <para>Follow the steps in the troubleshooting guide in
2232 <xref linkend="troubleshooting"/>.</para>
2235 <para>If you have followed the entire set of installation steps listed here
2236 closely, you are probably extremely close to a working system. Gather your
2237 configuration files and log files and contact the
2238 <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
2239 for assistance before making any drastic changes to your system
2240 configuration.</para>
2244 <simplesect xml:id="serversideinstallation-running-staffclient">
2245 <title>Testing the Staff Client on Linux</title>
2246 <para>In this section you will confirm that a basic login on the Staff Client works
2248 <para>Run the Evergreen Staff Client on your <systemitem class="osname">Fedora</systemitem>
2249 system by using the application
2250 <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
2251 version 3.0 and later on Ubuntu and Debian distributions).</para>
2252 <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
2257 xulrunner /home/opensrf/Evergreen-ILS-2.0.4/Open-ILS/xul/staff_client/build/application.ini</userinput>
2259 <para>A login screen for the Staff Client similar to this should appear:</para>
2261 <alt>Logging into the Staff Client</alt>
2263 <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>
2266 <para>First, add the name of your Evergreen server to the field
2267 <literal>Hostname</literal> in the <literal>Server</literal> section. You will
2268 probably want to use <literal>127.0.0.1</literal>. After adding the server
2269 name, click <guibutton>Re-Test Server</guibutton>. You should now see the
2270 messages <literal>200:OK</literal> in the fields <literal>Status</literal> and
2271 <literal>Version</literal>.</para>
2272 <para>Because this is the initial run of the Staff Client, you will see a warning in the
2273 upper-right saying: <emphasis role="bold">Not yet configured for the specified
2274 server</emphasis>. To continue, you must assign a workstation name.</para>
2275 <para>Try to log into the Staff Client with the admin username and password you created
2276 during installation. If the login is successful, you will see the following
2279 <alt>Logging into the Staff Client</alt>
2281 <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>
2284 <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the
2285 main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>
2287 <alt>Adding an SSL Exception in the Staff Client</alt>
2289 <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>
2292 <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm
2293 Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the
2294 main window and try to log in again.</para>
2296 <simplesect xml:id="serversideinstallation-starting-apache-server">
2297 <title>Testing the Apache Web Server</title>
2298 <para>In this section you will test the Apache configuration file(s), then restart the
2299 Apache web server.</para>
2300 <para>As the <emphasis role="bold">root</emphasis> user, execute the following
2301 commands. The use of <emphasis>restart</emphasis> will force the new Evergreen
2302 modules to be reloaded even if the Apache server is already running.
2303 Any problems found with your configuration files should be displayed:</para>
2307 /etc/init.d/httpd configtest && /etc/init.d/httpd restart</userinput>
2310 <simplesect xml:id="serversideinstallation-stopping">
2311 <title>Stopping Evergreen</title>
2312 <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the
2313 Evergreen services. For completeness, following are instructions for stopping the
2314 Evergreen services.</para>
2315 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
2316 services by using the following command:</para>
2319 # as the opensrf user
2320 # stop the server; use "-l" to force hostname to be "localhost"
2321 osrf_ctl.sh -l -a stop_all</userinput>
2323 <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the
2324 <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the
2325 fully qualified domain name for the system on which it will execute. That hostname may
2326 have been specified in the configuration file <filename>opensrf.xml</filename>, which
2327 you configured in a previous step.</note>
2330 <section xml:id="serversideinstallation-postinstallation">
2331 <title>Post-Installation Chores</title>
2332 <para>There are several additional steps you may need to complete after Evergreen has been
2333 successfully installed and tested. Some steps may not be needed (e.g., setting up support for
2336 <title>Remove temporary Apache configuration changes</title>
2337 <para>You modified the Apache configuration file
2338 <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
2339 temporary measure to expedite testing (see
2340 <xref linkend="serversideinstallation-modify-apache"/> for further information).
2341 Those changes must now be reversed in order to deny unwanted access to your
2342 CGI scripts from users on other public networks.</para>
2345 <emphasis>This temporary network update was done to expedite
2346 testing. You <emphasis role="bold">must</emphasis> correct
2347 this for a public production system.</emphasis>
2350 <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
2351 file again and comment out the line <literal>Allow from all</literal> and uncomment the
2352 line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
2353 address scheme.</para>
2355 <section xml:id="serversideinstallation-ssl">
2356 <title>Configure a permanent SSL key</title>
2357 <para>You used the command <command>openssl</command> in an earlier step to
2358 temporarily create a new SSL key for the Apache server (see
2359 <xref linkend="serversideinstallation-createsslcertificate-2.0"/> for further
2360 information). This self-signed security certificate was adequate during
2361 testing and development, but will continue to generate warnings in the Staff
2362 Client and browser. For a public production server you should configure or
2363 purchase a signed SSL certificate.</para>
2364 <para>There are several open source software solutions that provide schemes to
2365 generate and maintain public key security certificates for your library
2366 system. Some popular projects are listed below; please review them for
2367 background information on why you need such a system and how you can provide
2371 <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
2374 <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
2377 <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
2382 <emphasis>The temporary SSL key was only created to expedite
2383 testing. You should install a proper SSL certificate for a public
2384 production system.</emphasis>
2389 <title>(OPTIONAL) IP-Redirection</title>
2390 <para>By default, Evergreen is configured so searching the OPAC always starts in the
2391 top-level (regional) library rather than in a second-level (branch) library. Instead,
2392 you can use "IP-Redirection" to change the default OPAC search location to use the IP
2393 address range assigned to the second-level library where the seach originates. You must
2394 configure these IP ranges by creating the configuration file
2395 <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
2396 <filename>/etc/apache2/startup.pl</filename>.</para>
2397 <para>First, copy the sample file
2398 <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>
2399 to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
2400 line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
2401 the IP address ranges for your library system. Add new lines to represent the IP address
2402 range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
2403 values for each branch library found in the table
2404 <literal>actor.org_unit</literal>.</para>
2405 <para>Finally, modify the Apache startup script
2406 <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
2407 restarting the Apache server:</para>
2408 <programlisting language="xml"><![CDATA[
2409 # - Uncomment the following 2 lines to make use of the IP redirection code
2410 # - The IP file should contain a map with the following format:
2411 # - actor.org_unit.shortname <start_ip> <end_ip>
2412 # - e.g. LIB123 10.0.0.1 10.0.0.254
2413 use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
2414 OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
2415 ]]></programlisting>
2418 <title>(OPTIONAL) Set Up Support For Reports</title>
2419 <para>Evergreen reports are extremely powerful but require some simple configuration.
2420 See <xref linkend="report_starting_reporter_service"/> for information on starting and
2421 stopping the Reporter daemon processes.</para>