1 <?xml version="1.0" encoding="UTF-8"?>
\r
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">
\r
4 <title>Server-side Installation of Evergreen Software</title>
\r
6 <para>This section describes installation of the Evergreen server-side software and its associated components.
\r
7 Installation, configuration, testing and verification
\r
8 of the software is straightforward if you follow some simple directions.</para>
\r
11 <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
\r
12 stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
\r
13 installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
\r
15 <para>The current version of the Evergreen server-side software runs as a native application on any of several
\r
16 well-known <systemitem class="osname">Linux</systemitem> distributions
\r
17 (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
\r
18 It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
\r
19 operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
\r
20 Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
\r
21 installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
\r
22 <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
\r
23 <application>"VirtualBox"</application> or <application>"VMware"</application>
\r
24 to emulate a <systemitem class="osname">Linux</systemitem>
\r
25 environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
\r
26 systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
\r
27 <application>"VMware"</application>). More information on virtualized environments can be found in
\r
28 <xref linkend="serversideinstallation-virtual"/>.</para>
\r
29 <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
\r
30 <para>The Evergreen server-side software has dependencies on particular versions of certain major software
\r
31 sub-components. Successful installation of Evergreen software requires that software versions agree with those
\r
33 <table xml:id="serversideinstall-software-dependencies">
\r
34 <?dbfo keep-together="always" ?>
\r
35 <title>Evergreen Software Dependencies</title>
\r
37 <primary>Evergreen software dependencies</primary>
\r
39 <tgroup align="left" cols="3" colsep="1" rowsep="1">
\r
40 <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
\r
41 <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
\r
42 <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
\r
45 <entry>Evergreen</entry>
\r
46 <entry>OpenSRF</entry>
\r
47 <entry>PostgreSQL</entry>
\r
53 <entry>1.6.3</entry>
\r
57 <entry>1.6.1.x</entry>
\r
58 <entry>1.4.0</entry>
\r
59 <entry>8.2 / 8.3</entry>
\r
62 <entry>1.6.0.x</entry>
\r
64 <entry>8.2 / 8.3</entry>
\r
67 <entry>1.4.x</entry>
\r
69 <entry>8.1 / 8.2</entry>
\r
72 <entry>1.2.x</entry>
\r
74 <entry>8.1 / 8.2</entry>
\r
79 <section xml:id="serversideinstallation-all">
\r
80 <title>Installing Server-Side Software</title>
\r
81 <para>This section describes the installation of the major components of Evergreen server-side software.</para>
\r
82 <para>As far as possible, you should perform the following steps in the exact order given since the
\r
83 success of many steps relies on the successful completion of earlier steps. You should make backup
\r
84 copies of files and environments when you are instructed to do so. In the event of installation problems
\r
85 those copies can allow you to back out of a step gracefully and resume the installation from a known
\r
86 state. See <xref linkend="backingup"/> for further information.</para>
\r
87 <para>Of course, after you successfully complete and test the entire Evergreen installation you should
\r
88 take a final snapshot backup of your system(s). This can be the first in the series of regularly
\r
89 scheduled system backups that you should probably also begin.</para>
\r
90 <section xml:id="serversideinstallation-opensrf">
\r
92 <primary>OpenSRF</primary>
\r
93 <secondary>installation</secondary>
\r
95 <title>Installing OpenSRF 1.6.3 On <systemitem class="osname">Ubuntu</systemitem> or
\r
96 <systemitem class="osname">Debian</systemitem></title>
\r
98 <primary>Linux</primary>
\r
99 <secondary>Debian</secondary>
\r
102 <primary>Linux</primary>
\r
103 <secondary>Ubuntu</secondary>
\r
105 <para>This section describes the installation of the latest version of the Open Service Request
\r
106 Framework (OpenSRF), a major component of the Evergreen server-side software, on
\r
107 <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
\r
108 systems. Evergreen software is integrated with and depends on the OpenSRF software
\r
110 <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
\r
111 properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
\r
112 continue with any further Evergreen installation steps
\r
113 until you have verified that OpenSRF has been successfully installed and tested.</para>
\r
115 <para>The following steps have been tested on the x86 (32-bit) architecture of
\r
116 <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
\r
117 <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
\r
118 <systemitem class="osname">Fedora 13</systemitem> and
\r
119 <systemitem class="osname">Fedora 14</systemitem>.</para>
\r
120 <para>In the following instructions, you are asked to perform certain steps as
\r
121 either the <systemitem class="username">root</systemitem> user, the
\r
122 <systemitem class="username">opensrf</systemitem> user, or the
\r
123 <systemitem class="username">postgres</systemitem> user.</para>
\r
126 <para><systemitem class="osname">Debian</systemitem> -- To become the
\r
127 <systemitem class="username">root</systemitem> user, issue the command
\r
128 <command>su -</command> and enter the password of the
\r
129 <systemitem class="username">root</systemitem> user.</para>
\r
132 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
\r
133 <systemitem class="username">root</systemitem> user, issue the command
\r
134 <command>sudo su -</command> and enter the password of the
\r
135 <systemitem class="username">root</systemitem> user.</para>
\r
138 <para>To switch from the <systemitem class="username">root</systemitem> user to a
\r
139 different user, issue the command <command>su - USERNAME</command>. For example, to
\r
140 switch from the <systemitem class="username">root</systemitem> user to the
\r
141 <systemitem class="username">opensrf</systemitem> user, issue the command
\r
142 <command>su - opensrf</command>. Once you have become a non-root user, to become
\r
143 the <systemitem class="username">root</systemitem> user again, simply issue the command
\r
144 <command>exit</command>.</para>
\r
148 <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
\r
149 <para>As the <systemitem class="username">root</systemitem> user, add the
\r
150 <systemitem class="username">opensrf</systemitem> user to the system.
\r
151 In the following example, the default shell for the
\r
152 <systemitem class="username">opensrf</systemitem> user is automatically set
\r
153 to <command>/bin/bash</command> to inherit a reasonable environment:</para>
\r
156 # as the root user:
\r
157 useradd -m -s /bin/bash opensrf
\r
158 passwd opensrf</userinput>
\r
162 <title>Download and Unpack Latest OpenSRF Version</title>
\r
164 <primary>OpenSRF</primary>
\r
165 <secondary>download</secondary>
\r
167 <para>The latest version of OpenSRF can be found here:
\r
168 <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz"></ulink> .
\r
169 As the <systemitem class="username">opensrf</systemitem> user, change to
\r
170 the directory <filename class="directory">/home/opensrf</filename> then download
\r
171 and extract OpenSRF. The new subdirectory
\r
172 <filename class="directory">/home/opensrf/OpenSRF-1.6.3</filename> will be created:</para>
\r
175 # as the opensrf user:
\r
177 wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz
\r
178 tar zxf OpenSRF-1.6.3.tar.gz</userinput>
\r
182 <title>Install Prerequisites to Build OpenSRF</title>
\r
183 <para>In this section you will install and configure a set of prerequisites that will be
\r
184 used to build OpenSRF. In a following step you will actually build the OpenSRF software
\r
185 using the <command>make</command> utility.</para>
\r
186 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
\r
187 below to build the prerequisites from the software distribution that you just downloaded
\r
188 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
\r
189 example with the keyword corresponding to the name of one of the
\r
190 <systemitem class="osname">Linux</systemitem> distributions listed in the
\r
191 distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
\r
192 For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
\r
193 enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
\r
196 # as the root user:
\r
197 cd /home/opensrf/OpenSRF-1.6.3
\r
198 make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
\r
200 <table xml:id="serversideinstallation-keywords-opensrf">
\r
201 <?dbfo keep-together="always" ?>
\r
202 <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
\r
203 <tgroup align="left" cols="2" colsep="1" rowsep="1">
\r
204 <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
\r
205 <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
\r
208 <entry>Keyword</entry>
\r
209 <entry>Linux Version</entry>
\r
214 <entry>debian-squeeze</entry>
\r
215 <entry>Debian "Squeeze" (6.0)</entry>
\r
218 <entry>debian-etch</entry>
\r
219 <entry>Debian "Etch" (4.0)</entry>
\r
222 <entry>debian-lenny</entry>
\r
223 <entry>Debian "Lenny" (5.0)</entry>
\r
226 <entry>ubuntu-hardy</entry>
\r
227 <entry>Ubuntu "Hardy Heron" (8.04)</entry>
\r
230 <entry>ubuntu-karmic</entry>
\r
231 <entry>Ubuntu "Karmic Koala" (9.10)</entry>
\r
234 <entry>ubuntu-lucid</entry>
\r
235 <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
\r
238 <entry>fedora13</entry>
\r
239 <entry>Fedora "Goddard" (13)</entry>
\r
242 <entry>fedora13</entry>
\r
243 <entry>Fedora "Laughlin" (14)</entry>
\r
246 <entry>centos</entry>
\r
247 <entry>CentOS 5</entry>
\r
250 <entry>rhel</entry>
\r
251 <entry>Red Hat Enterprise Linux 5</entry>
\r
254 <entry>gentoo</entry>
\r
255 <entry>Gentoo</entry>
\r
260 <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>
\r
261 <indexterm><primary>Linux</primary><secondary>Fedora</secondary></indexterm>
\r
262 <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>
\r
263 <indexterm><primary>Linux</primary><secondary>CentOS</secondary></indexterm>
\r
264 <indexterm><primary>Linux</primary><secondary>Red Hat</secondary></indexterm>
\r
265 <indexterm><primary>Linux</primary><secondary>Gentoo</secondary></indexterm>
\r
266 <para>This will install a number of packages on the system that are required by OpenSRF,
\r
267 including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
\r
268 CPAN configuration prompt to allow it to automatically configure itself to download and
\r
269 install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
\r
270 it should install prerequisite modules - say <literal>Yes</literal>.</para>
\r
273 <title>Build OpenSRF</title>
\r
274 <para>In this section you will configure, build and install the OpenSRF
\r
275 components that support other Evergreen services.</para>
\r
278 <title>Configure OpenSRF</title>
\r
280 <primary>OpenSRF</primary>
\r
281 <secondary>configure</secondary>
\r
283 <para>As the <systemitem class="username">opensrf</systemitem>
\r
284 user, return to the new OpenSRF build directory and use the
\r
285 <command>configure</command> utility to prepare for the next
\r
286 step of compiling and linking the software. If you wish to
\r
287 include support for Python and Java, add the configuration
\r
288 options <option>--enable-python</option> and
\r
289 <option>--enable-java</option>, respectively:</para>
\r
292 # as the opensrf user:
\r
293 cd /home/opensrf/OpenSRF-1.6.3
\r
294 ./configure --prefix=/openils --sysconfdir=/openils/conf
\r
297 <para>This step will take several minutes to complete.</para>
\r
300 <title>Compile, Link and Install OpenSRF</title>
\r
301 <para>As the <systemitem class="username">root</systemitem>
\r
302 user, return to the new OpenSRF build directory and use the
\r
303 <command>make</command> utility to compile, link and install
\r
307 # as the root user:
\r
308 cd /home/opensrf/OpenSRF-1.6.3
\r
309 make install</userinput>
\r
311 <para>This step will take several minutes to complete.</para>
\r
314 <title>Update the System Dynamic Library Path</title>
\r
315 <para>You must update the system dynamic library path to force
\r
316 your system to recognize the newly installed libraries. As the
\r
317 <systemitem class="username">root</systemitem> user, do this by
\r
318 creating the new file
\r
319 <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing two
\r
320 new library paths, then execute the command
\r
321 <command>ldconfig</command> to automatically read the file and
\r
322 modify the system dynamic library path:</para>
\r
325 # as the root user:
\r
326 echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
\r
327 echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf
\r
328 ldconfig</userinput>
\r
331 <step xml:id="serversideinstallation-definedomains">
\r
332 <title>Define Public and Private OpenSRF Domains</title>
\r
333 <para>For security purposes, OpenSRF uses Jabber domains to separate services
\r
334 into public and private realms. On a single-server system the easiest way to
\r
335 define public and private OpenSRF domains is to define separate host names by
\r
336 adding entries to the file <filename>/etc/hosts</filename>.</para>
\r
337 <para>In the following steps we will use the example domains
\r
338 <systemitem class="domainname">public.localhost</systemitem> for the public
\r
339 domain and <systemitem class="domainname">private.localhost</systemitem>
\r
340 for the private domain. In an upcoming step, you will configure two special
\r
341 <systemitem class="service">ejabberd</systemitem> users
\r
342 to handle communications for these two domains.</para>
\r
343 <para>As the <systemitem class="username">root</systemitem> user, edit the file
\r
344 <filename>/etc/hosts</filename> and add the following example domains:</para>
\r
346 <primary>Jabber</primary>
\r
350 # as the root user:
\r
351 127.0.1.2 public.localhost public
\r
352 127.0.1.3 private.localhost private</userinput>
\r
356 <title>Change File Ownerships</title>
\r
357 <para>Finally, as the <systemitem class="username">root</systemitem>
\r
358 user, change the ownership of all files installed in the
\r
359 directory <filename class="directory">/openils</filename> to the
\r
360 user <systemitem class="username">opensrf</systemitem>:</para>
\r
363 # as the root user:
\r
364 chown -R opensrf:opensrf /openils</userinput>
\r
369 <step xml:id="stop-ejabberd-service">
\r
370 <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
\r
372 <primary>ejabberd</primary>
\r
374 <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
\r
375 you must stop that service. As the <systemitem class="username">root</systemitem> user,
\r
376 execute the following command to stop the service:</para>
\r
379 # as the root user:
\r
380 /etc/init.d/ejabberd stop</userinput>
\r
382 <para>If <systemitem class="service">ejabberd</systemitem> reports that it
\r
383 is already stopped, there may have been a problem when it started back
\r
384 in the installation step. If there are any remaining daemon processes such as
\r
385 <systemitem class="daemon">beam</systemitem> or
\r
386 <systemitem class="daemon">epmd</systemitem>
\r
387 you may need to perform the following commands to kill them:</para>
\r
390 # as the root user:
\r
392 killall beam; killall beam.smp
\r
393 rm /var/lib/ejabberd/*
\r
394 echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
\r
398 <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
\r
399 <para>You must make several configuration changes for the
\r
400 <systemitem class="service">ejabberd</systemitem> service before
\r
401 it is started again.
\r
402 As the <systemitem class="username">root</systemitem> user, edit the file
\r
403 <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
\r
406 <para>Change the line:</para>
\r
407 <literal>{hosts, ["localhost"]}.</literal>
\r
408 <para>to instead read:</para>
\r
409 <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
\r
413 <para>Change the line for older versions of <systemitem class="service">ejabberd</systemitem>:</para>
\r
414 <literal>{max_user_sessions, 10}</literal>
\r
415 <para>to instead read:</para>
\r
416 <literal>{max_user_sessions, 10000}</literal>
\r
418 <para>Change the line for newer versions of <systemitem class="service">ejabberd</systemitem>:</para>
\r
419 <literal>{access, max_user_sessions, [{10, all}]}</literal>
\r
420 <para>to instead read:</para>
\r
421 <literal>{access, max_user_sessions, [{10000, all}]}</literal>
\r
424 <para>Change all three occurrences of:</para>
\r
425 <literal>max_stanza_size</literal>
\r
426 <para>to instead read:</para>
\r
427 <literal>2000000</literal>
\r
430 <para>Change both occurrences of:</para>
\r
431 <literal>maxrate</literal>
\r
432 <para>to instead read:</para>
\r
433 <literal>500000</literal>
\r
436 <para>Comment out the line:</para>
\r
437 <literal>{mod_offline, []}</literal>
\r
438 <para>by placing two <literal>%</literal> comment signs in front
\r
439 so it instead reads:</para>
\r
440 <literal>%%{mod_offline, []}</literal>
\r
444 <step xml:id="serversideinstallation-opensrf-continued">
\r
445 <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
\r
446 <para>As the <systemitem class="username">root</systemitem> user, restart the
\r
447 <systemitem class="service">ejabberd</systemitem> service to test the
\r
448 configuration changes and to register your users:</para>
\r
451 # as the root user:
\r
452 /etc/init.d/ejabberd start</userinput>
\r
456 <title>Register <systemitem class="username">router</systemitem> and
\r
457 <systemitem class="username">opensrf</systemitem> as
\r
458 <systemitem class="service">ejabberd</systemitem> users</title>
\r
459 <para>The two <systemitem class="service">ejabberd</systemitem> users
\r
460 <systemitem class="username">router</systemitem> and
\r
461 <systemitem class="username">opensrf</systemitem> must be registered
\r
462 and configured to manage OpenSRF router service and communications
\r
463 for the two domains <literal>public.localhost</literal> and
\r
464 <literal>private.localhost</literal> that you added to the file
\r
465 <filename>/etc/hosts</filename> in a previous step
\r
466 (see <xref linkend="serversideinstallation-definedomains"/>).
\r
467 The users include:</para>
\r
470 <para>the <systemitem class="username">router</systemitem> user,
\r
471 to whom all requests to connect to an OpenSRF service will be
\r
475 <para>the <systemitem class="username">opensrf</systemitem> user,
\r
476 which clients use to connect to OpenSRF services (you may name
\r
477 the user anything you like, but we use
\r
478 <literal>opensrf</literal> in these examples)</para>
\r
481 <para>As the <systemitem class="username">root</systemitem> user, execute the
\r
482 <command>ejabberdctl</command> utility as shown below to register and create passwords
\r
483 for the users <systemitem class="username">router</systemitem> and
\r
484 <systemitem class="username">opensrf</systemitem> on each domain (remember to replace
\r
485 <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
\r
488 # as the root user:
\r
489 # Note: the syntax for registering a user with ejabberdctl is:
\r
490 # ejabberdctl register USER DOMAIN PASSWORD
\r
491 ejabberdctl register router private.localhost NEWPASSWORD
\r
492 ejabberdctl register router public.localhost NEWPASSWORD
\r
493 ejabberdctl register opensrf private.localhost NEWPASSWORD
\r
494 ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
\r
496 <para>The users <systemitem class="username">router</systemitem> and
\r
497 <systemitem class="username">opensrf</systemitem> and their respective passwords
\r
498 will be used again in <xref linkend="serversideinstallation-passwords"/> when
\r
499 we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para>
\r
502 There appears to be a problem with <command>ejabberdctl</command> in
\r
503 that it does not escape input correctly, so a password like
\r
504 <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
\r
505 A bug against ejabberd has been filed. To register a password using
\r
506 <command>ejabberdctl</command> with special shell characters until such
\r
507 time as that bug is resolved, the workaround is to specify a
\r
508 double-escaped character at the command line, for example,
\r
509 <literal>'0P3N\\\\$RF'</literal> .</para>
\r
512 <step xml:id="serversideinstallation-opensrf-createconfig">
\r
513 <title>Create OpenSRF configuration files</title>
\r
514 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
515 execute the following commands to create the new configuration files
\r
516 <filename>/openils/conf/opensrf_core.xml</filename> and
\r
517 <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
\r
520 # as the opensrf user:
\r
522 cp opensrf.xml.example opensrf.xml
\r
523 cp opensrf_core.xml.example opensrf_core.xml</userinput>
\r
526 <step xml:id="serversideinstallation-passwords">
\r
527 <title>Update usernames and passwords in the OpenSRF configuration file</title>
\r
528 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
529 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
\r
530 and update the usernames and passwords to match the values shown in the
\r
531 following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
\r
532 shows common XPath syntax to indicate the approximate position within the XML
\r
533 file that needs changes. The right-hand side of the table shows the replacement
\r
535 <table xml:id="serversideinstallation-xpath-table-1">
\r
536 <?dbfo keep-together="always" ?>
\r
537 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
\r
538 <tgroup align="left" cols="2" colsep="1" rowsep="1">
\r
539 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
\r
540 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
\r
543 <entry>XPath location</entry>
\r
544 <entry>Value</entry>
\r
549 <entry>/config/opensrf/username</entry>
\r
551 <systemitem class="username">opensrf</systemitem>
\r
555 <entry>/config/opensrf/passwd </entry>
\r
556 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
558 <systemitem class="username">opensrf</systemitem> user
\r
562 <entry>/config/gateway/username</entry>
\r
564 <systemitem class="username">opensrf</systemitem>
\r
568 <entry>/config/gateway/passwd</entry>
\r
569 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
571 <systemitem class="username">opensrf</systemitem> user
\r
575 <entry>/config/routers/router/transport/username,
\r
576 first entry where server == public.localhost</entry>
\r
578 <systemitem class="username">router</systemitem>
\r
582 <entry>/config/routers/router/transport/password,
\r
583 first entry where server == public.localhost</entry>
\r
584 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
586 <systemitem class="username">router</systemitem> user
\r
590 <entry>/config/routers/router/transport/username,
\r
591 second entry where server == private.localhost</entry>
\r
593 <systemitem class="username">router</systemitem>
\r
597 <entry>/config/routers/router/transport/password,
\r
598 second entry where server == private.localhost</entry>
\r
599 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
601 <systemitem class="username">router</systemitem> user
\r
607 <para>You may also need to modify the file to specify the domains from which
\r
608 <systemitem class="service">OpenSRF</systemitem> will accept connections,
\r
609 and to which it will make connections.
\r
610 If you are installing <application>OpenSRF</application> on a single server
\r
611 and using the <systemitem class="domainname">private.localhost</systemitem> and
\r
612 <systemitem class="domainname">public.localhost</systemitem> domains,
\r
613 these will already be set to the correct values. Otherwise, search and replace
\r
614 to match values for your own systems.</para>
\r
617 <title>Set the location of the persistent database</title>
\r
618 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
619 file <filename>/openils/conf/opensrf.xml</filename>, then find and verify that
\r
620 the element <literal>dbfile</literal> (near the end of the file) is set to the
\r
621 location of the persistent database. If necessary, change the default line:</para>
\r
622 <literal>/openils/var/persist.db</literal>
\r
623 <para>to instead read:</para>
\r
624 <literal>/tmp/persist.db</literal>
\r
625 <para>Following is a sample modification of that portion of the file:</para>
\r
626 <programlisting language="xml"><![CDATA[
\r
627 <!-- Example of an app-specific setting override -->
\r
630 <dbfile>/tmp/persist.db</dbfile>
\r
633 ]]></programlisting>
\r
635 <step xml:id="serversideinstallation-srfsh">
\r
636 <title>Create configuration files for users needing <command>srfsh</command></title>
\r
637 <para>In this section you will set up a special configuration file for each user
\r
638 who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
\r
639 shell</emphasis>) utility.</para>
\r
641 <primary>srfsh</primary>
\r
643 <para>The software installation will automatically create the utility
\r
644 <command>srfsh</command>, a command line diagnostic tool for testing and
\r
645 interacting with <application>OpenSRF</application>. It will be used
\r
646 in a future step to complete and test the Evergreen installation. See
\r
647 <xref linkend="serversideinstallation-testing"/> for further information.</para>
\r
648 <para>As the <systemitem class="username">root</systemitem> user, copy the
\r
649 sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
\r
650 to the home directory of each user who will use <command>srfsh</command>.
\r
651 For instance, do the following for the
\r
652 <systemitem class="username">opensrf</systemitem> user:</para>
\r
655 # as the root user:
\r
656 cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>
\r
658 <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
\r
659 following changes:</para>
\r
662 <para>Modify <literal>domain</literal> to be the router hostname
\r
663 (following our domain examples,
\r
664 <systemitem class="domainname">private.localhost</systemitem> will give
\r
665 <command>srfsh</command> access to all OpenSRF services, while
\r
666 <systemitem class="domainname">public.localhost</systemitem>
\r
667 will only allow access to those OpenSRF services that are
\r
668 publicly exposed).</para>
\r
671 <para>Modify <literal>username</literal> and
\r
672 <literal>password</literal> to match the
\r
673 <literal>opensrf</literal> Jabber user for the chosen
\r
677 <para>Modify <literal>logfile</literal> to be the full path for
\r
678 a log file to which the user has write access</para>
\r
681 <para>Modify <literal>loglevel</literal> as needed for testing</para>
\r
684 <para>Change the owner of the file to match the owner of the home directory</para>
\r
687 <para>Following is a sample of the file:</para>
\r
688 <programlisting language="xml"><![CDATA[
\r
689 <?xml version="1.0"?>
\r
690 <!-- This file follows the standard bootstrap config file layout -->
\r
691 <!-- found in opensrf_core.xml -->
\r
693 <router_name>router</router_name>
\r
694 <domain>private.localhost</domain>
\r
695 <username>opensrf</username>
\r
696 <passwd>SOMEPASSWORD</passwd>
\r
698 <logfile>/tmp/srfsh.log</logfile>
\r
699 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
\r
700 <loglevel>4</loglevel>
\r
702 ]]></programlisting>
\r
705 <title>Modify the environmental variable <envar>PATH</envar> for the
\r
706 <systemitem class="username">opensrf</systemitem> user</title>
\r
707 <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
\r
708 environmental variable <envar>PATH</envar> by adding a new file path to the
\r
709 <systemitem class="username">opensrf</systemitem> user's shell configuration
\r
710 file <filename>~/.bashrc</filename>:</para>
\r
713 # as the opensrf user:
\r
714 echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
\r
718 <title>Start OpenSRF</title>
\r
719 <para>As the <systemitem class="username">root</systemitem> user, start the
\r
720 <systemitem class="service">ejabberd</systemitem> and
\r
721 <systemitem class="service">memcached</systemitem> services:</para>
\r
724 # as the root user:
\r
725 /etc/init.d/ejabberd start
\r
726 /etc/init.d/memcached start</userinput>
\r
728 <para>Then as the <systemitem class="username">opensrf</systemitem> user,
\r
729 start OpenSRF as follows:</para>
\r
732 # as the opensrf user:
\r
733 osrf_ctl.sh -l -a start_all</userinput>
\r
735 <para>The flag <option>-l</option> forces Evergreen to use
\r
736 <systemitem class="domainname">localhost</systemitem> (your current system)
\r
737 as the hostname. The flag <option>-a start_all</option> starts the
\r
738 OpenSRF <systemitem class="service">router</systemitem> ,
\r
739 <systemitem class="service">Perl</systemitem> , and
\r
740 <systemitem class="service">C</systemitem> services.</para>
\r
743 <para>You can also start Evergreen without the
\r
744 <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
\r
745 utility must know the fully qualified domain name for the system
\r
746 on which it will execute. That hostname was probably specified
\r
747 in the configuration file <filename>opensrf.xml</filename> which
\r
748 you configured in a previous step.</para>
\r
751 <para>If you receive an error message similar to
\r
752 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
\r
753 environment variable <envar>PATH</envar> does not include the
\r
754 directory <filename class="directory">/openils/bin</filename>.
\r
755 As the <systemitem class="username">opensrf</systemitem> user,
\r
756 edit the configuration file <filename>~/.bashrc</filename> and
\r
757 add the following line:
\r
758 <literal>export PATH=$PATH:/openils/bin</literal></para>
\r
763 <title>Test connections to OpenSRF</title>
\r
764 <para>Once you have installed and started OpenSRF, as the
\r
765 <systemitem class="username">root</systemitem> user test your connection to
\r
766 <systemitem class="service">OpenSRF</systemitem> with the <command>srfsh</command>
\r
767 utility and try to call the <command>add</command> method on the OpenSRF
\r
768 <systemitem class="service">math</systemitem> service:</para>
\r
771 # as the root user:
\r
772 /openils/bin/srfsh</userinput>
\r
774 srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
\r
777 ------------------------------------
\r
778 Request Completed Successfully
\r
779 Request Time in seconds: 0.007519
\r
780 ------------------------------------</computeroutput>
\r
782 <para>For other <command>srfsh</command> commands, type in
\r
783 <userinput>help</userinput> at the prompt.</para>
\r
786 <title>Stop OpenSRF</title>
\r
787 <para>After OpenSRF has started, you can stop it at any time by using the
\r
788 <command>osrf_ctl.sh</command> again. As the
\r
789 <systemitem class="username">opensrf</systemitem>
\r
790 user, stop OpenSRF as follows:</para>
\r
793 # as the opensrf user:
\r
794 osrf_ctl.sh -l -a stop_all</userinput>
\r
799 <section xml:id="serversideinstallation-ubuntudebian">
\r
800 <title>Installing Evergreen 2.0 On <systemitem class="osname">Ubuntu</systemitem> or
\r
801 <systemitem class="osname">Debian</systemitem></title>
\r
803 <primary>Linux</primary>
\r
804 <secondary>Debian</secondary>
\r
807 <primary>Linux</primary>
\r
808 <secondary>Ubuntu</secondary>
\r
810 <para>This section outlines the installation process for the latest stable version of
\r
812 <para>In this section you will download, unpack, install, configure and test the Evergreen
\r
813 system, including the Evergreen server and the PostgreSQL database system. You will make several
\r
814 configuration changes and adjustments to the software, including updates to configure the system
\r
815 for your own locale, and some updates needed to work around a few known issues.</para>
\r
817 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
\r
818 architectures. There may be differences between the Desktop and Server editions of
\r
819 <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
\r
821 <para>In the following instructions, you are asked to perform certain steps as
\r
822 either the <systemitem class="username">root</systemitem> user, the
\r
823 <systemitem class="username">opensrf</systemitem> user, or the
\r
824 <systemitem class="username">postgres</systemitem> user.</para>
\r
827 <para><systemitem class="osname">Debian</systemitem> -- To become the
\r
828 <systemitem class="username">root</systemitem> user, issue the command
\r
829 <command>su -</command> and enter the password of the
\r
830 <systemitem class="username">root</systemitem> user.</para>
\r
833 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
\r
834 <systemitem class="username">root</systemitem> user, issue the command
\r
835 <command>sudo su -</command> and enter the password of the
\r
836 <systemitem class="username">root</systemitem> user.</para>
\r
839 <para>To switch from the <systemitem class="username">root</systemitem> user to a
\r
840 different user, issue the command <command>su - USERNAME</command>. For example, to
\r
841 switch from the <systemitem class="username">root</systemitem> user to the
\r
842 <systemitem class="username">opensrf</systemitem> user, issue the command
\r
843 <command>su - opensrf</command>. Once you have become a non-root user, to become the
\r
844 <systemitem class="username">root</systemitem> user again, simply issue the command
\r
845 <command>exit</command>.</para>
\r
849 <title>Install OpenSRF</title>
\r
850 <para>Evergreen software is integrated with and depends on the Open Service
\r
851 Request Framework (OpenSRF) software system. For further information on
\r
852 installing, configuring and testing OpenSRF, see
\r
853 <xref linkend="serversideinstallation-opensrf"/>.</para>
\r
854 <para>Follow the steps outlined in that section and run the specified tests to
\r
855 ensure that OpenSRF is properly installed and configured. Do
\r
856 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
\r
857 any further Evergreen installation steps until you have verified that OpenSRF
\r
858 has been successfully installed and tested.</para>
\r
861 <title>Download and Unpack Latest Evergreen Version</title>
\r
862 <para>The latest version of Evergreen can be found here:
\r
863 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
\r
864 As the <systemitem class="username">opensrf</systemitem> user, change to
\r
865 the directory <filename class="directory">/home/opensrf</filename> then download
\r
866 and extract Evergreen. The new subdirectory
\r
867 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename> will be created:</para>
\r
870 # as the opensrf user:
\r
872 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
\r
873 tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
\r
876 <step xml:id="serversideinstallation-installprereq">
\r
877 <title>Install Prerequisites to Build Evergreen</title>
\r
878 <para>In this section you will install and configure a set of prerequisites that will be
\r
879 used later in <xref linkend="serversideinstallation-configure"/> and
\r
880 <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
\r
881 using the <command>make</command> utility.</para>
\r
882 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
\r
883 below to build the prerequisites from the software distribution that you just downloaded
\r
884 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
\r
885 example with the keyword corresponding to the name of one of the
\r
886 <systemitem class="osname">Linux</systemitem> distributions listed in the following
\r
888 For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
\r
889 enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
\r
890 ubuntu-lucid</command>.</para>
\r
893 # as the root user:
\r
894 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
895 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
\r
900 <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>
\r
904 <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx
\r
905 (10.04)</systemitem></para>
\r
909 <step performance="optional" xml:id="serversideinstallation-postgresql-default">
\r
910 <title>(OPTIONAL) Install the PostgreSQL Server</title>
\r
912 <primary>databases</primary>
\r
913 <secondary>PostgreSQL</secondary>
\r
915 <para>Since the PostgreSQL server is usually a standalone server in multi-server
\r
916 production systems, the prerequisite installer Makefile in the previous section
\r
917 (see <xref linkend="serversideinstallation-installprereq"/>)
\r
918 does not automatically install PostgreSQL. You must install the PostgreSQL server
\r
919 yourself, either on the same system as Evergreen itself or on another system.
\r
920 If your PostgreSQL server is on a different system, just skip this step.
\r
921 If your PostgreSQL server will be on the same system as your Evergreen
\r
922 software, you can install the required PostgreSQL server packages as described
\r
923 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
\r
924 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
\r
925 for more information.</para>
\r
927 <para>PostgreSQL version 8.4 is the minimum supported version to work
\r
928 with Evergreen 2.0. If you have an older version of PostgreSQL,
\r
929 you should upgrade before installing Evergreen. To find your current version
\r
930 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
\r
931 user execute the command <command>psql</command>, then type
\r
932 <userinput>SELECT version();</userinput> to get detailed information
\r
933 about your version of PostgreSQL.</para>
\r
936 <step performance="optional">
\r
937 <title>Install Perl Modules on PostgreSQL Server</title>
\r
938 <para>If PostgreSQL is running on the same system as your Evergreen software,
\r
939 then the Perl modules will automatically be available. Just skip this step.
\r
940 Otherwise, continue if your PostgreSQL server is running on another system.</para>
\r
941 <para>You will need to install several Perl modules on the other system. As the
\r
942 <systemitem class="username">root</systemitem> user install the following Perl
\r
944 <para>as the root user, ensure the gcc compiler is installed:</para>
\r
946 <userinput>aptitude install gcc libxml-libxml-perl libxml-libxslt-perl</userinput>
\r
948 <para>then install the Perl modules:</para>
\r
950 <userinput>perl -MCPAN -e shell</userinput>
\r
951 <prompt>cpan></prompt> <userinput>Business::ISBN</userinput>
\r
952 <prompt>cpan></prompt> <userinput>install JSON::XS</userinput>
\r
953 <prompt>cpan></prompt> <userinput>Library::CallNumber::LC</userinput>
\r
954 <prompt>cpan></prompt> <userinput>install MARC::Record</userinput>
\r
955 <prompt>cpan></prompt> <userinput>install MARC::File::XML</userinput>
\r
956 <prompt>cpan></prompt> <userinput>cpan UUID::Tiny</userinput>
\r
958 <para>For more information on installing Perl Modules vist the official
\r
959 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
\r
961 <primary>Perl</primary>
\r
962 <secondary>CPAN</secondary>
\r
966 <title>Update the System Dynamic Library Path</title>
\r
967 <para>You must update the system dynamic library path to force your system to recognize
\r
968 the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
\r
969 do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
\r
970 containing a new library path, then run the command <command>ldconfig</command> to
\r
971 automatically read the file and modify the system dynamic library path:</para>
\r
974 # as the root user:
\r
975 echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
\r
976 echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
\r
977 ldconfig</userinput>
\r
980 <step performance="optional">
\r
981 <title>Restart the PostgreSQL Server</title>
\r
982 <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
\r
983 the <systemitem class="username">root</systemitem> user you must restart
\r
984 PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
\r
985 running on another system, you may skip this step.
\r
986 As the <systemitem class="username">opensrf</systemitem> user,
\r
987 execute the following command (remember to replace
\r
988 <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
\r
989 for example <literal>8.4</literal>):</para>
\r
992 # as the opensrf user:
\r
993 /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
\r
996 <step xml:id="serversideinstallation-configure">
\r
997 <title>Configure Evergreen</title>
\r
998 <para>In this step you will use the <command>configure</command> and
\r
999 <command>make</command> utilities to configure Evergreen so it can be compiled
\r
1000 and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
\r
1001 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
\r
1002 the Evergreen build directory and execute these commands:</para>
\r
1005 # as the opensrf user:
\r
1006 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1007 ./configure --prefix=/openils --sysconfdir=/openils/conf
\r
1011 <step xml:id="serversideinstallation-compile">
\r
1012 <title>Compile, Link and Install Evergreen</title>
\r
1013 <para>In this step you will actually compile, link and install Evergreen and the
\r
1014 default Evergreen Staff Client.</para>
\r
1015 <para>As the <systemitem class="username">root</systemitem> user, return to the
\r
1016 Evergreen build directory and use the <command>make</command> utility as shown below:</para>
\r
1019 # as the root user:
\r
1020 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1021 make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
\r
1023 <para>The Staff Client will also be automatically built, but you must remember
\r
1024 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
\r
1025 Staff Client you will use to connect to the Evergreen server.</para>
\r
1026 <para>The above commands will create a new subdirectory
\r
1027 <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
\r
1028 containing the Staff Client.</para>
\r
1029 <para>To complete the Staff Client installation, as the
\r
1030 <systemitem class="username">root</systemitem> user execute the following commands to
\r
1031 create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
\r
1032 directory <filename class="directory">/openils/var/web/xul</filename> that points to the
\r
1033 subdirectory <filename class="directory">/server</filename> of the new Staff Client
\r
1037 # as the root user:
\r
1038 cd /openils/var/web/xul
\r
1039 ln -sf rel_2_0_4/server server</userinput>
\r
1043 <title>Copy the OpenSRF Configuration Files</title>
\r
1044 <para>In this step you will replace some OpenSRF configuration files that you set up in
\r
1045 <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
\r
1046 tested OpenSRF.</para>
\r
1047 <para>You must copy several example OpenSRF configuration files into place after first
\r
1048 creating backup copies for troubleshooting purposes, then change all the file ownerships
\r
1049 to <systemitem class="username">opensrf</systemitem>.
\r
1050 As the <systemitem class="username">root</systemitem> user, execute the following
\r
1054 # as the root user:
\r
1056 cp opensrf.xml opensrf.xml.BAK
\r
1057 cp opensrf_core.xml opensrf_core.xml.BAK
\r
1058 cp opensrf.xml.example opensrf.xml
\r
1059 cp opensrf_core.xml.example opensrf_core.xml
\r
1060 cp oils_web.xml.example oils_web.xml
\r
1061 chown -R opensrf:opensrf /openils/</userinput>
\r
1065 <title>Create and Configure PostgreSQL Database</title>
\r
1067 <primary>databases</primary>
\r
1068 <secondary>PostgreSQL</secondary>
\r
1070 <para>In this step you will create the Evergreen database. In the commands
\r
1071 below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
\r
1072 repository to match your PostgreSQL server
\r
1073 layout. For example, if you built PostgreSQL from source the path would be
\r
1074 <filename class="directory">/usr/local/share/contrib</filename> , and if you
\r
1075 installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
\r
1076 the path would be
\r
1077 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
\r
1081 <emphasis role="bold">Create and configure the database</emphasis>
\r
1083 <para>As the <systemitem class="username">postgres</systemitem>
\r
1084 user on the PostgreSQL system create the PostgreSQL database,
\r
1085 then set some internal paths:</para>
\r
1088 # as the postgres user:
\r
1089 createdb evergreen -E UTF8 -T template0
\r
1090 createlang plperl evergreen
\r
1091 createlang plperlu evergreen
\r
1092 createlang plpgsql evergreen</userinput>
\r
1094 <para>Continue as the <systemitem class="username">postgres</systemitem> user
\r
1095 and execute the SQL scripts as shown below (remember to adjust the paths as needed,
\r
1096 where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL
\r
1097 version, for example <literal>8.4</literal>).</para>
\r
1100 # as the postgres user:
\r
1101 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
\r
1102 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
\r
1103 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
\r
1106 <step xml:id="serversideinstallation-postgresqlcreateuser">
\r
1107 <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
\r
1108 <para>As the <systemitem class="username">postgres</systemitem>
\r
1109 user on the PostgreSQL system, create a new PostgreSQL user
\r
1110 named <systemitem class="username">evergreen</systemitem> and
\r
1111 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
\r
1112 with an appropriate new password):</para>
\r
1115 # as the postgres user:
\r
1116 createuser -P -s evergreen</userinput>
\r
1118 Enter password for new role: <userinput>NEWPASSWORD</userinput>
\r
1119 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
\r
1123 <title>Create database schema</title>
\r
1124 <para>In this step you will create the database schema and configure your
\r
1125 system with the corresponding database authentication details for the
\r
1126 <emphasis>evergreen</emphasis> database user that you just created in
\r
1127 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
\r
1128 <para>As the <systemitem class="username">root</systemitem> user, enter
\r
1129 the following commands and replace <emphasis>HOSTNAME, PORT,
\r
1130 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
\r
1133 <userinput>cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1134 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
\r
1135 --service all --create-schema --create-offline \
\r
1136 --hostname HOSTNAME --port PORT \
\r
1137 --user evergreen --password PASSWORD \
\r
1138 --database DATABASENAME --admin-user ADMIN-USER \
\r
1139 --admin-pass ADMIN-PASSWORD </userinput>
\r
1141 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
\r
1142 <emphasis role="bold">localhost</emphasis> and
\r
1143 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
\r
1144 Of course, values for <emphasis>PASSWORD</emphasis> and
\r
1145 <emphasis>DATABASENAME</emphasis> must match the values you used in
\r
1146 <xref linkend="serversideinstallation-postgresqlcreateuser"/>. The <option>admin-user</option> and <option>admin-pass</option> options will
\r
1147 specify the Evergreen administrator account's username and password. This was
\r
1148 changed for security reasons, it was previously admin/open-ils</para>
\r
1149 <para>As the command executes, you may see warnings similar to:
\r
1150 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
\r
1151 you may see one warning per schema) but they can be safely ignored.</para>
\r
1152 <note>If you are entering the above command on a single line, do not
\r
1153 include the <literal>\</literal> (backslash) characters. If you are using
\r
1154 the <command>bash</command> shell, these should only be used at the end of
\r
1155 a line at a <command>bash</command> prompt to indicate that the command is
\r
1156 continued on the next line.</note>
\r
1161 <title>Configure the Apache web server</title>
\r
1163 <primary>web server</primary>
\r
1164 <secondary>Apache</secondary>
\r
1166 <para>In this step you will configure the Apache web server to support Evergreen
\r
1168 <para>First, you must enable some built-in Apache modules and install some
\r
1169 additional Apache configuration files. Then you will create a new Security
\r
1170 Certificate. Finally, you must make several changes to the Apache configuration
\r
1174 <title>Enable the required Apache Modules</title>
\r
1175 <para>As the <systemitem class="username">root</systemitem>
\r
1176 user, enable some modules in the Apache server, then copy the
\r
1177 new configuration files to the Apache server directories:</para>
\r
1179 <primary>Apache modules</primary>
\r
1183 # as the root user:
\r
1184 a2enmod ssl # enable mod_ssl
\r
1185 a2enmod rewrite # enable mod_rewrite
\r
1186 a2enmod expires # enable mod_expires</userinput>
\r
1188 <para>As the commands execute, you may see warnings similar to:
\r
1189 <literal>Module SOMEMODULE already enabled</literal> but you can
\r
1190 safely ignore them.</para>
\r
1193 <title>Copy Apache configuration files</title>
\r
1194 <para>You must copy the Apache configuration files from the
\r
1195 Evergreen installation directory to the Apache directory. As the
\r
1196 <systemitem class="username">root</systemitem> user, perform the
\r
1197 following commands:</para>
\r
1200 # as the root user:
\r
1201 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1202 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/
\r
1203 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
\r
1204 cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
\r
1207 <step xml:id="serversideinstallation-createsslcertificate">
\r
1208 <title>Create a Security Certificate</title>
\r
1209 <para>In this step you will create a new Security Certificate (SSL Key)
\r
1210 for the Apache server using the <command>openssl</command> command. For a
\r
1211 public production server you must configure or purchase a signed SSL
\r
1212 certificate, but for now you can just use a self-signed certificate and
\r
1213 accept the warnings in the Staff Client and browser during testing and
\r
1214 development. As the <systemitem class="username">root</systemitem> user,
\r
1215 perform the following commands:</para>
\r
1218 # as the root user:
\r
1219 mkdir /etc/apache2/ssl
\r
1220 cd /etc/apache2/ssl
\r
1221 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
\r
1223 <para>You will be prompted for several items of information; enter
\r
1224 the appropriate information for each item. The new files
\r
1225 <filename>server.crt</filename> and <filename>server.key</filename> will
\r
1226 be created in the directory
\r
1227 <filename class="directory">/etc/apache2/ssl</filename> .</para>
\r
1228 <note>This step generates a self-signed SSL certificate. You must install
\r
1229 a proper SSL certificate for a public production system to avoid warning
\r
1230 messages when users login to their account through the OPAC or when staff
\r
1231 login through the Staff Client. For further information on
\r
1232 installing a proper SSL certificate, see
\r
1233 <xref linkend="serversideinstallation-ssl"/>.</note>
\r
1235 <step xml:id="serversideinstallation-modify-apache">
\r
1236 <title>Update Apache configuration file</title>
\r
1237 <para>You must make several changes to the new Apache
\r
1238 configuration file
\r
1239 <filename>/etc/apache2/sites-available/eg.conf</filename> .
\r
1240 As the <systemitem class="username">root</systemitem> user,
\r
1241 edit the file and make the following changes:</para>
\r
1244 <para>In the section
\r
1245 <literal><Directory "/openils/var/cgi-bin"></literal>
\r
1246 replace the line:</para>
\r
1247 <literal>Allow from 10.0.0.0/8</literal>
\r
1248 <para>with the line:</para>
\r
1249 <literal>Allow from all</literal>
\r
1250 <warning>This change allows access to your configuration
\r
1251 CGI scripts from any workstation on any network. This is
\r
1252 only a temporary change to expedite testing and should be
\r
1253 removed after you have finished and successfully tested
\r
1254 the Evergreen installation. See
\r
1255 <xref linkend="serversideinstallation-postinstallation"/>
\r
1256 for further details on removing this change after the
\r
1257 Evergreen installation is complete.
\r
1261 <para>Comment out the line:</para>
\r
1262 <literal>Listen 443</literal>
\r
1263 <para>since it conflicts with the same declaration in
\r
1264 the configuration file:</para>
\r
1265 <para><filename>/etc/apache2/ports.conf</filename>.</para>
\r
1268 <para>The following updates are needed to allow the logs
\r
1269 to function properly, but it may break other Apache
\r
1270 applications on your server:</para>
\r
1272 <para>Edit the Apache configuration file and change the lines:</para>
\r
1274 <userinput>export APACHE_RUN_USER=www-data</userinput>
\r
1275 <userinput>export APACHE_RUN_GROUP=www-data</userinput>
\r
1277 <para>to instead read:</para>
\r
1280 export APACHE_RUN_USER=opensrf
\r
1281 export APACHE_RUN_GROUP=opensrf</userinput>
\r
1286 <systemitem class="username">root</systemitem> user,
\r
1287 edit the Apache configuration file
\r
1288 <filename>/etc/apache2/apache2.conf</filename> and
\r
1289 modify the value for <literal>KeepAliveTimeout</literal>
\r
1290 and <literal>MaxKeepAliveRequests</literal> to match
\r
1291 the following:</para>
\r
1294 KeepAliveTimeout 1
\r
1295 MaxKeepAliveRequests 100</userinput>
\r
1299 <para>Further configuration changes to Apache may be
\r
1300 necessary for busy systems. These changes increase the
\r
1301 number of Apache server processes that are started to
\r
1302 support additional browser connections.</para>
\r
1304 <systemitem class="username">root</systemitem> user,
\r
1305 edit the Apache configuration file
\r
1306 <filename>/etc/apache2/apache2.conf</filename>, locate
\r
1307 and modify the section related to <emphasis>prefork
\r
1308 configuration</emphasis> to suit the load on your
\r
1310 <programlisting language="xml"><![CDATA[
\r
1311 <IfModule mpm_prefork_module>
\r
1314 MaxSpareServers 15
\r
1316 MaxRequestsPerChild 10000
\r
1318 ]]></programlisting>
\r
1323 <title>Enable the Evergreen web site</title>
\r
1324 <para>Finally, you must enable the Evergreen web site. As the
\r
1325 <systemitem class="username">root</systemitem> user, execute the
\r
1326 following Apache configuration commands to disable the default
\r
1327 <emphasis>It Works</emphasis> web page and enable the Evergreen
\r
1328 web site, and then restart the Apache server:</para>
\r
1331 # as the root user:
\r
1332 # disable/enable web sites
\r
1335 # restart the server
\r
1336 /etc/init.d/apache2 reload</userinput>
\r
1341 <step xml:id="serversideinstallation-opensrf-config">
\r
1342 <title>Update the OpenSRF Configuration File</title>
\r
1343 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
1344 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
\r
1345 to update the Jabber usernames and passwords, and to specify the domain from
\r
1346 which we will accept and to which we will make connections.</para>
\r
1347 <para>If you are installing Evergreen on a single server and using the
\r
1348 <systemitem class="domainname">private.localhost</systemitem> /
\r
1349 <systemitem class="domainname">public.localhost</systemitem> domains,
\r
1350 these will already be set to the correct values. Otherwise, search and replace
\r
1351 to match your customized values.</para>
\r
1352 <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
\r
1353 shows common XPath syntax to indicate the approximate position within the XML
\r
1354 file that needs changes. The right-hand side of the table shows the replacement
\r
1356 <table xml:id="serversideinstallation-xpath-table-2">
\r
1357 <?dbfo keep-together="always" ?>
\r
1358 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
\r
1359 <tgroup align="left" cols="2" colsep="1" rowsep="1">
\r
1360 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
\r
1361 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
\r
1364 <entry>XPath location</entry>
\r
1365 <entry>Value</entry>
\r
1370 <entry>/config/opensrf/username</entry>
\r
1372 <systemitem class="username">opensrf</systemitem>
\r
1376 <entry>/config/opensrf/passwd </entry>
\r
1377 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
1379 <systemitem class="username">opensrf</systemitem> user
\r
1383 <entry>/config/gateway/username</entry>
\r
1385 <systemitem class="username">opensrf</systemitem>
\r
1389 <entry>/config/gateway/passwd</entry>
\r
1390 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
1392 <systemitem class="username">opensrf</systemitem> user
\r
1396 <entry>/config/routers/router/transport/username,
\r
1397 first entry where server == public.localhost</entry>
\r
1399 <systemitem class="username">router</systemitem>
\r
1403 <entry>/config/routers/router/transport/password,
\r
1404 first entry where server == public.localhost</entry>
\r
1405 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
1407 <systemitem class="username">router</systemitem> user
\r
1411 <entry>/config/routers/router/transport/username,
\r
1412 second entry where server == private.localhost</entry>
\r
1414 <systemitem class="username">router</systemitem>
\r
1418 <entry>/config/routers/router/transport/password,
\r
1419 second entry where server == private.localhost</entry>
\r
1420 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
1422 <systemitem class="username">router</systemitem> user
\r
1429 <step performance="optional">
\r
1430 <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
\r
1431 <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
\r
1432 software installation automatically created a utility named <command>srfsh</command> (surf
\r
1433 shell). This is a command line diagnostic tool for testing and interacting with
\r
1434 OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
\r
1435 Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration
\r
1436 file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
\r
1437 See <xref linkend="serversideinstallation-testing"/> for further information.</para>
\r
1439 <step xml:id="serversideinstallation-opensrf-env">
\r
1440 <title>Modify the OpenSRF Environment</title>
\r
1441 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
\r
1444 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
1445 modify the shell configuration file <filename>~/.bashrc</filename> for
\r
1446 user <systemitem class="username">opensrf</systemitem> by adding a Perl
\r
1447 environmental variable, then execute the shell configuration file to load
\r
1448 the new variables into your current environment.</para>
\r
1449 <note>In a multi-server environment, you must add any
\r
1450 modifications to <filename>~/.bashrc</filename> to the top of the file
\r
1451 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
\r
1452 return </literal>. This will allow headless (scripted) logins to load the
\r
1453 correct environment.</note>
\r
1456 # as the opensrf user:
\r
1457 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
\r
1458 . ~/.bashrc</userinput>
\r
1463 <step performance="optional">
\r
1464 <title>(OPTIONAL) Enable and Disable Language Localizations</title>
\r
1465 <para>You can load translations such as Armenian (hy-AM), Canadian French
\r
1466 (fr-CA), and others into the database to complete the translations available in
\r
1467 the OPAC and Staff Client. For further information, see
\r
1468 <xref linkend="languagesandlocalization"/>.</para>
\r
1472 <section xml:id="serversideinstallation-fedora">
\r
1473 <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or
\r
1474 <systemitem class="osname">Fedora 14</systemitem> </title>
\r
1476 <section xml:id="serversideinstallation-starting">
\r
1477 <title>Starting Evergreen</title>
\r
1478 <para>In this section you will learn how to start the Evergreen services.
\r
1479 For completeness, instructions for stopping Evergreen can be found later in
\r
1480 <xref linkend="serversideinstallation-stopping"/>.</para>
\r
1483 <para>As the <systemitem class="username">root</systemitem>
\r
1484 user, start the <systemitem class="service">ejabberd</systemitem> and
\r
1485 <systemitem class="service">memcached</systemitem> services as follows:</para>
\r
1488 # as the root user:
\r
1489 /etc/init.d/ejabberd start
\r
1490 /etc/init.d/memcached start</userinput>
\r
1494 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
1495 start the OpenSRF router service as follows:</para>
\r
1498 # as the opensrf user:
\r
1499 osrf_ctl.sh -l -a start_all</userinput>
\r
1501 <para>The flag <option>-l</option> forces Evergreen to use
\r
1502 <systemitem class="domainname">localhost</systemitem> (your current system)
\r
1503 as the hostname. The flag <option>-a start_all</option> starts the
\r
1504 OpenSRF <systemitem class="service">router</systemitem> ,
\r
1505 <systemitem class="service">Perl</systemitem> , and
\r
1506 <systemitem class="service">C</systemitem> services.</para>
\r
1509 <para>You can also start Evergreen without the
\r
1510 <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
\r
1511 utility must know the fully qualified domain name for the system
\r
1512 on which it will execute. That hostname was probably specified
\r
1513 in the configuration file <filename>opensrf.xml</filename> which
\r
1514 you configured in a previous step.</para>
\r
1517 <para>If you receive an error message similar to
\r
1518 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
\r
1519 environment variable <envar>PATH</envar> does not include the
\r
1520 directory <filename class="directory">/openils/bin</filename>.
\r
1521 As the <systemitem class="username">opensrf</systemitem> user,
\r
1522 edit the configuration file <filename>~/.bashrc</filename> and
\r
1523 add the following line:
\r
1524 <literal>export PATH=$PATH:/openils/bin</literal></para>
\r
1527 <para>If you receive an error message similar to <emphasis>Can't
\r
1528 locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
\r
1529 aborted</emphasis>, then your environment variable
\r
1530 <emphasis role="bold">PERL5LIB</emphasis> does not include the
\r
1531 directory <filename class="directory">/openils/lib/perl5</filename>.
\r
1532 As the <systemitem class="username">opensrf</systemitem> user,
\r
1533 edit the configuration file <filename>~/.bashrc</filename> and
\r
1534 add the following line:
\r
1535 <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
\r
1540 <para>In this step you will generate the Web files needed by the Staff Client
\r
1541 and catalog, and update the proximity of locations in the Organizational Unit
\r
1542 tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
\r
1543 <para>You must do this the first time you start Evergreen and after making any
\r
1544 changes to the library hierarchy.</para>
\r
1545 <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
\r
1546 following command and review the results:</para>
\r
1549 # as the opensrf user:
\r
1551 ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
\r
1553 Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
\r
1554 Updating fieldmapper
\r
1555 Updating web_fieldmapper
\r
1557 removing OrgTree from the cache for locale hy-AM...
\r
1558 removing OrgTree from the cache for locale cs-CZ...
\r
1559 removing OrgTree from the cache for locale en-CA...
\r
1560 removing OrgTree from the cache for locale en-US...
\r
1561 removing OrgTree from the cache for locale fr-CA...
\r
1562 removing OrgTree from the cache for locale ru-RU...
\r
1563 Updating OrgTree HTML
\r
1564 Updating locales selection HTML
\r
1565 Updating Search Groups
\r
1566 Refreshing proximity of org units
\r
1567 Successfully updated the organization proximity
\r
1568 Done</computeroutput>
\r
1572 <para>As the <systemitem class="username">root</systemitem> user, restart the
\r
1573 Apache Web server:</para>
\r
1576 # as the root user:
\r
1577 /etc/init.d/apache2 restart</userinput>
\r
1579 <note>If the Apache Web server was running when you started the OpenSRF
\r
1580 services, you might not be able to successfully log into the OPAC or Staff
\r
1581 Client until the Apache Web server has been restarted.</note>
\r
1585 <section xml:id="serversideinstallation-testing">
\r
1586 <title>Testing Your Evergreen Installation</title>
\r
1587 <para>This section describes several simple tests you can perform to verify that the Evergreen
\r
1588 server-side software has been installed and configured properly and is running as
\r
1590 <simplesect xml:id="serversideinstallation-testing-connections">
\r
1591 <title>Testing Connections to Evergreen</title>
\r
1592 <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
\r
1593 <command>srfsh</command> application and try logging onto the Evergreen server using the default
\r
1594 administrator username and password. Following is sample output generated by executing
\r
1595 <command>srfsh</command> after a successful Evergreen installation. For help with
\r
1596 <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
\r
1597 As the <systemitem class="username">opensrf</systemitem> user,
\r
1598 execute the following commands to test your Evergreen connection:</para>
\r
1601 # as the opensrf user:
\r
1602 /openils/bin/srfsh</userinput>
\r
1604 srfsh% <userinput>login admin open-ils</userinput>
\r
1605 Received Data: "250bf1518c7527a03249858687714376"
\r
1606 ------------------------------------
\r
1607 Request Completed Successfully
\r
1608 Request Time in seconds: 0.045286
\r
1609 ------------------------------------
\r
1612 "textcode":"SUCCESS",
\r
1615 "stacktrace":"oils_auth.c:304",
\r
1617 "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
\r
1621 ------------------------------------
\r
1622 Request Completed Successfully
\r
1623 Request Time in seconds: 1.336568
\r
1624 ------------------------------------</computeroutput>
\r
1626 <para>If this does not work, try the following:</para>
\r
1629 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
\r
1630 <filename>settings-tester.pl</filename> utility to review your Evergreen
\r
1631 installation for any system configuration problems:</para>
\r
1634 # as the opensrf user:
\r
1636 ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
\r
1638 <para>If the output of <command>settings-tester.pl</command> does not help you
\r
1639 find the problem, please do not make any significant changes to your
\r
1640 configuration.</para>
\r
1643 <para>Follow the steps in the troubleshooting guide in
\r
1644 <xref linkend="troubleshooting"/>.</para>
\r
1647 <para>If you have followed the entire set of installation steps listed here
\r
1648 closely, you are probably extremely close to a working system. Gather your
\r
1649 configuration files and log files and contact the
\r
1650 <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
\r
1651 list for assistance before making any drastic changes to your system
\r
1652 configuration.</para>
\r
1656 <simplesect xml:id="serversideinstallation-running-staffclient">
\r
1657 <title>Testing the Staff Client on Linux</title>
\r
1658 <para>In this section you will confirm that a basic login on the Staff Client works
\r
1660 <para>Run the Evergreen Staff Client on a Linux system by using the application
\r
1661 <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
\r
1662 version 3.0 and later on Ubuntu and Debian distributions).</para>
\r
1663 <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
\r
1667 # as the root user:
\r
1668 xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini</userinput>
\r
1670 <para>A login screen for the Staff Client similar to this should appear:</para>
\r
1672 <alt>Logging into the Staff Client</alt>
\r
1674 <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>
\r
1677 <para>First, add the name of your Evergreen server to the field
\r
1678 <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably
\r
1679 want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test
\r
1680 Server. You should now see the messages <literal>200:OK</literal> in the fields
\r
1681 <literal>Status</literal> and <literal>Version</literal>.</para>
\r
1682 <para>Because this is the initial run of the Staff Client, you will see a warning in the
\r
1683 upper-right saying: <emphasis role="bold">Not yet configured for the specified
\r
1684 server</emphasis>. To continue, you must assign a workstation name.</para>
\r
1685 <para>Try to log into the Staff Client with the admin username and password you created during installation. If the login is successful,
\r
1686 you will see the following screen:</para>
\r
1688 <alt>Logging into the Staff Client</alt>
\r
1690 <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>
\r
1693 <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the
\r
1694 main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>
\r
1696 <alt>Adding an SSL Exception in the Staff Client</alt>
\r
1698 <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>
\r
1701 <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm
\r
1702 Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the
\r
1703 main window and try to log in again.</para>
\r
1705 <simplesect xml:id="serversideinstallation-starting-apache-server">
\r
1706 <title>Testing the Apache Web Server</title>
\r
1707 <para>In this section you will test the Apache configuration file(s), then restart the
\r
1708 Apache web server.</para>
\r
1709 <para>As the <emphasis role="bold">root</emphasis> user, execute the following
\r
1710 commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen
\r
1711 modules to be reloaded even if the Apache server is already running. Any problems found
\r
1712 with your configuration files should be displayed:</para>
\r
1715 # as the root user:
\r
1716 apache2ctl configtest && /etc/init.d/apache2 restart</userinput>
\r
1719 <simplesect xml:id="serversideinstallation-stopping">
\r
1720 <title>Stopping Evergreen</title>
\r
1721 <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the
\r
1722 Evergreen services. For completeness, following are instructions for stopping the
\r
1723 Evergreen services.</para>
\r
1724 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
\r
1725 services by using the following command:</para>
\r
1728 # as the opensrf user
\r
1729 # stop the server; use "-l" to force hostname to be "localhost"
\r
1730 osrf_ctl.sh -l -a stop_all</userinput>
\r
1732 <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the
\r
1733 <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the
\r
1734 fully qualified domain name for the system on which it will execute. That hostname may
\r
1735 have been specified in the configuration file <filename>opensrf.xml</filename>, which
\r
1736 you configured in a previous step.</note>
\r
1739 <section xml:id="serversideinstallation-postinstallation">
\r
1740 <title>Post-Installation Chores</title>
\r
1741 <para>There are several additional steps you may need to complete after Evergreen has been
\r
1742 successfully installed and tested. Some steps may not be needed (e.g., setting up support for
\r
1745 <title>Remove temporary Apache configuration changes</title>
\r
1746 <para>You modified the Apache configuration file
\r
1747 <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
\r
1748 temporary measure to expedite testing (see
\r
1749 <xref linkend="serversideinstallation-modify-apache"/> for further information).
\r
1750 Those changes must now be reversed in order to deny unwanted access to your
\r
1751 CGI scripts from users on other public networks.</para>
\r
1754 <emphasis>This temporary network update was done to expedite
\r
1755 testing. You <emphasis role="bold">must</emphasis> correct
\r
1756 this for a public production system.</emphasis>
\r
1759 <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
\r
1760 file again and comment out the line <literal>Allow from all</literal> and uncomment the
\r
1761 line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
\r
1762 address scheme.</para>
\r
1764 <section xml:id="serversideinstallation-ssl">
\r
1765 <title>Configure a permanent SSL key</title>
\r
1766 <para>You used the command <command>openssl</command> in an earlier step to
\r
1767 temporarily create a new SSL key for the Apache server (see
\r
1768 <xref linkend="serversideinstallation-createsslcertificate"/> for further
\r
1769 information). This self-signed security certificate was adequate during
\r
1770 testing and development, but will continue to generate warnings in the Staff
\r
1771 Client and browser. For a public production server you should configure or
\r
1772 purchase a signed SSL certificate.</para>
\r
1773 <para>There are several open source software solutions that provide schemes to
\r
1774 generate and maintain public key security certificates for your library
\r
1775 system. Some popular projects are listed below; please review them for
\r
1776 background information on why you need such a system and how you can provide
\r
1780 <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
\r
1783 <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
\r
1786 <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
\r
1791 <emphasis>The temporary SSL key was only created to expedite
\r
1792 testing. You should install a proper SSL certificate for a public
\r
1793 production system.</emphasis>
\r
1798 <title>(OPTIONAL) IP-Redirection</title>
\r
1799 <para>By default, Evergreen is configured so searching the OPAC always starts in the
\r
1800 top-level (regional) library rather than in a second-level (branch) library. Instead,
\r
1801 you can use "IP-Redirection" to change the default OPAC search location to use the IP
\r
1802 address range assigned to the second-level library where the seach originates. You must
\r
1803 configure these IP ranges by creating the configuration file
\r
1804 <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
\r
1805 <filename>/etc/apache2/startup.pl</filename>.</para>
\r
1806 <para>First, copy the sample file
\r
1807 <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>
\r
1808 to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
\r
1809 line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
\r
1810 the IP address ranges for your library system. Add new lines to represent the IP address
\r
1811 range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
\r
1812 values for each branch library found in the table
\r
1813 <literal>actor.org_unit</literal>.</para>
\r
1814 <para>Finally, modify the Apache startup script
\r
1815 <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
\r
1816 restarting the Apache server:</para>
\r
1817 <programlisting language="xml"><![CDATA[
\r
1818 # - Uncomment the following 2 lines to make use of the IP redirection code
\r
1819 # - The IP file should contain a map with the following format:
\r
1820 # - actor.org_unit.shortname <start_ip> <end_ip>
\r
1821 # - e.g. LIB123 10.0.0.1 10.0.0.254
\r
1822 use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
\r
1823 OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
\r
1824 ]]></programlisting>
\r
1827 <title>(OPTIONAL) Set Up Support For Reports</title>
\r
1828 <para>Evergreen reports are extremely powerful but require some simple configuration.
\r
1829 See <xref linkend="report_starting_reporter_service"/> for information on starting and
\r
1830 stopping the Reporter daemon processes.</para>
\r
projects / working / Evergreen.git / blob