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-2.0.0">
92 <primary>OpenSRF</primary>
93 <secondary>installation</secondary>
95 <title>Installing OpenSRF 2.0.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-2.0.0.tar.gz"></ulink> .
169 As the <systemitem class="username">opensrf</systemitem> user, change to
170 the directory <filename class="directory">/home/opensrf</filename> then download
171 and extract OpenSRF. The new subdirectory
172 <filename class="directory">/home/opensrf/opensrf-2.0.0</filename> will be created:</para>
175 # as the opensrf user:
177 wget http://evergreen-ils.org/downloads/opensrf-2.0.0.tar.gz
178 tar zxf opensrf-2.0.0.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-2.0.0
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-2.0.0
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-2.0.0
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-2.0.0"/>.</para>
879 <para>Follow the steps outlined in that section and run the specified tests to
880 ensure that OpenSRF is properly installed and configured. Do
881 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
882 any further Evergreen installation steps until you have verified that OpenSRF
883 has been successfully installed and tested.</para>
886 <title>Download and Unpack Latest Evergreen Version</title>
887 <para>The latest version of Evergreen can be found here:
888 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz"></ulink> .
889 As the <systemitem class="username">opensrf</systemitem> user, change to
890 the directory <filename class="directory">/home/opensrf</filename> then download
891 and extract Evergreen. The new subdirectory
892 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.7</filename>
893 will be created:</para>
896 # as the opensrf user:
898 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz
899 tar zxf Evergreen-ILS-2.0.7.tar.gz</userinput>
902 <step xml:id="serversideinstallation-installprereq">
903 <title>Install Prerequisites to Build Evergreen</title>
904 <para>In this section you will install and configure a set of prerequisites that will be
905 used later in <xref linkend="serversideinstallation-configure"/> and
906 <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
907 using the <command>make</command> utility.</para>
908 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
909 below to build the prerequisites from the software distribution that you just downloaded
910 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
911 example with the keyword corresponding to the name of one of the
912 <systemitem class="osname">Linux</systemitem> distributions listed in the in the
913 distribution keywords table <xref linkend="serversideinstallation-keywords-evergreen"/>.
914 For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
915 enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
916 ubuntu-lucid</command>.</para>
920 cd /home/opensrf/Evergreen-ILS-2.0.7
921 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
924 <table xml:id="serversideinstallation-keywords-evergreen">
925 <?dbfo keep-together="always" ?>
926 <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
927 <tgroup align="left" cols="2" colsep="1" rowsep="1">
928 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
929 <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
932 <entry>Keyword</entry>
933 <entry>Linux Version</entry>
938 <entry>debian-squeeze</entry>
939 <entry>Debian "Squeeze" (6.0)</entry>
942 <entry>debian-lenny</entry>
943 <entry>Debian "Lenny" (5.0)</entry>
946 <entry>ubuntu-hardy</entry>
947 <entry>Ubuntu "Hardy Heron" (8.04)</entry>
950 <entry>ubuntu-lucid</entry>
951 <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
954 <entry>fedora13</entry>
955 <entry>Fedora "Goddard" (13)</entry>
958 <entry>centos</entry>
959 <entry>CentOS 5</entry>
963 <entry>Red Hat Enterprise Linux 5</entry>
969 <primary>Linux</primary>
970 <secondary>Debian</secondary>
973 <primary>Linux</primary>
974 <secondary>Fedora</secondary>
977 <primary>Linux</primary>
978 <secondary>Ubuntu</secondary>
981 <primary>Linux</primary>
982 <secondary>CentOS</secondary>
985 <primary>Linux</primary>
986 <secondary>Red Hat</secondary>
989 <step performance="optional">
990 <title>(OPTIONAL) Install the PostgreSQL Server</title>
992 <primary>databases</primary>
993 <secondary>PostgreSQL</secondary>
995 <para>Since the PostgreSQL server is usually a standalone server in multi-server
996 production systems, the prerequisite installer Makefile in the previous section
997 (see <xref linkend="serversideinstallation-installprereq"/>)
998 does not automatically install PostgreSQL. You must install the PostgreSQL server
999 yourself, either on the same system as Evergreen itself or on another system.
1000 If your PostgreSQL server is on a different system, just skip this step.
1001 If your PostgreSQL server will be on the same system as your Evergreen
1002 software, you can install the required PostgreSQL server packages as described
1003 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
1004 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1005 for more information.</para>
1007 <para>PostgreSQL version 8.4 is the minimum supported version to work
1008 with Evergreen 2.0. If you have an older version of PostgreSQL,
1009 you should upgrade before installing Evergreen. To find your current version
1010 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
1011 user execute the command <command>psql</command>, then type
1012 <userinput>SELECT version();</userinput> to get detailed information
1013 about your version of PostgreSQL.</para>
1016 <step performance="optional">
1017 <title>Install Perl Modules on PostgreSQL Server</title>
1018 <para>If PostgreSQL is running on the same system as your Evergreen software,
1019 then the Perl modules will automatically be available. Just skip this step.
1020 Otherwise, continue if your PostgreSQL server is running on another system
1021 and install several Perl modules there. As the
1022 <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1023 is installed, then install the following Perl modules:</para>
1026 aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
1027 perl -MCPAN -e shell
1028 <prompt>cpan></prompt> Business::ISBN
1029 <prompt>cpan></prompt> install JSON::XS
1030 <prompt>cpan></prompt> Library::CallNumber::LC
1031 <prompt>cpan></prompt> install MARC::Record
1032 <prompt>cpan></prompt> install MARC::File::XML
1033 <prompt>cpan></prompt> cpan UUID::Tiny</userinput>
1035 <para>For more information on installing Perl Modules vist the official
1036 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1038 <primary>Perl</primary>
1039 <secondary>CPAN</secondary>
1043 <title>Update the System Dynamic Library Path</title>
1044 <para>You must update the system dynamic library path to force your system to recognize
1045 the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
1046 do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
1047 containing two new library paths, then run the command <command>ldconfig</command> to
1048 automatically read the file and modify the system dynamic library path:</para>
1052 echo "/usr/local/lib" > /etc/ld.so.conf.d/osrf.conf
1053 echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
1054 ldconfig</userinput>
1057 <step performance="optional">
1058 <title>Restart the PostgreSQL Server</title>
1059 <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
1060 the <systemitem class="username">root</systemitem> user you must restart
1061 PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
1062 running on another system, you may skip this step.
1063 As the <systemitem class="username">opensrf</systemitem> user,
1064 execute the following command (remember to replace
1065 <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
1066 for example <literal>8.4</literal>):</para>
1069 # as the opensrf user:
1070 /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
1073 <step xml:id="serversideinstallation-configure">
1074 <title>Configure Evergreen</title>
1075 <para>In this step you will use the <command>configure</command> and
1076 <command>make</command> utilities to configure Evergreen so it can be compiled
1077 and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
1078 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1079 the Evergreen build directory and execute these commands:</para>
1082 # as the opensrf user:
1083 cd /home/opensrf/Evergreen-ILS-2.0.7
1084 ./configure --prefix=/openils --sysconfdir=/openils/conf
1088 <step xml:id="serversideinstallation-compile">
1089 <title>Compile, Link and Install Evergreen</title>
1090 <para>In this step you will actually compile, link and install Evergreen and the
1091 default Evergreen Staff Client.</para>
1092 <para>As the <systemitem class="username">root</systemitem> user, return to the
1093 Evergreen build directory and use the <command>make</command> utility as shown
1098 cd /home/opensrf/Evergreen-ILS-2.0.7
1099 make STAFF_CLIENT_BUILD_ID=rel_2_0_7 install</userinput>
1101 <para>The Staff Client will also be automatically built, but you must remember
1102 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1103 Staff Client you will use to connect to the Evergreen server.</para>
1104 <para>The above commands will create a new subdirectory
1105 <filename class="directory">/openils/var/web/xul/rel_2_0_7</filename>
1106 containing the Staff Client.</para>
1107 <para>To complete the Staff Client installation, as the
1108 <systemitem class="username">root</systemitem> user execute the following commands to
1109 create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
1110 directory <filename class="directory">/openils/var/web/xul</filename> that points to the
1111 subdirectory <filename class="directory">/server</filename> of the new Staff Client
1116 cd /openils/var/web/xul
1117 ln -sf rel_2_0_7/server server</userinput>
1121 <title>Copy the OpenSRF Configuration Files</title>
1122 <para>In this step you will replace some OpenSRF configuration files that you set up in
1123 <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
1124 tested OpenSRF.</para>
1125 <para>You must copy several example OpenSRF configuration files into place after first
1126 creating backup copies for troubleshooting purposes, then change all the file ownerships
1127 to <systemitem class="username">opensrf</systemitem>.
1128 As the <systemitem class="username">root</systemitem> user, execute the following
1134 cp opensrf.xml opensrf.xml.BAK
1135 cp opensrf_core.xml opensrf_core.xml.BAK
1136 cp opensrf.xml.example opensrf.xml
1137 cp opensrf_core.xml.example opensrf_core.xml
1138 cp oils_web.xml.example oils_web.xml
1139 chown -R opensrf:opensrf /openils/</userinput>
1143 <title>Create and Configure PostgreSQL Database</title>
1145 <primary>databases</primary>
1146 <secondary>PostgreSQL</secondary>
1148 <para>In this step you will create the Evergreen database. In the commands
1149 below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
1150 repository to match your PostgreSQL server
1151 layout. For example, if you built PostgreSQL from source the path would be
1152 <filename class="directory">/usr/local/share/contrib</filename> , and if you
1153 installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
1155 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1158 <title>Create and configure the database</title>
1159 <para>As the <systemitem class="username">postgres</systemitem>
1160 user on the PostgreSQL system create the PostgreSQL database,
1161 then set some internal paths:</para>
1164 # as the postgres user:
1165 createdb evergreen -E UTF8 -T template0
1166 createlang plperl evergreen
1167 createlang plperlu evergreen
1168 createlang plpgsql evergreen</userinput>
1170 <para>Continue as the <systemitem class="username">postgres</systemitem>
1171 user and execute the SQL scripts as shown below (remember to adjust the
1172 paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1173 your installed PostgreSQL version, for example
1174 <literal>"8.4"</literal>).</para>
1177 # as the postgres user:
1178 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1179 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
1180 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
1183 <step xml:id="serversideinstallation-postgresqlcreateuser">
1184 <title>Create <systemitem class="username">evergreen</systemitem>
1185 PostgreSQL user</title>
1186 <para>As the <systemitem class="username">postgres</systemitem>
1187 user on the PostgreSQL system, create a new PostgreSQL user
1188 named <systemitem class="username">evergreen</systemitem> and
1189 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1190 with an appropriate new password):</para>
1193 # as the postgres user:
1194 createuser -P -s evergreen</userinput>
1196 Enter password for new role: <userinput>NEWPASSWORD</userinput>
1197 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1201 <title>Create database schema</title>
1202 <para>In this step you will create the database schema and configure your
1203 system with the corresponding database authentication details for the
1204 <emphasis>evergreen</emphasis> database user that you just created in
1205 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
1206 <para>As the <systemitem class="username">root</systemitem> user, enter
1207 the following commands and replace <emphasis>HOSTNAME, PORT,
1208 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1213 cd /home/opensrf/Evergreen-ILS-2.0.7
1214 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1215 --service all --create-schema --create-offline \
1216 --hostname HOSTNAME --port PORT \
1217 --user evergreen --password PASSWORD \
1218 --database DATABASENAME --admin-user ADMIN-USER \
1219 --admin-pass ADMIN-PASSWORD </userinput>
1221 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1222 <emphasis role="bold">localhost</emphasis> and
1223 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1224 Of course, values for <emphasis>PASSWORD</emphasis> and
1225 <emphasis>DATABASENAME</emphasis> must match the values you used in
1226 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
1227 The <option>admin-user</option> and <option>admin-pass</option> options will
1228 specify the Evergreen administrator account's username and password. This was
1229 changed for security reasons, it was previously admin/open-ils</para>
1230 <para>As the command executes, you may see warnings similar to:
1231 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1232 you may see one warning per schema) but they can be safely ignored.</para>
1233 <note>If you are entering the above command on a single line, do not
1234 include the <literal>\</literal> (backslash) characters. If you are using
1235 the <command>bash</command> shell, these should only be used at the end of
1236 a line at a <command>bash</command> prompt to indicate that the command is
1237 continued on the next line.</note>
1242 <title>Configure the Apache web server</title>
1244 <primary>web server</primary>
1245 <secondary>Apache</secondary>
1247 <para>In this step you will configure the Apache web server to support Evergreen
1249 <para>First, you must enable some built-in Apache modules and install some
1250 additional Apache configuration files. Then you will create a new Security
1251 Certificate. Finally, you must make several changes to the Apache configuration
1255 <title>Enable the required Apache Modules</title>
1256 <para>As the <systemitem class="username">root</systemitem>
1257 user, enable some modules in the Apache server, then copy the
1258 new configuration files to the Apache server directories:</para>
1260 <primary>Apache modules</primary>
1265 a2enmod ssl # enable mod_ssl
1266 a2enmod rewrite # enable mod_rewrite
1267 a2enmod expires # enable mod_expires</userinput>
1269 <para>As the commands execute, you may see warnings similar to:
1270 <literal>Module SOMEMODULE already enabled</literal> but you can
1271 safely ignore them.</para>
1274 <title>Copy Apache configuration files</title>
1275 <para>You must copy the Apache configuration files from the
1276 Evergreen installation directory to the Apache directory. As the
1277 <systemitem class="username">root</systemitem> user, perform the
1278 following commands:</para>
1282 cd /home/opensrf/Evergreen-ILS-2.0.7
1283 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/
1284 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
1285 cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
1288 <step xml:id="serversideinstallation-createsslcertificate">
1289 <title>Create a Security Certificate</title>
1290 <para>In this step you will create a new Security Certificate (SSL Key)
1291 for the Apache server using the <command>openssl</command> command. For a
1292 public production server you must configure or purchase a signed SSL
1293 certificate, but for now you can just use a self-signed certificate and
1294 accept the warnings in the Staff Client and browser during testing and
1295 development. As the <systemitem class="username">root</systemitem> user,
1296 perform the following commands:</para>
1300 mkdir /etc/apache2/ssl
1302 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1304 <para>You will be prompted for several items of information; enter
1305 the appropriate information for each item. The new files
1306 <filename>server.crt</filename> and <filename>server.key</filename> will
1307 be created in the directory
1308 <filename class="directory">/etc/apache2/ssl</filename> .</para>
1309 <note>This step generates a self-signed SSL certificate. You must install
1310 a proper SSL certificate for a public production system to avoid warning
1311 messages when users login to their account through the OPAC or when staff
1312 login through the Staff Client. For further information on
1313 installing a proper SSL certificate, see
1314 <xref linkend="serversideinstallation-ssl"/>.</note>
1316 <step xml:id="serversideinstallation-modify-apache">
1317 <title>Update Apache configuration files</title>
1318 <para>You must make several changes to an Apache configuration file.</para>
1319 <para>As the <systemitem class="username">root</systemitem> user
1320 edit the file <filename>/etc/apache2/sites-available/eg.conf</filename>
1321 and make the following changes:</para>
1324 <para>In the section
1325 <literal><Directory "/openils/var/cgi-bin"></literal>
1326 replace the line:</para>
1327 <literal>Allow from 10.0.0.0/8</literal>
1328 <para>with the line:</para>
1329 <literal>Allow from all</literal>
1330 <warning>This change allows access to your configuration
1331 CGI scripts from any workstation on any network. This is
1332 only a temporary change to expedite testing and should be
1333 removed after you have finished and successfully tested
1334 the Evergreen installation. See
1335 <xref linkend="serversideinstallation-postinstallation"/>
1336 for further details on removing this change after the
1337 Evergreen installation is complete.
1341 <para>Comment out the line:</para>
1342 <literal>Listen 443</literal>
1343 <para>since it conflicts with the same declaration in
1344 the configuration file:</para>
1345 <para><filename>/etc/apache2/ports.conf</filename>.</para>
1348 <para>The following updates are needed to allow the logs
1349 to function properly, but it may break other Apache
1350 applications on your server:</para>
1351 <para>As the <systemitem class="username">root</systemitem> user, edit the Apache configuration file <filename>/etc/apache2/envvars</filename> and
1352 change the lines:</para>
1355 export APACHE_RUN_USER=www-data
1356 export APACHE_RUN_GROUP=www-data</userinput>
1358 <para>to instead read:</para>
1361 export APACHE_RUN_USER=opensrf
1362 export APACHE_RUN_GROUP=opensrf</userinput>
1367 <systemitem class="username">root</systemitem> user,
1368 edit the Apache configuration file
1369 <filename>/etc/apache2/apache2.conf</filename> and
1370 modify the value for <literal>KeepAliveTimeout</literal>
1371 and <literal>MaxKeepAliveRequests</literal> to match
1372 the following:</para>
1376 MaxKeepAliveRequests 100</userinput>
1380 <para>Further configuration changes to Apache may be
1381 necessary for busy systems. These changes increase the
1382 number of Apache server processes that are started to
1383 support additional browser connections.</para>
1385 <systemitem class="username">root</systemitem> user,
1386 edit the Apache configuration file
1387 <filename>/etc/apache2/apache2.conf</filename>, locate
1388 and modify the section related to <emphasis>prefork
1389 configuration</emphasis> to suit the load on your
1391 <programlisting language="xml"><![CDATA[
1392 <IfModule mpm_prefork_module>
1397 MaxRequestsPerChild 10000
1399 ]]></programlisting>
1404 <title>Enable the Evergreen web site</title>
1405 <para>Finally, you must enable the Evergreen web site. As the
1406 <systemitem class="username">root</systemitem> user, execute the
1407 following Apache configuration commands to disable the default
1408 <emphasis>It Works</emphasis> web page and enable the Evergreen
1409 web site, and then restart the Apache server:</para>
1413 # disable/enable web sites
1416 # restart the server
1417 /etc/init.d/apache2 reload</userinput>
1422 <step xml:id="serversideinstallation-opensrf-config">
1423 <title>Update the OpenSRF Configuration File</title>
1424 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1425 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1426 to update the Jabber usernames and passwords, and to specify the domain from
1427 which we will accept and to which we will make connections.</para>
1428 <para>If you are installing Evergreen on a single server and using the
1429 <systemitem class="domainname">private.localhost</systemitem> /
1430 <systemitem class="domainname">public.localhost</systemitem> domains,
1431 these will already be set to the correct values. Otherwise, search and replace
1432 to match your customized values.</para>
1433 <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
1434 shows common XPath syntax to indicate the approximate position within the XML
1435 file that needs changes. The right-hand side of the table shows the replacement
1437 <table xml:id="serversideinstallation-xpath-table-2">
1438 <?dbfo keep-together="always" ?>
1439 <title>Sample XPath syntax for editing 'opensrf_core.xml'</title>
1440 <tgroup align="left" cols="2" colsep="1" rowsep="1">
1441 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
1442 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
1445 <entry>XPath location</entry>
1446 <entry>Value</entry>
1451 <entry>/config/opensrf/username</entry>
1453 <systemitem class="username">opensrf</systemitem>
1457 <entry>/config/opensrf/passwd </entry>
1458 <entry><systemitem class="domainname">private.localhost</systemitem>
1460 <systemitem class="username">opensrf</systemitem> user
1464 <entry>/config/gateway/username</entry>
1466 <systemitem class="username">opensrf</systemitem>
1470 <entry>/config/gateway/passwd</entry>
1471 <entry><systemitem class="domainname">public.localhost</systemitem>
1473 <systemitem class="username">opensrf</systemitem> user
1477 <entry>/config/routers/router/transport/username,
1478 first entry where server == public.localhost</entry>
1480 <systemitem class="username">router</systemitem>
1484 <entry>/config/routers/router/transport/password,
1485 first entry where server == public.localhost</entry>
1486 <entry><systemitem class="domainname">public.localhost</systemitem>
1488 <systemitem class="username">router</systemitem> user
1492 <entry>/config/routers/router/transport/username,
1493 second entry where server == private.localhost</entry>
1495 <systemitem class="username">router</systemitem>
1499 <entry>/config/routers/router/transport/password,
1500 second entry where server == private.localhost</entry>
1501 <entry><systemitem class="domainname">private.localhost</systemitem>
1503 <systemitem class="username">router</systemitem> user
1510 <step performance="optional">
1511 <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
1512 <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
1513 software installation automatically created a utility named <command>srfsh</command> (surf
1514 shell). This is a command line diagnostic tool for testing and interacting with
1515 OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
1516 Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration
1517 file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
1518 See <xref linkend="serversideinstallation-testing"/> for further information.</para>
1520 <step xml:id="serversideinstallation-opensrf-env">
1521 <title>Modify the OpenSRF Environment</title>
1522 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
1525 <para>As the <systemitem class="username">opensrf</systemitem> user,
1526 modify the shell configuration file <filename>~/.bashrc</filename> for
1527 user <systemitem class="username">opensrf</systemitem> by adding a Perl
1528 environmental variable, then execute the shell configuration file to load
1529 the new variables into your current environment.</para>
1532 # as the opensrf user:
1533 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
1534 . ~/.bashrc</userinput>
1536 <note>In a multi-server environment, you must add any
1537 modifications to <filename>~/.bashrc</filename> to the top of the file
1538 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
1539 return </literal>. This will allow headless (scripted) logins to load the
1540 correct environment.</note>
1544 <step performance="optional">
1545 <title>(OPTIONAL) Enable and Disable Language Localizations</title>
1546 <para>You can load translations such as Armenian (hy-AM), Canadian French
1547 (fr-CA), and others into the database to complete the translations available in
1548 the OPAC and Staff Client. For further information, see
1549 <xref linkend="languagesandlocalization"/>.</para>
1553 <section xml:id="serversideinstallation-fedora">
1554 <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
1555 <systemitem class="osname">Fedora 14</systemitem></title>
1557 <primary>Linux</primary>
1558 <secondary>Fedora</secondary>
1560 <para>This section outlines the installation process for the latest stable version of
1561 Evergreen on a <systemitem class="osname">Fedora 14</systemitem> system.
1562 See <xref linkend="serversideinstallation-ubuntudebian"/> for description of a
1563 similar installation on <systemitem class="osname">Ubuntu</systemitem> or
1564 <systemitem class="osname">Debian</systemitem> systems.</para>
1565 <para>In the following section you will download, unpack, install, configure and test the Evergreen
1566 system, including the Evergreen server and the PostgreSQL database system. You will make several
1567 configuration changes and adjustments to the software, including updates to configure the system
1568 for your own locale, and some updates needed to work around a few known issues.</para>
1570 <para>The following steps have been tested on the x86 (32-bit) and x86_64
1571 (64-bit) architecture of a <systemitem class="osname">Fedora 14</systemitem>
1572 image as of 2011-01-27.</para>
1573 <para>In the following instructions, you are asked to perform certain steps as
1574 either the <systemitem class="username">root</systemitem> user, the
1575 <systemitem class="username">opensrf</systemitem> user, or the
1576 <systemitem class="username">postgres</systemitem> user.</para>
1579 <para><systemitem class="osname">Fedora</systemitem> -- To become the
1580 <systemitem class="username">root</systemitem> user, issue the command
1581 <command>su -</command> and enter the password of the
1582 <systemitem class="username">root</systemitem> user.</para>
1585 <para>To switch from the <systemitem class="username">root</systemitem> user to a
1586 different user, issue the command <command>su - USERNAME</command>. For example, to
1587 switch from the <systemitem class="username">root</systemitem> user to the
1588 <systemitem class="username">opensrf</systemitem> user, issue the command
1589 <command>su - opensrf</command>. Once you have become a non-root user, to become the
1590 <systemitem class="username">root</systemitem> user again, simply issue the command
1591 <command>exit</command>.</para>
1594 <step xml:id="serversideinstallation-opensrf-2.0">
1595 <title>Install OpenSRF</title>
1596 <para>Evergreen software is integrated with and depends on the Open Service
1597 Request Framework (OpenSRF) software system. For further information on
1598 installing, configuring and testing OpenSRF, see
1599 <xref linkend="serversideinstallation-opensrf-2.0.0"/>.</para>
1600 <para>Follow the steps outlined in that section and run the specified tests to
1601 ensure that OpenSRF is properly installed and configured. Do
1602 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
1603 any further Evergreen installation steps until you have verified that OpenSRF
1604 has been successfully installed and tested.</para>
1607 <title>Download and Unpack Latest Evergreen Version</title>
1608 <para>The latest version of Evergreen can be found here:
1609 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz"></ulink> .
1610 As the <systemitem class="username">opensrf</systemitem> user, change to
1611 the directory <filename class="directory">/home/opensrf</filename> then
1612 download and extract Evergreen. The new subdirectory
1613 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.7</filename>
1614 will be created:</para>
1617 # as the opensrf user:
1619 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.7.tar.gz
1620 tar zxf Evergreen-ILS-2.0.7.tar.gz</userinput>
1623 <step xml:id="serversideinstallation-installprereq-2.0">
1624 <title>Install Prerequisites to Build Evergreen</title>
1625 <para>In this section you will install and configure a set of prerequisites that will be
1626 used later in <xref linkend="serversideinstallation-configure-2.0"/> and
1627 <xref linkend="serversideinstallation-compile-2.0"/> to build the Evergreen software
1628 using the <command>make</command> utility.</para>
1629 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
1630 below to build the prerequisites from the software distribution that you just downloaded
1631 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
1632 example with the keyword corresponding to the name of one of the
1633 <systemitem class="osname">Linux</systemitem> distributions listed in the following
1634 distribution list. For example, to install the prerequisites for
1635 <systemitem class="osname">Fedora 13</systemitem> or
1636 <systemitem class="osname">Fedora 14</systemitem>, you would enter the command:
1637 <command>make -f Open-ILS/src/extras/Makefile.install fedora13</command>.</para>
1641 cd /home/opensrf/Evergreen-ILS-2.0.7
1642 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
1645 <step performance="optional">
1646 <title>(OPTIONAL) Install the PostgreSQL Server</title>
1648 <primary>databases</primary>
1649 <secondary>PostgreSQL</secondary>
1651 <para>Since the PostgreSQL server is usually a standalone server in multi-server
1652 production systems, the prerequisite installer Makefile in the previous section
1653 (see <xref linkend="serversideinstallation-installprereq-2.0"/>)
1654 does not automatically install PostgreSQL. You must install the PostgreSQL server
1655 yourself, either on the same system as Evergreen itself or on another system.
1656 If your PostgreSQL server is on a different system, just skip this step.
1657 If your PostgreSQL server will be on the same system as your Evergreen
1658 software, you can install the required PostgreSQL server packages as described
1659 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
1660 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
1661 for more information.</para>
1663 <para>PostgreSQL version 8.4 is the minimum supported version to work
1664 with Evergreen 2.0. If you have an older version of PostgreSQL,
1665 you should upgrade before installing Evergreen. To find your current version
1666 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
1667 user execute the command <command>psql</command>, then type
1668 <userinput>SELECT version();</userinput> to get detailed information
1669 about your version of PostgreSQL.</para>
1672 <step performance="optional">
1673 <title>Install Perl Modules on PostgreSQL Server</title>
1674 <para>If PostgreSQL is running on the same system as your Evergreen software,
1675 then the Perl modules will automatically be available. Just skip this step.
1676 Otherwise, continue if your PostgreSQL server is running on another system,
1677 and install several Perl modules there. As the
1678 <systemitem class="username">root</systemitem> user, ensure the gcc compiler
1679 is installed, then install the following Perl modules:</para>
1683 perl -MCPAN -e shell
1684 <prompt>cpan></prompt> install JSON::XS
1685 <prompt>cpan></prompt> install MARC::Record
1686 <prompt>cpan></prompt> install MARC::File::XML</userinput>
1688 <para>For more information on installing Perl Modules vist the official
1689 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
1691 <primary>Perl</primary>
1692 <secondary>CPAN</secondary>
1695 <step xml:id="serversideinstallation-configure-2.0">
1696 <title>Configure Evergreen</title>
1697 <para>In this step you will use the <command>configure</command> and
1698 <command>make</command> utilities to configure Evergreen so it can be compiled
1699 and linked later in <xref linkend="serversideinstallation-compile-2.0"/>.</para>
1700 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
1701 the Evergreen build directory and execute these commands:</para>
1704 # as the opensrf user:
1705 cd /home/opensrf/Evergreen-ILS-2.0.7
1706 ./configure --prefix=/openils --sysconfdir=/openils/conf
1710 <step xml:id="serversideinstallation-compile-2.0">
1711 <title>Compile, Link and Install Evergreen</title>
1712 <para>In this step you will actually compile, link and install Evergreen and the
1713 default Evergreen Staff Client.</para>
1714 <para>As the <systemitem class="username">root</systemitem> user, return to the
1715 Evergreen build directory and use the <command>make</command> utility as shown
1720 cd /home/opensrf/Evergreen-ILS-2.0.7
1721 make STAFF_CLIENT_BUILD_ID=rel_2_0_7 install</userinput>
1723 <para>The Staff Client will also be automatically built, but you must remember
1724 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
1725 Staff Client you will use to connect to the Evergreen server.</para>
1726 <para>The above commands will create a new subdirectory
1727 <filename class="directory">/openils/var/web/xul/rel_2_0_7</filename>
1728 containing the Staff Client.</para>
1729 <para>To complete the Staff Client installation, as the
1730 <systemitem class="username">root</systemitem> user execute the following commands
1731 to create a symbolic link named <emphasis>server</emphasis> in the head of the
1732 Staff Client directory <filename class="directory">/openils/var/web/xul</filename>
1733 that points to the subdirectory <filename class="directory">/server</filename>
1734 of the new Staff Client build:</para>
1738 cd /openils/var/web/xul
1739 ln -sf rel_2_0_7/server server</userinput>
1743 <title>Copy the OpenSRF Configuration Files</title>
1744 <para>In this step you will replace some OpenSRF configuration files that you set up
1745 earlier in <xref linkend="serversideinstallation-opensrf-2.0"/> when you installed
1746 and tested OpenSRF.</para>
1747 <para>You must copy several example OpenSRF configuration files into place after first
1748 creating backup copies for troubleshooting purposes, then change all the file ownerships
1749 to <systemitem class="username">opensrf</systemitem>.
1750 As the <systemitem class="username">root</systemitem> user, execute the following
1756 cp opensrf.xml opensrf.xml.BAK
1757 cp opensrf_core.xml opensrf_core.xml.BAK
1758 cp opensrf.xml.example opensrf.xml
1759 cp opensrf_core.xml.example opensrf_core.xml
1760 cp oils_web.xml.example oils_web.xml
1761 chown -R opensrf:opensrf /openils/</userinput>
1765 <title>Create and Configure PostgreSQL Database</title>
1767 <primary>databases</primary>
1768 <secondary>PostgreSQL</secondary>
1770 <para>In this step you will create the Evergreen database. In the
1771 commands below, remember to adjust the path of the
1772 <emphasis role="bold">contrib</emphasis> repository to match your
1773 PostgreSQL server layout. For example, if you built PostgreSQL from
1774 source the path would be
1775 <filename class="directory">/usr/local/share/contrib</filename>
1776 , and if you installed the PostgreSQL 8.4 server packages on
1777 <systemitem class="osname">Ubuntu</systemitem>, the path would be
1778 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
1781 <title>Start the PostgreSQL service</title>
1782 <para>As the <systemitem class="username">root</systemitem>
1783 user on the PostgreSQL system, initialize the PostgreSQL cluster
1784 and start the PostgreSQL service:</para>
1788 service initdb postgresql
1789 /etc/init.d/postgresql start</userinput>
1793 <title>Create and configure the database</title>
1794 <para>As the <systemitem class="username">postgres</systemitem>
1795 user on the PostgreSQL system create the PostgreSQL database,
1796 then set some internal paths:</para>
1799 # as the postgres user:
1800 createdb evergreen -E UTF8 -T template0
1801 createlang plperl evergreen
1802 createlang plperlu evergreen
1803 createlang plpgsql evergreen</userinput>
1805 <para>Continue as the <systemitem class="username">postgres</systemitem>
1806 user and execute the SQL scripts as shown below (remember to adjust the
1807 paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
1808 your installed PostgreSQL version, for example
1809 <literal>"8.4"</literal>).</para>
1812 # as the postgres user:
1813 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
1814 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
1815 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
1818 <step xml:id="serversideinstallation-postgresqlcreateuser-2.0">
1819 <title>Create <systemitem class="username">evergreen</systemitem>
1820 PostgreSQL user</title>
1821 <para>As the <systemitem class="username">postgres</systemitem>
1822 user on the PostgreSQL system, create a new PostgreSQL user
1823 named <systemitem class="username">evergreen</systemitem> and
1824 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
1825 with an appropriate new password):</para>
1828 # as the postgres user:
1829 createuser -P -s evergreen</userinput>
1831 Enter password for new role: <userinput>NEWPASSWORD</userinput>
1832 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
1836 <title>Enable IPv4 and IPv6 connections</title>
1837 <para>As the root user, enable IPv4 and IPv6 connections to the
1838 PostgreSQL server. For a single-server instance, enable
1839 password-protected connections from the Evergreen user to the
1840 Evergreen database on localhost by adding the following lines to
1841 <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
1846 # IPv4 local connections:
1847 host evergreen evergreen 127.0.0.1/32 md5
1848 # IPv6 local connections:
1849 host evergreen evergreen ::1/128 md5</userinput>
1851 <para>Then, as the root user, restart the PostgreSQL server to
1852 make that configuration take effect:</para>
1856 /etc/init.d/postgresql restart</userinput>
1860 <title>Create database schema</title>
1861 <para>In this step you will create the database schema and configure your
1862 system with the corresponding database authentication details for the
1863 <emphasis>evergreen</emphasis> database user that you just created in
1864 <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.</para>
1865 <para>As the <systemitem class="username">root</systemitem> user, enter
1866 the following commands and replace <emphasis>HOSTNAME, PORT,
1867 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
1872 cd /home/opensrf/Evergreen-ILS-2.0.7
1873 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
1874 --service all --create-schema --create-offline \
1875 --hostname HOSTNAME --port PORT \
1876 --user evergreen --password PASSWORD \
1877 --database DATABASENAME --admin-user ADMIN-USER \
1878 --admin-pass ADMIN-PASSWORD </userinput>
1880 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
1881 <emphasis role="bold">localhost</emphasis> and
1882 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
1883 Of course, values for <emphasis>PASSWORD</emphasis> and
1884 <emphasis>DATABASENAME</emphasis> must match the values you used in
1885 <xref linkend="serversideinstallation-postgresqlcreateuser-2.0"/>.
1886 The <option>admin-user</option> and <option>admin-pass</option> options will
1887 specify the Evergreen administrator account's username and password. This was
1888 changed for security reasons, it was previously admin/open-ils</para>
1889 <para>As the command executes, you may see warnings similar to:
1890 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
1891 you may see one warning per schema) but they can be safely ignored.</para>
1892 <note>If you are entering the above command on a single line, do not
1893 include the <literal>\</literal> (backslash) characters. If you are using
1894 the <command>bash</command> shell, these should only be used at the end of
1895 a line at a <command>bash</command> prompt to indicate that the command is
1896 continued on the next line.</note>
1901 <title>Configure the Apache web server</title>
1903 <primary>web server</primary>
1904 <secondary>Apache</secondary>
1906 <para>In this step you will configure the Apache web server to support Evergreen
1908 <para>First, you must install some additional Apache configuration files. Then you will
1909 create a new Security Certificate. Finally, you must make several changes to Apache
1910 configuration files.</para>
1913 <title>Copy Apache configuration files</title>
1914 <para>You must copy the Apache configuration files from the
1915 Evergreen installation directory to the Apache directory. As the
1916 <systemitem class="username">root</systemitem> user, perform the
1917 following commands:</para>
1921 cd /home/opensrf/Evergreen-ILS-2.0.7
1922 cp Open-ILS/examples/apache/eg.conf /etc/httpd/conf.d/
1923 cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
1924 cp Open-ILS/examples/apache/startup.pl /etc/httpd/</userinput>
1927 <step xml:id="serversideinstallation-createsslcertificate-2.0">
1928 <title>Create a Security Certificate</title>
1929 <para>In this step you will create a new Security Certificate (SSL Key)
1930 for the Apache server using the <command>openssl</command> command. For a
1931 public production server you must configure or purchase a signed SSL
1932 certificate, but for now you can just use a self-signed certificate and
1933 accept the warnings in the Staff Client and browser during testing and
1934 development. As the <systemitem class="username">root</systemitem> user,
1935 perform the following commands:</para>
1939 mkdir /etc/httpd/ssl
1941 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
1943 <para>You will be prompted for several items of information; enter
1944 the appropriate information for each item. The new files
1945 <filename>server.crt</filename> and <filename>server.key</filename> will
1946 be created in the directory
1947 <filename class="directory">/etc/httpd/ssl</filename> .</para>
1948 <note>This step generates a self-signed SSL certificate. You must install
1949 a proper SSL certificate for a public production system to avoid warning
1950 messages when users login to their account through the OPAC or when staff
1951 login through the Staff Client. For further information on
1952 installing a proper SSL certificate, see
1953 <xref linkend="serversideinstallation-ssl"/>.</note>
1955 <step xml:id="serversideinstallation-modify-apache-2.0">
1956 <title>Update Apache configuration files</title>
1957 <para>You must make several changes to two Apache configuration files.</para>
1958 <para>As the <systemitem class="username">root</systemitem>
1959 user, edit the file <filename>/etc/httpd/conf.d/eg.conf</filename>
1960 and make the following changes:</para>
1963 <para>Change all instances of <literal>apache2</literal>
1964 to <literal>httpd</literal> .</para>
1967 <para>In the section
1968 <literal><Directory "/openils/var/cgi-bin"></literal>
1969 replace the line:</para>
1970 <literal>Allow from 10.0.0.0/8</literal>
1971 <para>with the line:</para>
1972 <literal>Allow from all</literal>
1973 <warning>This change allows access to your configuration
1974 CGI scripts from any workstation on any network. This is
1975 only a temporary change to expedite testing and should be
1976 removed after you have finished and successfully tested
1977 the Evergreen installation. See
1978 <xref linkend="serversideinstallation-postinstallation"/>
1979 for further details on removing this change after the
1980 Evergreen installation is complete.
1984 <para>Comment out the line:</para>
1985 <literal>Listen 443</literal>
1986 <para>since it conflicts with the same declaration in
1987 the configuration file:</para>
1988 <para><filename>/etc/httpd/conf.d/ssl.conf</filename>.</para>
1992 As the <systemitem class="username">root</systemitem> user, edit the
1993 Apache configuration file <filename>/etc/httpd/conf.d/httpd.conf</filename>
1994 and make the following changes:</para>
1997 Change <literal>User apache</literal> to
1998 <literal>User opensrf</literal></listitem>
2000 Change <literal>KeepAlive</literal> to
2001 <literal>On</literal></listitem>
2003 Change <literal>KeepAliveTimeout</literal> to
2004 <literal>1</literal></listitem>
2010 <title>Update the System Dynamic Library Path</title>
2011 <para>You must update the system dynamic library path to force your
2012 system to recognize the library <literal>dbdpgsql.so</literal>. As the
2013 <systemitem class="username">root</systemitem> user, do this by creating
2014 the new file <filename>/etc/ld.so.conf.d/eg.conf</filename> containing two
2015 new library paths, then run the command <command>ldconfig</command> to
2016 automatically read the file and modify the system dynamic library
2021 echo "/usr/lib/dbd" > /etc/ld.so.conf.d/eg.conf
2022 echo "/usr/lib64/dbd/" >> /etc/ld.so.conf.d/eg.conf
2023 ldconfig</userinput>
2026 <step xml:id="serversideinstallation-opensrf-config-2.0">
2027 <title>Update the OpenSRF Configuration File</title>
2028 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
2029 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
2030 and update the Jabber usernames and passwords, and specify the domain from
2031 which we will accept and to which we will make connections.</para>
2032 <para>If you are installing Evergreen on a single server and using the
2033 <systemitem class="domainname">private.localhost</systemitem> /
2034 <systemitem class="domainname">public.localhost</systemitem> domains,
2035 these will already be set to the correct values. Otherwise, search and replace
2036 to match your customized values.</para>
2037 <para>See the table <xref linkend="serversideinstallation-xpath-table-2"/>
2038 for examples of the XPath syntax you will find in this XML file. The syntax
2039 indicates the approximate position within the file that needs changes.</para>
2041 <step xml:id="serversideinstallation-opensrf-env-2.0">
2042 <title>Modify the OpenSRF Environment</title>
2043 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
2046 <para>As the <systemitem class="username">opensrf</systemitem> user,
2047 modify the shell configuration file <filename>~/.bashrc</filename> for
2048 user <systemitem class="username">opensrf</systemitem> by adding a Perl
2049 environmental variable, then execute the shell configuration file to load
2050 the new variables into your current environment:</para>
2053 # as the opensrf user:
2054 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
2055 . ~/.bashrc</userinput>
2057 <note>In a multi-server environment, you must add any
2058 modifications to <filename>~/.bashrc</filename> to the top of the file
2059 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
2060 return </literal>. This will allow headless (scripted) logins to load the
2061 correct environment.</note>
2066 <title>Configuring Fedora Security</title>
2067 <para><systemitem class="osname">Fedora</systemitem> is a very secure
2068 system out of the box, including a very restrictive firewall and an
2069 automatically enabled set of SELinux system policies to prevent
2070 unauthorized access to system resources. Unfortunately, these secure
2071 system policies can interfere with the normal operation of
2072 applications like Evergreen.</para>
2073 <para>Until a person with the required SELinux skills can offer a
2074 nuanced set of policies appropriate for Evergreen, the simplest way to
2075 test and develop against a <systemitem class="osname">Fedora</systemitem>
2076 server is to completely disable the firewall and SELinux policies.</para>
2079 <title>Disabling the Fedora firewall</title>
2080 <para>To disable the <systemitem class="osname">Fedora</systemitem>
2081 firewall until your next reboot, issue the
2082 following command as the root user:</para>
2086 /etc/init.d/iptables stop</userinput>
2088 <para>To disable the <systemitem class="osname">Fedora</systemitem>
2089 firewall permanently, issue the following
2090 command as the root user:</para>
2094 chkconfig iptables off</userinput>
2096 <para>This change will take effect when you reboot your system.</para>
2099 <title>Disabling the SELinux policies</title>
2100 <para>To disable the SELinux policies until your next reboot, issue
2101 the following command as the root user:</para>
2105 /usr/sbin/setenforce 0</userinput>
2107 <para>To disable the SELinux policies permanently, as the root user
2108 edit the file <filename>/etc/sysconfig/selinux</filename> and make the
2109 following change:</para>
2113 SELINUX=permissive</userinput>
2115 <para>This change will take effect when you reboot your system.</para>
2121 <section xml:id="serversideinstallation-starting">
2122 <title>Starting Evergreen</title>
2123 <para>In this section you will learn how to start the Evergreen services.
2124 For completeness, instructions for stopping Evergreen can be found later in
2125 <xref linkend="serversideinstallation-stopping"/>.</para>
2128 <para>As the <systemitem class="username">root</systemitem> user,
2129 start the <systemitem class="service">ejabberd</systemitem>,
2130 <systemitem class="service">memcached</systemitem>, and
2131 <systemitem class="service">PostgreSQL</systemitem> services
2132 (if they aren't already running) as follows:</para>
2136 /etc/init.d/ejabberd start
2137 /etc/init.d/memcached start
2138 /etc/init.d/postgresql start</userinput>
2142 <para>If you want to have these services run automatically every time
2143 you boot your server, issue the following commands as the root
2148 chkconfig --levels 2345 ejabberd on
2149 chkconfig --levels 2345 memcached on
2150 chkconfig --levels 2345 postgresql on</userinput>
2154 <para>As the <systemitem class="username">opensrf</systemitem> user,
2155 start the OpenSRF <systemitem class="service">router</systemitem> ,
2156 <systemitem class="service">Perl</systemitem>, and <systemitem class="service">C</systemitem> services. The <option>-l</option> flag in
2157 the following command is only necessary if you want to force Evergreen to
2158 treat the hostname as <literal>'localhost'</literal>. You should not
2159 use the '-l' flag if you configured <filename>opensrf.xml</filename>
2160 using the real hostname of your machine as returned by: <literal>perl
2161 -ENet::Domain 'print Net::Domain::hostfqdn() . “\n”;'</literal> .
2162 As the opensrf user, execute this command:</para>
2165 # as the opensrf user:
2166 osrf_ctl.sh -l -a start_all</userinput>
2170 <para>If you receive an error message similar to
2171 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
2172 environment variable <envar>PATH</envar> does not include the
2173 directory <filename class="directory">/openils/bin</filename>.
2174 As the <systemitem class="username">opensrf</systemitem> user,
2175 edit the configuration file <filename>~/.bashrc</filename> and
2176 add the following line:
2177 <literal>export PATH=$PATH:/openils/bin</literal></para>
2180 <para>If you receive an error message similar to <emphasis>Can't
2181 locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
2182 aborted</emphasis>, then your environment variable
2183 <emphasis role="bold">PERL5LIB</emphasis> does not include the
2184 directory <filename class="directory">/openils/lib/perl5</filename>.
2185 This should have been set by <filename>~/.bashrc</filename> when you
2186 logged in as the <systemitem class="username">opensrf</systemitem>
2187 user, but you can manually set it using the following command:
2188 <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
2193 <para>In this step you will generate the Web files needed by the Staff Client
2194 and catalog, as well as update the proximity of locations in the Organizational
2195 Unit tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
2196 <para>You must do this the first time you start Evergreen and after making any
2197 changes to the library hierarchy.</para>
2198 <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
2199 following command and review the results as shown in this example:</para>
2202 # as the opensrf user:
2204 ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
2206 Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
2207 Updating fieldmapper
2208 Updating web_fieldmapper
2210 removing OrgTree from the cache for locale hy-AM...
2211 removing OrgTree from the cache for locale cs-CZ...
2212 removing OrgTree from the cache for locale en-CA...
2213 removing OrgTree from the cache for locale en-US...
2214 removing OrgTree from the cache for locale fr-CA...
2215 removing OrgTree from the cache for locale ru-RU...
2216 Updating OrgTree HTML
2217 Updating locales selection HTML
2218 Updating Search Groups
2219 Refreshing proximity of org units
2220 Successfully updated the organization proximity
2221 Done</computeroutput>
2225 <para>As the <systemitem class="username">root</systemitem> user, restart the
2226 Apache Web server:</para>
2230 /etc/init.d/httpd restart</userinput>
2232 <note>If the Apache Web server was running when you started the OpenSRF
2233 services, you might not be able to successfully log into the OPAC or Staff
2234 Client until the Apache Web server has been restarted.</note>
2238 <section xml:id="serversideinstallation-testing">
2239 <title>Testing Your Evergreen Installation</title>
2240 <para>This section describes several simple tests you can perform to verify that the Evergreen
2241 server-side software has been installed and configured properly and is running as
2243 <simplesect xml:id="serversideinstallation-testing-connections">
2244 <title>Testing Connections to Evergreen</title>
2245 <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
2246 <command>srfsh</command> application and try logging onto the Evergreen server using the default
2247 administrator username and password. Following is sample output generated by executing
2248 <command>srfsh</command> after a successful Evergreen installation. For help with
2249 <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
2250 As the <systemitem class="username">opensrf</systemitem> user,
2251 execute the following command and review the results as shown in this example to test
2252 your Evergreen connection:</para>
2255 # as the opensrf user:
2256 /openils/bin/srfsh</userinput>
2258 srfsh% <userinput>login admin open-ils</userinput>
2259 Received Data: "250bf1518c7527a03249858687714376"
2260 ------------------------------------
2261 Request Completed Successfully
2262 Request Time in seconds: 0.045286
2263 ------------------------------------
2266 "textcode":"SUCCESS",
2269 "stacktrace":"oils_auth.c:304",
2271 "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
2275 ------------------------------------
2276 Request Completed Successfully
2277 Request Time in seconds: 1.336568
2278 ------------------------------------</computeroutput>
2280 <para>If this does not work, try the following:</para>
2283 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
2284 utility <filename>settings-tester.pl</filename> to review your Evergreen
2285 installation for any system configuration problems:</para>
2288 # as the opensrf user:
2290 ./Evergreen-ILS-2.0.7/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
2292 <para>If the output of <command>settings-tester.pl</command> does not help
2293 you find the problem, please do not make any significant changes to your
2294 configuration.</para>
2297 <para>Follow the steps in the troubleshooting guide in
2298 <xref linkend="troubleshooting"/>.</para>
2301 <para>If you have followed the entire set of installation steps listed here
2302 closely, you are probably extremely close to a working system. Gather your
2303 configuration files and log files and contact the
2304 <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
2305 for assistance before making any drastic changes to your system
2306 configuration.</para>
2310 <simplesect xml:id="serversideinstallation-running-staffclient">
2311 <title>Testing the Staff Client on Linux</title>
2312 <para>In this section you will confirm that a basic login on the Staff Client works
2314 <para>Run the Evergreen Staff Client on your <systemitem class="osname">Fedora</systemitem>
2315 system by using the application
2316 <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
2317 version 3.0 and later on Ubuntu and Debian distributions).</para>
2318 <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
2323 xulrunner /home/opensrf/Evergreen-ILS-2.0.7/Open-ILS/xul/staff_client/build/application.ini</userinput>
2325 <para>A login screen for the Staff Client similar to this should appear:</para>
2327 <alt>Logging into the Staff Client</alt>
2329 <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>
2332 <para>First, add the name of your Evergreen server to the field
2333 <literal>Hostname</literal> in the <literal>Server</literal> section. You will
2334 probably want to use <literal>127.0.0.1</literal>. After adding the server
2335 name, click <guibutton>Re-Test Server</guibutton>. You should now see the
2336 messages <literal>200:OK</literal> in the fields <literal>Status</literal> and
2337 <literal>Version</literal>.</para>
2338 <para>Because this is the initial run of the Staff Client, you will see a warning in the
2339 upper-right saying: <emphasis role="bold">Not yet configured for the specified
2340 server</emphasis>. To continue, you must assign a workstation name.</para>
2341 <para>Try to log into the Staff Client with the admin username and password you created
2342 during installation. If the login is successful, you will see the following
2345 <alt>Logging into the Staff Client</alt>
2347 <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>
2350 <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the
2351 main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>
2353 <alt>Adding an SSL Exception in the Staff Client</alt>
2355 <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>
2358 <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm
2359 Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the
2360 main window and try to log in again.</para>
2362 <simplesect xml:id="serversideinstallation-starting-apache-server">
2363 <title>Testing the Apache Web Server</title>
2364 <para>In this section you will test the Apache configuration file(s), then restart the
2365 Apache web server.</para>
2366 <para>As the <emphasis role="bold">root</emphasis> user, execute the following
2367 commands. The use of <emphasis>restart</emphasis> will force the new Evergreen
2368 modules to be reloaded even if the Apache server is already running.
2369 Any problems found with your configuration files should be displayed:</para>
2373 /etc/init.d/httpd configtest && /etc/init.d/httpd restart</userinput>
2376 <simplesect xml:id="serversideinstallation-stopping">
2377 <title>Stopping Evergreen</title>
2378 <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the
2379 Evergreen services. For completeness, following are instructions for stopping the
2380 Evergreen services.</para>
2381 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
2382 services by using the following command:</para>
2385 # as the opensrf user
2386 # stop the server; use "-l" to force hostname to be "localhost"
2387 osrf_ctl.sh -l -a stop_all</userinput>
2389 <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the
2390 <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the
2391 fully qualified domain name for the system on which it will execute. That hostname may
2392 have been specified in the configuration file <filename>opensrf.xml</filename>, which
2393 you configured in a previous step.</note>
2396 <section xml:id="serversideinstallation-postinstallation">
2397 <title>Post-Installation Chores</title>
2398 <para>There are several additional steps you may need to complete after Evergreen has been
2399 successfully installed and tested. Some steps may not be needed (e.g., setting up support for
2402 <title>Remove temporary Apache configuration changes</title>
2403 <para>You modified the Apache configuration file
2404 <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
2405 temporary measure to expedite testing (see
2406 <xref linkend="serversideinstallation-modify-apache"/> for further information).
2407 Those changes must now be reversed in order to deny unwanted access to your
2408 CGI scripts from users on other public networks.</para>
2411 <emphasis>This temporary network update was done to expedite
2412 testing. You <emphasis role="bold">must</emphasis> correct
2413 this for a public production system.</emphasis>
2416 <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
2417 file again and comment out the line <literal>Allow from all</literal> and uncomment the
2418 line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
2419 address scheme.</para>
2421 <section xml:id="serversideinstallation-ssl">
2422 <title>Configure a permanent SSL key</title>
2423 <para>You used the command <command>openssl</command> in an earlier step to
2424 temporarily create a new SSL key for the Apache server (see
2425 <xref linkend="serversideinstallation-createsslcertificate-2.0"/> for further
2426 information). This self-signed security certificate was adequate during
2427 testing and development, but will continue to generate warnings in the Staff
2428 Client and browser. For a public production server you should configure or
2429 purchase a signed SSL certificate.</para>
2430 <para>There are several open source software solutions that provide schemes to
2431 generate and maintain public key security certificates for your library
2432 system. Some popular projects are listed below; please review them for
2433 background information on why you need such a system and how you can provide
2437 <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
2440 <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
2443 <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
2448 <emphasis>The temporary SSL key was only created to expedite
2449 testing. You should install a proper SSL certificate for a public
2450 production system.</emphasis>
2455 <title>(OPTIONAL) IP-Redirection</title>
2456 <para>By default, Evergreen is configured so searching the OPAC always starts in the
2457 top-level (regional) library rather than in a second-level (branch) library. Instead,
2458 you can use "IP-Redirection" to change the default OPAC search location to use the IP
2459 address range assigned to the second-level library where the seach originates. You must
2460 configure these IP ranges by creating the configuration file
2461 <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
2462 <filename>/etc/apache2/startup.pl</filename>.</para>
2463 <para>First, copy the sample file
2464 <filename>/home/opensrf/Evergreen-ILS-2.0.0/Open-ILS/examples/lib_ips.txt.example</filename>
2465 to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
2466 line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
2467 the IP address ranges for your library system. Add new lines to represent the IP address
2468 range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
2469 values for each branch library found in the table
2470 <literal>actor.org_unit</literal>.</para>
2471 <para>Finally, modify the Apache startup script
2472 <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
2473 restarting the Apache server:</para>
2474 <programlisting language="xml"><![CDATA[
2475 # - Uncomment the following 2 lines to make use of the IP redirection code
2476 # - The IP file should contain a map with the following format:
2477 # - actor.org_unit.shortname <start_ip> <end_ip>
2478 # - e.g. LIB123 10.0.0.1 10.0.0.254
2479 use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
2480 OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
2481 ]]></programlisting>
2484 <title>(OPTIONAL) Set Up Support For Reports</title>
2485 <para>Evergreen reports are extremely powerful but require some simple configuration.
2486 See <xref linkend="report_starting_reporter_service"/> for information on starting and
2487 stopping the Reporter daemon processes.</para>
projects / working / Evergreen.git / blob