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. </para>
\r
13 <para>The current version of the Evergreen server-side software runs as a native application on any of several
\r
14 well-known <systemitem class="osname">Linux</systemitem> distributions
\r
15 (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
\r
16 It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
\r
17 operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
\r
18 Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
\r
19 installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
\r
20 <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
\r
21 <application>"VirtualBox"</application> or <application>"VMware"</application>
\r
22 to emulate a <systemitem class="osname">Linux</systemitem>
\r
23 environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
\r
24 systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
\r
25 <application>"VMware"</application>).</para>
\r
26 <para>The Evergreen server-side software has dependencies on particular versions of certain major software
\r
27 sub-components. Successful installation of Evergreen software requires that software versions agree with those
\r
29 <table xml:id="serversideinstall-software-dependencies">
\r
30 <?dbfo keep-together="always" ?>
\r
31 <title>Evergreen Software Dependencies</title>
\r
33 <primary>Evergreen software dependencies</primary>
\r
35 <tgroup align="left" cols="3" colsep="1" rowsep="1">
\r
36 <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
\r
37 <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
\r
38 <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
\r
41 <entry>Evergreen</entry>
\r
42 <entry>OpenSRF</entry>
\r
43 <entry>PostgreSQL</entry>
\r
49 <entry>1.6.3</entry>
\r
55 <section xml:id="serversideinstallation-all">
\r
56 <title>Installing Server-Side Software</title>
\r
57 <para>This section describes the installation of the major components of Evergreen server-side software.</para>
\r
58 <para>As far as possible, you should perform the following steps in the exact order given since the
\r
59 success of many steps relies on the successful completion of earlier steps. You should make backup
\r
60 copies of files and environments when you are instructed to do so. In the event of installation problems
\r
61 those copies can allow you to back out of a step gracefully and resume the installation from a known
\r
62 state. See <xref linkend="backingup"/> for further information.</para>
\r
63 <para>Of course, after you successfully complete and test the entire Evergreen installation you should
\r
64 take a final snapshot backup of your system(s). This can be the first in the series of regularly
\r
65 scheduled system backups that you should probably also begin.</para>
\r
66 <section xml:id="serversideinstallation-opensrf">
\r
68 <primary>OpenSRF</primary>
\r
69 <secondary>installation</secondary>
\r
71 <title>Installing OpenSRF 1.6.3 On <systemitem class="osname">Ubuntu</systemitem> or
\r
72 <systemitem class="osname">Debian</systemitem></title>
\r
74 <primary>Linux</primary>
\r
75 <secondary>Debian</secondary>
\r
78 <primary>Linux</primary>
\r
79 <secondary>Ubuntu</secondary>
\r
81 <para>This section describes the installation of the latest version of the Open Service Request
\r
82 Framework (OpenSRF), a major component of the Evergreen server-side software, on
\r
83 <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
\r
84 systems. Evergreen software is integrated with and depends on the OpenSRF software
\r
86 <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
\r
87 properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
\r
88 continue with any further Evergreen installation steps
\r
89 until you have verified that OpenSRF has been successfully installed and tested.</para>
\r
91 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
\r
92 platforms. OpenSRF 1.6.3 has been tested on <systemitem class="osname">Debian Lenny (5.0)</systemitem>, <systemitem class="osname">Debian Squeeze (6.0)</systemitem>
\r
93 and <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem>,
\r
94 <systemitem class="osname">CentOS 5</systemitem>, <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem>.</para>
\r
95 <para>In the following instructions, you are asked to perform certain steps as
\r
96 either the <systemitem class="username">root</systemitem> user, the
\r
97 <systemitem class="username">opensrf</systemitem> user, or the
\r
98 <systemitem class="username">postgres</systemitem> user.</para>
\r
101 <para><systemitem class="osname">Debian</systemitem> -- To become the
\r
102 <systemitem class="username">root</systemitem> user, issue the command
\r
103 <command>su -</command> and enter the password of the
\r
104 <systemitem class="username">root</systemitem> user.</para>
\r
107 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
\r
108 <systemitem class="username">root</systemitem> user, issue the command
\r
109 <command>sudo su -</command> and enter the password of the
\r
110 <systemitem class="username">root</systemitem> user.</para>
\r
113 <para>To switch from the <systemitem class="username">root</systemitem> user to a
\r
114 different user, issue the command <command>su - USERNAME</command>. For example, to
\r
115 switch from the <systemitem class="username">root</systemitem> user to the
\r
116 <systemitem class="username">opensrf</systemitem> user, issue the command
\r
117 <command>su - opensrf</command>. Once you have become a non-root user, to become
\r
118 the <systemitem class="username">root</systemitem> user again, simply issue the command
\r
119 <command>exit</command>.</para>
\r
123 <title>Add New <systemitem class="username">opensrf</systemitem> User</title>
\r
124 <para>As the <systemitem class="username">root</systemitem> user, add the
\r
125 <systemitem class="username">opensrf</systemitem> user to the system.
\r
126 In the following example, the default shell for the
\r
127 <systemitem class="username">opensrf</systemitem> user is automatically set
\r
128 to <command>/bin/bash</command> to inherit a reasonable environment:</para>
\r
131 # as the root user:
\r
132 useradd -m -s /bin/bash opensrf
\r
133 passwd opensrf</userinput>
\r
137 <title>Download and Unpack Latest OpenSRF Version</title>
\r
139 <primary>OpenSRF</primary>
\r
140 <secondary>download</secondary>
\r
142 <para>The latest version of OpenSRF can be found here:
\r
143 <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz"></ulink> .
\r
144 As the <systemitem class="username">opensrf</systemitem> user, change to
\r
145 the directory <filename class="directory">/home/opensrf</filename> then download
\r
146 and extract OpenSRF. The new subdirectory
\r
147 <filename class="directory">/home/opensrf/OpenSRF-1.6.3</filename> will be created:</para>
\r
150 # as the opensrf user:
\r
152 wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz
\r
153 tar zxf OpenSRF-1.6.3.tar.gz</userinput>
\r
157 <title>Install Prerequisites to Build OpenSRF</title>
\r
158 <para>In this section you will install and configure a set of prerequisites that will be
\r
159 used to build OpenSRF. In a following step you will actually build the OpenSRF software
\r
160 using the <command>make</command> utility.</para>
\r
161 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
\r
162 below to build the prerequisites from the software distribution that you just downloaded
\r
163 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
\r
164 example with the keyword corresponding to the name of one of the
\r
165 <systemitem class="osname">Linux</systemitem> listed distributions.
\r
166 For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
\r
167 enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
\r
170 # as the root user:
\r
171 cd /home/opensrf/OpenSRF-1.6.3
\r
172 make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
\r
176 <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem>
\r
177 <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>
\r
180 <para><option>fedora13</option> for <systemitem class="osname">Fedora 13</systemitem>
\r
181 <indexterm><primary>Linux</primary><secondary>Fedora</secondary></indexterm></para>
\r
184 <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx
\r
185 (10.04)</systemitem></para>
\r
188 <para><option>centos</option> for <systemitem class="osname">CentOS 5</systemitem></para>
\r
191 <para><option>rhel</option> for <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem></para>
\r
194 <para>This will install a number of packages on the system that are required by OpenSRF,
\r
195 including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
\r
196 CPAN configuration prompt to allow it to automatically configure itself to download and
\r
197 install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
\r
198 it should install prerequisite modules - say <literal>Yes</literal>.</para>
\r
201 <title>Build OpenSRF</title>
\r
202 <para>In this section you will configure, build and install the OpenSRF
\r
203 components that support other Evergreen services.</para>
\r
206 <title>Configure OpenSRF</title>
\r
208 <primary>OpenSRF</primary>
\r
209 <secondary>configure</secondary>
\r
211 <para>As the <systemitem class="username">opensrf</systemitem>
\r
212 user, return to the new OpenSRF build directory and use the
\r
213 <command>configure</command> utility to prepare for the next
\r
214 step of compiling and linking the software. If you wish to
\r
215 include support for Python and Java, add the configuration
\r
216 options <option>--enable-python</option> and
\r
217 <option>--enable-java</option>, respectively:</para>
\r
220 # as the opensrf user:
\r
221 cd /home/opensrf/OpenSRF-1.6.3
\r
222 ./configure --prefix=/openils --sysconfdir=/openils/conf
\r
225 <para>This step will take several minutes to complete.</para>
\r
228 <title>Compile, Link and Install OpenSRF</title>
\r
229 <para>As the <systemitem class="username">root</systemitem>
\r
230 user, return to the new OpenSRF build directory and use the
\r
231 <command>make</command> utility to compile, link and install
\r
235 # as the root user:
\r
236 cd /home/opensrf/OpenSRF-1.6.3
\r
237 make install</userinput>
\r
239 <para>This step will take several minutes to complete.</para>
\r
242 <title>Update the System Dynamic Library Path</title>
\r
243 <para>You must update the system dynamic library path to force
\r
244 your system to recognize the newly installed libraries. As the
\r
245 <systemitem class="username">root</systemitem> user, do this by
\r
246 creating the new file
\r
247 <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
\r
248 new library path, then run the command
\r
249 <command>ldconfig</command> to automatically read the file and
\r
250 modify the system dynamic library path:</para>
\r
253 # as the root user:
\r
254 echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
\r
255 ldconfig</userinput>
\r
258 <step xml:id="serversideinstallation-definedomains">
\r
259 <title>Define Public and Private OpenSRF Domains</title>
\r
260 <para>For security purposes, OpenSRF uses Jabber domains to separate services
\r
261 into public and private realms. On a single-server system the easiest way to
\r
262 define public and private OpenSRF domains is to define separate host names by
\r
263 adding entries to the file <filename>/etc/hosts</filename>.</para>
\r
264 <para>In the following steps we will use the example domains
\r
265 <systemitem class="domainname">public.localhost</systemitem> for the public
\r
266 domain and <systemitem class="domainname">private.localhost</systemitem>
\r
267 for the private domain. In an upcoming step, you will configure two special
\r
268 <systemitem class="service">ejabberd</systemitem> users
\r
269 to handle communications for these two domains.</para>
\r
270 <para>As the <systemitem class="username">root</systemitem> user, edit the file
\r
271 <filename>/etc/hosts</filename> and add the following example domains:</para>
\r
273 <primary>Jabber</primary>
\r
277 # as the root user:
\r
278 127.0.1.2 public.localhost public
\r
279 127.0.1.3 private.localhost private</userinput>
\r
283 <title>Change File Ownerships</title>
\r
284 <para>Finally, as the <systemitem class="username">root</systemitem>
\r
285 user, change the ownership of all files installed in the
\r
286 directory <filename class="directory">/openils</filename> to the
\r
287 user <systemitem class="username">opensrf</systemitem>:</para>
\r
290 # as the root user:
\r
291 chown -R opensrf:opensrf /openils</userinput>
\r
296 <step xml:id="stop-ejabberd-service">
\r
297 <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
\r
299 <primary>ejabberd</primary>
\r
301 <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
\r
302 you must stop that service. As the <systemitem class="username">root</systemitem> user,
\r
303 execute the following command to stop the service:</para>
\r
306 # as the root user:
\r
307 /etc/init.d/ejabberd stop</userinput>
\r
309 <para>If <systemitem class="service">ejabberd</systemitem> reports that it
\r
310 is already stopped, there may have been a problem when it started back
\r
311 in the installation step. If there are any remaining daemon processes such as
\r
312 <systemitem class="daemon">beam</systemitem> or
\r
313 <systemitem class="daemon">epmd</systemitem>
\r
314 you may need to perform the following commands to kill them:</para>
\r
317 # as the root user:
\r
319 killall beam; killall beam.smp
\r
320 rm /var/lib/ejabberd/*
\r
321 echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
\r
325 <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
\r
326 <para>You must make several configuration changes for the
\r
327 <systemitem class="service">ejabberd</systemitem> service before
\r
328 it is started again.
\r
329 As the <systemitem class="username">root</systemitem> user, edit the file
\r
330 <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
\r
333 <para>Change the line:</para>
\r
334 <literal>{hosts, ["localhost"]}.</literal>
\r
335 <para>to instead read:</para>
\r
336 <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
\r
340 <para>Change the line:</para>
\r
341 <literal>{max_user_sessions, 10}</literal>
\r
342 <para>to instead read:</para>
\r
343 <literal>{max_user_sessions, 10000}</literal>
\r
345 <para>If the line looks something like this:</para>
\r
346 <literal>{access, max_user_sessions, [{10, all}]}</literal>
\r
347 <para>then change it to instead read:</para>
\r
348 <literal>{access, max_user_sessions, [{10000, all}]}</literal>
\r
351 <para>Change all three occurrences of:</para>
\r
352 <literal>max_stanza_size</literal>
\r
353 <para>to instead read:</para>
\r
354 <literal>2000000</literal>
\r
357 <para>Change both occurrences of:</para>
\r
358 <literal>maxrate</literal>
\r
359 <para>to instead read:</para>
\r
360 <literal>500000</literal>
\r
363 <para>Comment out the line:</para>
\r
364 <literal>{mod_offline, []}</literal>
\r
365 <para>by placing two <literal>%</literal> comment signs in front
\r
366 so it instead reads:</para>
\r
367 <literal>%%{mod_offline, []}</literal>
\r
371 <step xml:id="serversideinstallation-opensrf-continued">
\r
372 <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
\r
373 <para>As the <systemitem class="username">root</systemitem> user, restart the
\r
374 <systemitem class="service">ejabberd</systemitem> service to test the
\r
375 configuration changes and to register your users:</para>
\r
378 # as the root user:
\r
379 /etc/init.d/ejabberd start</userinput>
\r
383 <title>Register <systemitem class="username">router</systemitem> and
\r
384 <systemitem class="username">opensrf</systemitem> as
\r
385 <systemitem class="service">ejabberd</systemitem> users</title>
\r
386 <para>The two <systemitem class="service">ejabberd</systemitem> users
\r
387 <systemitem class="username">router</systemitem> and
\r
388 <systemitem class="username">opensrf</systemitem> must be registered
\r
389 and configured to manage OpenSRF router service and communications
\r
390 for the two domains <literal>public.localhost</literal> and
\r
391 <literal>private.localhost</literal> that you added to the file
\r
392 <filename>/etc/hosts</filename> in a previous step
\r
393 (see <xref linkend="serversideinstallation-definedomains"/>).
\r
394 The users include:</para>
\r
397 <para>the <systemitem class="username">router</systemitem> user,
\r
398 to whom all requests to connect to an OpenSRF service will be
\r
402 <para>the <systemitem class="username">opensrf</systemitem> user,
\r
403 which clients use to connect to OpenSRF services (you may name
\r
404 the user anything you like, but we use
\r
405 <literal>opensrf</literal> in these examples)</para>
\r
408 <para>As the <systemitem class="username">root</systemitem> user, execute the
\r
409 <command>ejabberdctl</command> utility as shown below to register and create passwords
\r
410 for the users <systemitem class="username">router</systemitem> and
\r
411 <systemitem class="username">opensrf</systemitem> on each domain (remember to replace
\r
412 <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
\r
415 # as the root user:
\r
416 # Note: the syntax for registering a user with ejabberdctl is:
\r
417 # ejabberdctl register USER DOMAIN PASSWORD
\r
418 ejabberdctl register router private.localhost NEWPASSWORD
\r
419 ejabberdctl register router public.localhost NEWPASSWORD
\r
420 ejabberdctl register opensrf private.localhost NEWPASSWORD
\r
421 ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
\r
423 <para>Note that the users <systemitem class="username">router</systemitem> and
\r
424 <systemitem class="username">opensrf</systemitem> and their respective passwords
\r
425 will be used again in <xref linkend="serversideinstallation-passwords"/> when
\r
426 we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para>
\r
428 <step xml:id="serversideinstallation-opensrf-createconfig">
\r
429 <title>Create OpenSRF configuration files</title>
\r
430 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
431 execute the following commands to create the new configuration files
\r
432 <filename>/openils/conf/opensrf_core.xml</filename> and
\r
433 <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
\r
436 # as the opensrf user:
\r
438 cp opensrf.xml.example opensrf.xml
\r
439 cp opensrf_core.xml.example opensrf_core.xml</userinput>
\r
442 <step xml:id="serversideinstallation-passwords">
\r
443 <title>Update usernames and passwords in the OpenSRF configuration file</title>
\r
444 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
445 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
\r
446 and update the usernames and passwords to match the values shown in the
\r
447 following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
\r
448 shows common XPath syntax to indicate the approximate position within the XML
\r
449 file that needs changes. The right-hand side of the table shows the replacement
\r
451 <table xml:id="serversideinstallation-xpath-table-1">
\r
452 <?dbfo keep-together="always" ?>
\r
453 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
\r
454 <tgroup align="left" cols="2" colsep="1" rowsep="1">
\r
455 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
\r
456 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
\r
459 <entry>XPath location</entry>
\r
460 <entry>Value</entry>
\r
465 <entry>/config/opensrf/username</entry>
\r
467 <systemitem class="username">opensrf</systemitem>
\r
471 <entry>/config/opensrf/passwd </entry>
\r
472 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
474 <systemitem class="username">opensrf</systemitem> user
\r
478 <entry>/config/gateway/username</entry>
\r
480 <systemitem class="username">opensrf</systemitem>
\r
484 <entry>/config/gateway/passwd</entry>
\r
485 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
487 <systemitem class="username">opensrf</systemitem> user
\r
491 <entry>/config/routers/router/transport/username,
\r
492 first entry where server == public.localhost</entry>
\r
494 <systemitem class="username">router</systemitem>
\r
498 <entry>/config/routers/router/transport/password,
\r
499 first entry where server == public.localhost</entry>
\r
500 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
502 <systemitem class="username">router</systemitem> user
\r
506 <entry>/config/routers/router/transport/username,
\r
507 second entry where server == private.localhost</entry>
\r
509 <systemitem class="username">router</systemitem>
\r
513 <entry>/config/routers/router/transport/password,
\r
514 second entry where server == private.localhost</entry>
\r
515 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
517 <systemitem class="username">router</systemitem> user
\r
523 <para>You may also need to modify the file to specify the domains from which
\r
524 <systemitem class="service">OpenSRF</systemitem> will accept connections,
\r
525 and to which it will make connections.
\r
526 If you are installing <application>OpenSRF</application> on a single server
\r
527 and using the <systemitem class="domainname">private.localhost</systemitem> and
\r
528 <systemitem class="domainname">public.localhost</systemitem> domains,
\r
529 these will already be set to the correct values. Otherwise, search and replace
\r
530 to match values for your own systems.</para>
\r
533 <title>Set location of the persistent database</title>
\r
534 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
535 file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the
\r
536 element <literal>dbfile</literal> (near the end of the file) to set the
\r
537 location of the persistent database. Change the default line:</para>
\r
538 <literal>/openils/var/persist.db</literal>
\r
539 <para>to instead read:</para>
\r
540 <literal>/tmp/persist.db</literal>
\r
541 <para>Following is a sample modification of that portion of the file:</para>
\r
542 <programlisting language="xml"><![CDATA[
\r
543 <!-- Example of an app-specific setting override -->
\r
546 <dbfile>/tmp/persist.db</dbfile>
\r
549 ]]></programlisting>
\r
551 <step xml:id="serversideinstallation-srfsh">
\r
552 <title>Create configuration files for users needing <command>srfsh</command></title>
\r
553 <para>In this section you will set up a special configuration file for each user
\r
554 who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
\r
555 shell</emphasis>) utility.</para>
\r
557 <primary>srfsh</primary>
\r
559 <para>The software installation will automatically create the utility
\r
560 <command>srfsh</command> (surf shell), a command line diagnostic tool for
\r
561 testing and interacting with <application>OpenSRF</application>. It will be used
\r
562 in a future step to complete and test the Evergreen installation. See
\r
563 <xref linkend="serversideinstallation-testing"/> for further information.</para>
\r
564 <para>As the <systemitem class="username">root</systemitem> user, copy the
\r
565 sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
\r
566 to the home directory of each user who will use <command>srfsh</command>.
\r
567 For instance, do the following for the
\r
568 <systemitem class="username">opensrf</systemitem> user:</para>
\r
571 # as the root user:
\r
572 cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>
\r
574 <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
\r
575 following changes:</para>
\r
578 <para>Modify <literal>domain</literal> to be the router hostname
\r
579 (following our domain examples,
\r
580 <systemitem class="domainname">private.localhost</systemitem> will give
\r
581 <command>srfsh</command> access to all OpenSRF services, while
\r
582 <systemitem class="domainname">public.localhost</systemitem>
\r
583 will only allow access to those OpenSRF services that are
\r
584 publicly exposed).</para>
\r
587 <para>Modify <literal>username</literal> and
\r
588 <literal>password</literal> to match the
\r
589 <literal>opensrf</literal> Jabber user for the chosen
\r
593 <para>Modify <literal>logfile</literal> to be the full path for
\r
594 a log file to which the user has write access</para>
\r
597 <para>Modify <literal>loglevel</literal> as needed for testing</para>
\r
600 <para>Change the owner of the file to match the owner of the home directory</para>
\r
603 <para>Following is a sample of the file:</para>
\r
604 <programlisting language="xml"><![CDATA[
\r
605 <?xml version="1.0"?>
\r
606 <!-- This file follows the standard bootstrap config file layout -->
\r
607 <!-- found in opensrf_core.xml -->
\r
609 <router_name>router</router_name>
\r
610 <domain>private.localhost</domain>
\r
611 <username>opensrf</username>
\r
612 <passwd>SOMEPASSWORD</passwd>
\r
614 <logfile>/tmp/srfsh.log</logfile>
\r
615 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
\r
616 <loglevel>4</loglevel>
\r
618 ]]></programlisting>
\r
621 <title>Modify the environmental variable <envar>PATH</envar> for the
\r
622 <systemitem class="username">opensrf</systemitem> user</title>
\r
623 <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
\r
624 environmental variable <envar>PATH</envar> by adding a new file path to the
\r
625 <systemitem class="username">opensrf</systemitem> user's shell configuration
\r
626 file <filename>~/.bashrc</filename>:</para>
\r
629 # as the opensrf user:
\r
630 echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
\r
634 <title>Start OpenSRF</title>
\r
635 <para>As the <systemitem class="username">root</systemitem> user, start the
\r
636 <systemitem class="service">ejabberd</systemitem> and
\r
637 <systemitem class="service">memcached</systemitem> services:</para>
\r
640 # as the root user:
\r
641 /etc/init.d/ejabberd start
\r
642 /etc/init.d/memcached start</userinput>
\r
644 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
645 start OpenSRF as follows:</para>
\r
648 # as the opensrf user:
\r
649 osrf_ctl.sh -l -a start_all</userinput>
\r
651 <para>The flag <option>-l</option> forces Evergreen to use
\r
652 <systemitem class="domainname">localhost</systemitem> (your current system)
\r
653 as the hostname. The flag <option>-a start_all</option> starts the other
\r
654 OpenSRF <systemitem class="service">router</systemitem> ,
\r
655 <systemitem class="service">Perl</systemitem> , and
\r
656 <systemitem class="service">C</systemitem> services.</para>
\r
659 <para>You can also start Evergreen without the
\r
660 <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
\r
661 utility must know the fully qualified domain name for the system
\r
662 on which it will execute. That hostname was probably specified
\r
663 in the configuration file <filename>opensrf.xml</filename> which
\r
664 you configured in a previous step.</para>
\r
667 <para>If you receive an error message similar to
\r
668 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
\r
669 environment variable <envar>PATH</envar> does not include the
\r
670 directory <filename class="directory">/openils/bin</filename>.
\r
671 As the <systemitem class="username">opensrf</systemitem> user,
\r
672 edit the configuration file <filename>~/.bashrc</filename> and
\r
673 add the following line:
\r
674 <literal>export PATH=$PATH:/openils/bin</literal></para>
\r
679 <title>Test connections to OpenSRF</title>
\r
680 <para>Once you have installed and started OpenSRF, as the
\r
681 <systemitem class="username">root</systemitem> user, test your connection to
\r
682 <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
\r
683 utility and trying to call the <command>add</command> method on the OpenSRF
\r
684 <systemitem class="service">math</systemitem> service:</para>
\r
687 # as the root user:
\r
688 /openils/bin/srfsh</userinput>
\r
690 srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
\r
693 ------------------------------------
\r
694 Request Completed Successfully
\r
695 Request Time in seconds: 0.007519
\r
696 ------------------------------------</computeroutput>
\r
698 <para>For other <command>srfsh</command> commands, type in
\r
699 <userinput>help</userinput> at the prompt.</para>
\r
702 <title>Stop OpenSRF</title>
\r
703 <para>After OpenSRF has started, you can stop it at any time by using the
\r
704 <command>osrf_ctl.sh</command> again. As the
\r
705 <systemitem class="username">opensrf</systemitem>
\r
706 user, stop OpenSRF as follows:</para>
\r
709 # as the opensrf user:
\r
710 osrf_ctl.sh -l -a stop_all</userinput>
\r
715 <section xml:id="serversideinstallation-ubuntudebian">
\r
716 <title>Installing Evergreen 2.0 On <systemitem class="osname">Ubuntu</systemitem> or
\r
717 <systemitem class="osname">Debian</systemitem></title>
\r
719 <primary>Linux</primary>
\r
720 <secondary>Debian</secondary>
\r
723 <primary>Linux</primary>
\r
724 <secondary>Ubuntu</secondary>
\r
726 <para>This section outlines the installation process for the latest stable version of
\r
728 <para>In this section you will download, unpack, install, configure and test the Evergreen
\r
729 system, including the Evergreen server and the PostgreSQL database system. You will make several
\r
730 configuration changes and adjustments to the software, including updates to configure the system
\r
731 for your own locale, and some updates needed to work around a few known issues.</para>
\r
733 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
\r
734 architectures. There may be differences between the Desktop and Server editions of
\r
735 <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
\r
737 <para>In the following instructions, you are asked to perform certain steps as
\r
738 either the <systemitem class="username">root</systemitem> user, the
\r
739 <systemitem class="username">opensrf</systemitem> user, or the
\r
740 <systemitem class="username">postgres</systemitem> user.</para>
\r
743 <para><systemitem class="osname">Debian</systemitem> -- To become the
\r
744 <systemitem class="username">root</systemitem> user, issue the command
\r
745 <command>su -</command> and enter the password of the
\r
746 <systemitem class="username">root</systemitem> user.</para>
\r
749 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
\r
750 <systemitem class="username">root</systemitem> user, issue the command
\r
751 <command>sudo su -</command> and enter the password of the
\r
752 <systemitem class="username">root</systemitem> user.</para>
\r
755 <para>To switch from the <systemitem class="username">root</systemitem> user to a
\r
756 different user, issue the command <command>su - USERNAME</command>. For example, to
\r
757 switch from the <systemitem class="username">root</systemitem> user to the
\r
758 <systemitem class="username">opensrf</systemitem> user, issue the command
\r
759 <command>su - opensrf</command>. Once you have become a non-root user, to become the
\r
760 <systemitem class="username">root</systemitem> user again, simply issue the command
\r
761 <command>exit</command>.</para>
\r
765 <title>Install OpenSRF</title>
\r
766 <para>Evergreen software is integrated with and depends on the Open Service
\r
767 Request Framework (OpenSRF) software system. For further information on
\r
768 installing, configuring and testing OpenSRF, see
\r
769 <xref linkend="serversideinstallation-opensrf"/>.</para>
\r
770 <para>Follow the steps outlined in that section and run the specified tests to
\r
771 ensure that OpenSRF is properly installed and configured. Do
\r
772 <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
\r
773 any further Evergreen installation steps until you have verified that OpenSRF
\r
774 has been successfully installed and tested.</para>
\r
777 <title>Download and Unpack Latest Evergreen Version</title>
\r
778 <para>The latest version of Evergreen can be found here:
\r
779 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
\r
780 As the <systemitem class="username">opensrf</systemitem> user, change to
\r
781 the directory <filename class="directory">/home/opensrf</filename> then download
\r
782 and extract Evergreen. The new subdirectory
\r
783 <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename> will be created:</para>
\r
786 # as the opensrf user:
\r
788 wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
\r
789 tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
\r
792 <step xml:id="serversideinstallation-installprereq">
\r
793 <title>Install Prerequisites to Build Evergreen</title>
\r
794 <para>In this section you will install and configure a set of prerequisites that will be
\r
795 used later in <xref linkend="serversideinstallation-configure"/> and
\r
796 <xref linkend="serversideinstallation-compile"/> to build the Evergreen software
\r
797 using the <command>make</command> utility.</para>
\r
798 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
\r
799 below to build the prerequisites from the software distribution that you just downloaded
\r
800 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
\r
801 example with the keyword corresponding to the name of one of the
\r
802 <systemitem class="osname">Linux</systemitem> distributions listed in the following
\r
804 For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
\r
805 enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
\r
806 ubuntu-lucid</command>.</para>
\r
809 # as the root user:
\r
810 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
811 make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
\r
816 <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>
\r
820 <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx
\r
821 (10.04)</systemitem></para>
\r
825 <step performance="optional" xml:id="serversideinstallation-postgresql-default">
\r
826 <title>(OPTIONAL) Install the PostgreSQL Server</title>
\r
828 <primary>databases</primary>
\r
829 <secondary>PostgreSQL</secondary>
\r
831 <para>Since the PostgreSQL server is usually a standalone server in multi-server
\r
832 production systems, the prerequisite installer Makefile in the previous section
\r
833 (see <xref linkend="serversideinstallation-installprereq"/>)
\r
834 does not automatically install PostgreSQL. You must install the PostgreSQL server
\r
835 yourself, either on the same system as Evergreen itself or on another system.
\r
836 If your PostgreSQL server is on a different system, just skip this step.
\r
837 If your PostgreSQL server will be on the same system as your Evergreen
\r
838 software, you can install the required PostgreSQL server packages as described
\r
839 in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official
\r
840 web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
\r
841 for more information.</para>
\r
843 <para>PostgreSQL version 8.4 is the minimum supported version to work
\r
844 with Evergreen 2.0. If you have an older version of PostgreSQL,
\r
845 you should upgrade before installing Evergreen. To find your current version
\r
846 of PostgreSQL, as the <systemitem class="username">postgres</systemitem>
\r
847 user execute the command <command>psql</command>, then type
\r
848 <userinput>SELECT version();</userinput> to get detailed information
\r
849 about your version of PostgreSQL.</para>
\r
852 <step performance="optional">
\r
853 <title>Install Perl Modules on PostgreSQL Server</title>
\r
854 <para>If PostgreSQL is running on the same system as your Evergreen software,
\r
855 then the Perl modules will automatically be available. Just skip this step.
\r
856 Otherwise, continue if your PostgreSQL server is running on another system.</para>
\r
857 <para>You will need to install several Perl modules on the other system. As the
\r
858 <systemitem class="username">root</systemitem> user install the following Perl
\r
860 <para>as the root user, ensure the gcc compiler is installed:</para>
\r
862 <userinput>aptitude install gcc libxml-libxml-perl libxml-libxslt-perl</userinput>
\r
864 <para>then install the Perl modules:</para>
\r
866 <userinput>perl -MCPAN -e shell</userinput>
\r
867 <prompt>cpan></prompt> <userinput>Business::ISBN</userinput>
\r
868 <prompt>cpan></prompt> <userinput>install JSON::XS</userinput>
\r
869 <prompt>cpan></prompt> <userinput>Library::CallNumber::LC</userinput>
\r
870 <prompt>cpan></prompt> <userinput>install MARC::Record</userinput>
\r
871 <prompt>cpan></prompt> <userinput>install MARC::File::XML</userinput>
\r
872 <prompt>cpan></prompt> <userinput>cpan UUID::Tiny</userinput>
\r
874 <para>For more information on installing Perl Modules vist the official
\r
875 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
\r
877 <primary>Perl</primary>
\r
878 <secondary>CPAN</secondary>
\r
882 <title>Update the System Dynamic Library Path</title>
\r
883 <para>You must update the system dynamic library path to force your system to recognize
\r
884 the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
\r
885 do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
\r
886 containing a new library path, then run the command <command>ldconfig</command> to
\r
887 automatically read the file and modify the system dynamic library path:</para>
\r
890 # as the root user:
\r
891 echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
\r
892 echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
\r
893 ldconfig</userinput>
\r
896 <step performance="optional">
\r
897 <title>Restart the PostgreSQL Server</title>
\r
898 <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
\r
899 the <systemitem class="username">root</systemitem> user you must restart
\r
900 PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
\r
901 running on another system, you may skip this step.
\r
902 As the <systemitem class="username">opensrf</systemitem> user,
\r
903 execute the following command (remember to replace
\r
904 <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
\r
905 for example <literal>8.4</literal>):</para>
\r
908 # as the opensrf user:
\r
909 /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
\r
912 <step xml:id="serversideinstallation-configure">
\r
913 <title>Configure Evergreen</title>
\r
914 <para>In this step you will use the <command>configure</command> and
\r
915 <command>make</command> utilities to configure Evergreen so it can be compiled
\r
916 and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
\r
917 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
\r
918 the Evergreen build directory and execute these commands:</para>
\r
921 # as the opensrf user:
\r
922 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
923 ./configure --prefix=/openils --sysconfdir=/openils/conf
\r
927 <step xml:id="serversideinstallation-compile">
\r
928 <title>Compile, Link and Install Evergreen</title>
\r
929 <para>In this step you will actually compile, link and install Evergreen and the
\r
930 default Evergreen Staff Client.</para>
\r
931 <para>As the <systemitem class="username">root</systemitem> user, return to the
\r
932 Evergreen build directory and use the <command>make</command> utility as shown below:</para>
\r
935 # as the root user:
\r
936 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
937 make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>
\r
939 <para>The Staff Client will also be automatically built, but you must remember
\r
940 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
\r
941 Staff Client you will use to connect to the Evergreen server.</para>
\r
942 <para>The above commands will create a new subdirectory
\r
943 <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename>
\r
944 containing the Staff Client.</para>
\r
945 <para>To complete the Staff Client installation, as the
\r
946 <systemitem class="username">root</systemitem> user execute the following commands to
\r
947 create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client
\r
948 directory <filename class="directory">/openils/var/web/xul</filename> that points to the
\r
949 subdirectory <filename class="directory">/server</filename> of the new Staff Client
\r
953 # as the root user:
\r
954 cd /openils/var/web/xul
\r
955 ln -sf rel_2_0_4/server server</userinput>
\r
959 <title>Copy the OpenSRF Configuration Files</title>
\r
960 <para>In this step you will replace some OpenSRF configuration files that you set up in
\r
961 <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
\r
962 tested OpenSRF.</para>
\r
963 <para>You must copy several example OpenSRF configuration files into place after first
\r
964 creating backup copies for troubleshooting purposes, then change all the file ownerships
\r
965 to <systemitem class="username">opensrf</systemitem>.
\r
966 As the <systemitem class="username">root</systemitem> user, execute the following
\r
970 # as the root user:
\r
972 cp opensrf.xml opensrf.xml.BAK
\r
973 cp opensrf_core.xml opensrf_core.xml.BAK
\r
974 cp opensrf.xml.example opensrf.xml
\r
975 cp opensrf_core.xml.example opensrf_core.xml
\r
976 cp oils_web.xml.example oils_web.xml
\r
977 chown -R opensrf:opensrf /openils/</userinput>
\r
981 <title>Create and Configure PostgreSQL Database</title>
\r
983 <primary>databases</primary>
\r
984 <secondary>PostgreSQL</secondary>
\r
986 <para>In this step you will create the Evergreen database. In the commands
\r
987 below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
\r
988 repository to match your PostgreSQL server
\r
989 layout. For example, if you built PostgreSQL from source the path would be
\r
990 <filename class="directory">/usr/local/share/contrib</filename> , and if you
\r
991 installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
\r
993 <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
\r
997 <emphasis role="bold">Create and configure the database</emphasis>
\r
999 <para>As the <systemitem class="username">postgres</systemitem>
\r
1000 user on the PostgreSQL system create the PostgreSQL database,
\r
1001 then set some internal paths:</para>
\r
1004 # as the postgres user:
\r
1005 createdb evergreen -E UTF8 -T template0
\r
1006 createlang plperl evergreen
\r
1007 createlang plperlu evergreen
\r
1008 createlang plpgsql evergreen</userinput>
\r
1010 <para>Continue as the <systemitem class="username">postgres</systemitem> user
\r
1011 and execute the SQL scripts as shown below (remember to adjust the paths as needed,
\r
1012 where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL
\r
1013 version, for example <literal>8.4</literal>).</para>
\r
1016 # as the postgres user:
\r
1017 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
\r
1018 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
\r
1019 psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
\r
1022 <step xml:id="serversideinstallation-postgresqlcreateuser">
\r
1023 <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
\r
1024 <para>As the <systemitem class="username">postgres</systemitem>
\r
1025 user on the PostgreSQL system, create a new PostgreSQL user
\r
1026 named <systemitem class="username">evergreen</systemitem> and
\r
1027 assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
\r
1028 with an appropriate new password):</para>
\r
1031 # as the postgres user:
\r
1032 createuser -P -s evergreen</userinput>
\r
1034 Enter password for new role: <userinput>NEWPASSWORD</userinput>
\r
1035 Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
\r
1039 <title>Create database schema</title>
\r
1040 <para>In this step you will create the database schema and configure your
\r
1041 system with the corresponding database authentication details for the
\r
1042 <emphasis>evergreen</emphasis> database user that you just created in
\r
1043 <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
\r
1044 <para>As the <systemitem class="username">root</systemitem> user, enter
\r
1045 the following commands and replace <emphasis>HOSTNAME, PORT,
\r
1046 PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
\r
1049 <userinput>cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1050 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
\r
1051 --service all --create-schema --create-offline \
\r
1052 --hostname HOSTNAME --port PORT \
\r
1053 --user evergreen --password PASSWORD \
\r
1054 --database DATABASENAME --admin-user ADMIN-USER \
\r
1055 --admin-pass ADMIN-PASSWORD </userinput>
\r
1057 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
\r
1058 <emphasis role="bold">localhost</emphasis> and
\r
1059 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
\r
1060 Of course, values for <emphasis>PASSWORD</emphasis> and
\r
1061 <emphasis>DATABASENAME</emphasis> must match the values you used in
\r
1062 <xref linkend="serversideinstallation-postgresqlcreateuser"/>. The <option>admin-user</option> and <option>admin-pass</option> options will
\r
1063 specify the Evergreen administrator account's username and password. This was
\r
1064 changed for security reasons, it was previously admin/open-ils</para>
\r
1065 <para>As the command executes, you may see warnings similar to:
\r
1066 <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
\r
1067 you may see one warning per schema) but they can be safely ignored.</para>
\r
1068 <note>If you are entering the above command on a single line, do not
\r
1069 include the <literal>\</literal> (backslash) characters. If you are using
\r
1070 the <command>bash</command> shell, these should only be used at the end of
\r
1071 a line at a <command>bash</command> prompt to indicate that the command is
\r
1072 continued on the next line.</note>
\r
1077 <title>Configure the Apache web server</title>
\r
1079 <primary>web server</primary>
\r
1080 <secondary>Apache</secondary>
\r
1082 <para>In this step you will configure the Apache web server to support Evergreen
\r
1084 <para>First, you must enable some built-in Apache modules and install some
\r
1085 additional Apache configuration files. Then you will create a new Security
\r
1086 Certificate. Finally, you must make several changes to the Apache configuration
\r
1090 <title>Enable the required Apache Modules</title>
\r
1091 <para>As the <systemitem class="username">root</systemitem>
\r
1092 user, enable some modules in the Apache server, then copy the
\r
1093 new configuration files to the Apache server directories:</para>
\r
1095 <primary>Apache modules</primary>
\r
1099 # as the root user:
\r
1100 a2enmod ssl # enable mod_ssl
\r
1101 a2enmod rewrite # enable mod_rewrite
\r
1102 a2enmod expires # enable mod_expires</userinput>
\r
1104 <para>As the commands execute, you may see warnings similar to:
\r
1105 <literal>Module SOMEMODULE already enabled</literal> but you can
\r
1106 safely ignore them.</para>
\r
1109 <title>Copy Apache configuration files</title>
\r
1110 <para>You must copy the Apache configuration files from the
\r
1111 Evergreen installation directory to the Apache directory. As the
\r
1112 <systemitem class="username">root</systemitem> user, perform the
\r
1113 following commands:</para>
\r
1116 # as the root user:
\r
1117 cd /home/opensrf/Evergreen-ILS-2.0.4
\r
1118 cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/
\r
1119 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
\r
1120 cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
\r
1123 <step xml:id="serversideinstallation-createsslcertificate">
\r
1124 <title>Create a Security Certificate</title>
\r
1125 <para>In this step you will create a new Security Certificate (SSL Key)
\r
1126 for the Apache server using the <command>openssl</command> command. For a
\r
1127 public production server you must configure or purchase a signed SSL
\r
1128 certificate, but for now you can just use a self-signed certificate and
\r
1129 accept the warnings in the Staff Client and browser during testing and
\r
1130 development. As the <systemitem class="username">root</systemitem> user,
\r
1131 perform the following commands:</para>
\r
1134 # as the root user:
\r
1135 mkdir /etc/apache2/ssl
\r
1136 cd /etc/apache2/ssl
\r
1137 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
\r
1139 <para>You will be prompted for several items of information; enter
\r
1140 the appropriate information for each item. The new files
\r
1141 <filename>server.crt</filename> and <filename>server.key</filename> will
\r
1142 be created in the directory
\r
1143 <filename class="directory">/etc/apache2/ssl</filename> .</para>
\r
1144 <note>This step generates a self-signed SSL certificate. You must install
\r
1145 a proper SSL certificate for a public production system to avoid warning
\r
1146 messages when users login to their account through the OPAC or when staff
\r
1147 login through the Staff Client. For further information on
\r
1148 installing a proper SSL certificate, see
\r
1149 <xref linkend="serversideinstallation-ssl"/>.</note>
\r
1151 <step xml:id="serversideinstallation-modify-apache">
\r
1152 <title>Update Apache configuration file</title>
\r
1153 <para>You must make several changes to the new Apache
\r
1154 configuration file
\r
1155 <filename>/etc/apache2/sites-available/eg.conf</filename> .
\r
1156 As the <systemitem class="username">root</systemitem> user,
\r
1157 edit the file and make the following changes:</para>
\r
1160 <para>In the section
\r
1161 <literal><Directory "/openils/var/cgi-bin"></literal>
\r
1162 replace the line:</para>
\r
1163 <literal>Allow from 10.0.0.0/8</literal>
\r
1164 <para>with the line:</para>
\r
1165 <literal>Allow from all</literal>
\r
1166 <warning>This change allows access to your configuration
\r
1167 CGI scripts from any workstation on any network. This is
\r
1168 only a temporary change to expedite testing and should be
\r
1169 removed after you have finished and successfully tested
\r
1170 the Evergreen installation. See
\r
1171 <xref linkend="serversideinstallation-postinstallation"/>
\r
1172 for further details on removing this change after the
\r
1173 Evergreen installation is complete.
\r
1177 <para>Comment out the line:</para>
\r
1178 <literal>Listen 443</literal>
\r
1179 <para>since it conflicts with the same declaration in
\r
1180 the configuration file:</para>
\r
1181 <para><filename>/etc/apache2/ports.conf</filename>.</para>
\r
1184 <para>The following updates are needed to allow the logs
\r
1185 to function properly, but it may break other Apache
\r
1186 applications on your server:</para>
\r
1188 <para>Edit the Apache configuration file and change the lines:</para>
\r
1190 <userinput>export APACHE_RUN_USER=www-data</userinput>
\r
1191 <userinput>export APACHE_RUN_GROUP=www-data</userinput>
\r
1193 <para>to instead read:</para>
\r
1196 export APACHE_RUN_USER=opensrf
\r
1197 export APACHE_RUN_GROUP=opensrf</userinput>
\r
1202 <systemitem class="username">root</systemitem> user,
\r
1203 edit the Apache configuration file
\r
1204 <filename>/etc/apache2/apache2.conf</filename> and
\r
1205 modify the value for <literal>KeepAliveTimeout</literal>
\r
1206 and <literal>MaxKeepAliveRequests</literal> to match
\r
1207 the following:</para>
\r
1210 KeepAliveTimeout 1
\r
1211 MaxKeepAliveRequests 100</userinput>
\r
1215 <para>Further configuration changes to Apache may be
\r
1216 necessary for busy systems. These changes increase the
\r
1217 number of Apache server processes that are started to
\r
1218 support additional browser connections.</para>
\r
1220 <systemitem class="username">root</systemitem> user,
\r
1221 edit the Apache configuration file
\r
1222 <filename>/etc/apache2/apache2.conf</filename>, locate
\r
1223 and modify the section related to <emphasis>prefork
\r
1224 configuration</emphasis> to suit the load on your
\r
1226 <programlisting language="xml"><![CDATA[
\r
1227 <IfModule mpm_prefork_module>
\r
1230 MaxSpareServers 15
\r
1232 MaxRequestsPerChild 10000
\r
1234 ]]></programlisting>
\r
1239 <title>Enable the Evergreen web site</title>
\r
1240 <para>Finally, you must enable the Evergreen web site. As the
\r
1241 <systemitem class="username">root</systemitem> user, execute the
\r
1242 following Apache configuration commands to disable the default
\r
1243 <emphasis>It Works</emphasis> web page and enable the Evergreen
\r
1244 web site, and then restart the Apache server:</para>
\r
1247 # as the root user:
\r
1248 # disable/enable web sites
\r
1251 # restart the server
\r
1252 /etc/init.d/apache2 reload</userinput>
\r
1257 <step xml:id="serversideinstallation-opensrf-config">
\r
1258 <title>Update the OpenSRF Configuration File</title>
\r
1259 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
\r
1260 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
\r
1261 to update the Jabber usernames and passwords, and to specify the domain from
\r
1262 which we will accept and to which we will make connections.</para>
\r
1263 <para>If you are installing Evergreen on a single server and using the
\r
1264 <systemitem class="domainname">private.localhost</systemitem> /
\r
1265 <systemitem class="domainname">public.localhost</systemitem> domains,
\r
1266 these will already be set to the correct values. Otherwise, search and replace
\r
1267 to match your customized values.</para>
\r
1268 <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
\r
1269 shows common XPath syntax to indicate the approximate position within the XML
\r
1270 file that needs changes. The right-hand side of the table shows the replacement
\r
1272 <table xml:id="serversideinstallation-xpath-table-2">
\r
1273 <?dbfo keep-together="always" ?>
\r
1274 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
\r
1275 <tgroup align="left" cols="2" colsep="1" rowsep="1">
\r
1276 <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
\r
1277 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
\r
1280 <entry>XPath location</entry>
\r
1281 <entry>Value</entry>
\r
1286 <entry>/config/opensrf/username</entry>
\r
1288 <systemitem class="username">opensrf</systemitem>
\r
1292 <entry>/config/opensrf/passwd </entry>
\r
1293 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
1295 <systemitem class="username">opensrf</systemitem> user
\r
1299 <entry>/config/gateway/username</entry>
\r
1301 <systemitem class="username">opensrf</systemitem>
\r
1305 <entry>/config/gateway/passwd</entry>
\r
1306 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
1308 <systemitem class="username">opensrf</systemitem> user
\r
1312 <entry>/config/routers/router/transport/username,
\r
1313 first entry where server == public.localhost</entry>
\r
1315 <systemitem class="username">router</systemitem>
\r
1319 <entry>/config/routers/router/transport/password,
\r
1320 first entry where server == public.localhost</entry>
\r
1321 <entry><systemitem class="domainname">public.localhost</systemitem>
\r
1323 <systemitem class="username">router</systemitem> user
\r
1327 <entry>/config/routers/router/transport/username,
\r
1328 second entry where server == private.localhost</entry>
\r
1330 <systemitem class="username">router</systemitem>
\r
1334 <entry>/config/routers/router/transport/password,
\r
1335 second entry where server == private.localhost</entry>
\r
1336 <entry><systemitem class="domainname">private.localhost</systemitem>
\r
1338 <systemitem class="username">router</systemitem> user
\r
1345 <step performance="optional">
\r
1346 <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>
\r
1347 <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the
\r
1348 software installation automatically created a utility named <command>srfsh</command> (surf
\r
1349 shell). This is a command line diagnostic tool for testing and interacting with
\r
1350 OpenSRF. It will be used in a future step to complete and test the Evergreen installation.
\r
1351 Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration
\r
1352 file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.
\r
1353 See <xref linkend="serversideinstallation-testing"/> for further information.</para>
\r
1355 <step xml:id="serversideinstallation-opensrf-env">
\r
1356 <title>Modify the OpenSRF Environment</title>
\r
1357 <para>In this step you will make some minor modifications to the OpenSRF environment:</para>
\r
1360 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
1361 modify the shell configuration file <filename>~/.bashrc</filename> for
\r
1362 user <systemitem class="username">opensrf</systemitem> by adding a Perl
\r
1363 environmental variable, then execute the shell configuration file to load
\r
1364 the new variables into your current environment.</para>
\r
1365 <note>In a multi-server environment, you must add any
\r
1366 modifications to <filename>~/.bashrc</filename> to the top of the file
\r
1367 <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
\r
1368 return </literal>. This will allow headless (scripted) logins to load the
\r
1369 correct environment.</note>
\r
1372 # as the opensrf user:
\r
1373 echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
\r
1374 . ~/.bashrc</userinput>
\r
1379 <step performance="optional">
\r
1380 <title>(OPTIONAL) Enable and Disable Language Localizations</title>
\r
1381 <para>You can load translations such as Armenian (hy-AM), Canadian French
\r
1382 (fr-CA), and others into the database to complete the translations available in
\r
1383 the OPAC and Staff Client. For further information, see
\r
1384 <xref linkend="languagesandlocalization"/>.</para>
\r
1388 <section xml:id="serversideinstallation-starting">
\r
1389 <title>Starting Evergreen</title>
\r
1390 <para>In this section you will learn how to start the Evergreen services.
\r
1391 For completeness, instructions for stopping Evergreen can be found later in
\r
1392 <xref linkend="serversideinstallation-stopping"/>.</para>
\r
1395 <para>As the <systemitem class="username">root</systemitem>
\r
1396 user, start the <systemitem class="service">ejabberd</systemitem> and
\r
1397 <systemitem class="service">memcached</systemitem> services as follows:</para>
\r
1400 # as the root user:
\r
1401 /etc/init.d/ejabberd start
\r
1402 /etc/init.d/memcached start</userinput>
\r
1406 <para>As the <systemitem class="username">opensrf</systemitem> user,
\r
1407 start Evergreen as follows:</para>
\r
1410 # as the opensrf user:
\r
1411 osrf_ctl.sh -l -a start_all</userinput>
\r
1413 <para>The flag <option>-l</option> forces Evergreen to use
\r
1414 <systemitem class="domainname">localhost</systemitem> (your current system)
\r
1415 as the hostname. The flag <option>-a start_all</option> starts the other
\r
1416 OpenSRF <systemitem class="service">router</systemitem> ,
\r
1417 <systemitem class="service">Perl</systemitem> , and
\r
1418 <systemitem class="service">C</systemitem> services.</para>
\r
1421 <para>You can also start Evergreen without the
\r
1422 <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
\r
1423 utility must know the fully qualified domain name for the system
\r
1424 on which it will execute. That hostname was probably specified
\r
1425 in the configuration file <filename>opensrf.xml</filename> which
\r
1426 you configured in a previous step.</para>
\r
1429 <para>If you receive an error message similar to
\r
1430 <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
\r
1431 environment variable <envar>PATH</envar> does not include the
\r
1432 directory <filename class="directory">/openils/bin</filename>.
\r
1433 As the <systemitem class="username">opensrf</systemitem> user,
\r
1434 edit the configuration file <filename>~/.bashrc</filename> and
\r
1435 add the following line:
\r
1436 <literal>export PATH=$PATH:/openils/bin</literal></para>
\r
1439 <para>If you receive an error message similar to <emphasis>Can't
\r
1440 locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
\r
1441 aborted</emphasis>, then your environment variable
\r
1442 <emphasis role="bold">PERL5LIB</emphasis> does not include the
\r
1443 directory <filename class="directory">/openils/lib/perl5</filename>.
\r
1444 As the <systemitem class="username">opensrf</systemitem> user,
\r
1445 edit the configuration file <filename>~/.bashrc</filename> and
\r
1446 add the following line:
\r
1447 <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
\r
1452 <para>In this step you will generate the Web files needed by the Staff Client
\r
1453 and catalog, and update the proximity of locations in the Organizational Unit
\r
1454 tree (which allows <emphasis>Holds</emphasis> to work properly).</para>
\r
1455 <para>You must do this the first time you start Evergreen and after making any
\r
1456 changes to the library hierarchy.</para>
\r
1457 <para>As the <systemitem class="username">opensrf</systemitem> user, execute the
\r
1458 following command and review the results:</para>
\r
1461 # as the opensrf user:
\r
1463 ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
\r
1465 Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
\r
1466 Updating fieldmapper
\r
1467 Updating web_fieldmapper
\r
1469 removing OrgTree from the cache for locale hy-AM...
\r
1470 removing OrgTree from the cache for locale cs-CZ...
\r
1471 removing OrgTree from the cache for locale en-CA...
\r
1472 removing OrgTree from the cache for locale en-US...
\r
1473 removing OrgTree from the cache for locale fr-CA...
\r
1474 removing OrgTree from the cache for locale ru-RU...
\r
1475 Updating OrgTree HTML
\r
1476 Updating locales selection HTML
\r
1477 Updating Search Groups
\r
1478 Refreshing proximity of org units
\r
1479 Successfully updated the organization proximity
\r
1480 Done</computeroutput>
\r
1484 <para>As the <systemitem class="username">root</systemitem> user, restart the
\r
1485 Apache Web server:</para>
\r
1488 # as the root user:
\r
1489 /etc/init.d/apache2 restart</userinput>
\r
1491 <note>If the Apache Web server was running when you started the OpenSRF
\r
1492 services, you might not be able to successfully log into the OPAC or Staff
\r
1493 Client until the Apache Web server has been restarted.</note>
\r
1497 <section xml:id="serversideinstallation-testing">
\r
1498 <title>Testing Your Evergreen Installation</title>
\r
1499 <para>This section describes several simple tests you can perform to verify that the Evergreen
\r
1500 server-side software has been installed and configured properly and is running as
\r
1502 <simplesect xml:id="serversideinstallation-testing-connections">
\r
1503 <title>Testing Connections to Evergreen</title>
\r
1504 <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
\r
1505 <command>srfsh</command> application and try logging onto the Evergreen server using the default
\r
1506 administrator username and password. Following is sample output generated by executing
\r
1507 <command>srfsh</command> after a successful Evergreen installation. For help with
\r
1508 <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
\r
1509 As the <systemitem class="username">opensrf</systemitem> user,
\r
1510 execute the following commands to test your Evergreen connection:</para>
\r
1513 # as the opensrf user:
\r
1514 /openils/bin/srfsh</userinput>
\r
1516 srfsh% <userinput>login admin open-ils</userinput>
\r
1517 Received Data: "250bf1518c7527a03249858687714376"
\r
1518 ------------------------------------
\r
1519 Request Completed Successfully
\r
1520 Request Time in seconds: 0.045286
\r
1521 ------------------------------------
\r
1524 "textcode":"SUCCESS",
\r
1527 "stacktrace":"oils_auth.c:304",
\r
1529 "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
\r
1533 ------------------------------------
\r
1534 Request Completed Successfully
\r
1535 Request Time in seconds: 1.336568
\r
1536 ------------------------------------</computeroutput>
\r
1538 <para>If this does not work, try the following:</para>
\r
1541 <para>As the <systemitem class="username">opensrf</systemitem> user, run the
\r
1542 <filename>settings-tester.pl</filename> utility to review your Evergreen
\r
1543 installation for any system configuration problems:</para>
\r
1546 # as the opensrf user:
\r
1548 ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
\r
1550 <para>If the output of <command>settings-tester.pl</command> does not help you
\r
1551 find the problem, please do not make any significant changes to your
\r
1552 configuration.</para>
\r
1555 <para>Follow the steps in the troubleshooting guide in
\r
1556 <xref linkend="troubleshooting"/>.</para>
\r
1559 <para>If you have followed the entire set of installation steps listed here
\r
1560 closely, you are probably extremely close to a working system. Gather your
\r
1561 configuration files and log files and contact the
\r
1562 <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
\r
1563 list for assistance before making any drastic changes to your system
\r
1564 configuration.</para>
\r
1568 <simplesect xml:id="serversideinstallation-running-staffclient">
\r
1569 <title>Testing the Staff Client on Linux</title>
\r
1570 <para>In this section you will confirm that a basic login on the Staff Client works
\r
1572 <para>Run the Evergreen Staff Client on a Linux system by using the application
\r
1573 <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
\r
1574 version 3.0 and later on Ubuntu and Debian distributions).</para>
\r
1575 <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
\r
1579 # as the root user:
\r
1580 xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini</userinput>
\r
1582 <para>A login screen for the Staff Client similar to this should appear:</para>
\r
1584 <alt>Logging into the Staff Client</alt>
\r
1586 <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>
\r
1589 <para>First, add the name of your Evergreen server to the field
\r
1590 <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably
\r
1591 want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test
\r
1592 Server. You should now see the messages <literal>200:OK</literal> in the fields
\r
1593 <literal>Status</literal> and <literal>Version</literal>.</para>
\r
1594 <para>Because this is the initial run of the Staff Client, you will see a warning in the
\r
1595 upper-right saying: <emphasis role="bold">Not yet configured for the specified
\r
1596 server</emphasis>. To continue, you must assign a workstation name.</para>
\r
1597 <para>Try to log into the Staff Client with the admin username and password you created during installation. If the login is successful,
\r
1598 you will see the following screen:</para>
\r
1600 <alt>Logging into the Staff Client</alt>
\r
1602 <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>
\r
1605 <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the
\r
1606 main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>
\r
1608 <alt>Adding an SSL Exception in the Staff Client</alt>
\r
1610 <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>
\r
1613 <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm
\r
1614 Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the
\r
1615 main window and try to log in again.</para>
\r
1617 <simplesect xml:id="serversideinstallation-starting-apache-server">
\r
1618 <title>Testing the Apache Web Server</title>
\r
1619 <para>In this section you will test the Apache configuration file(s), then restart the
\r
1620 Apache web server.</para>
\r
1621 <para>As the <emphasis role="bold">root</emphasis> user, execute the following
\r
1622 commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen
\r
1623 modules to be reloaded even if the Apache server is already running. Any problems found
\r
1624 with your configuration files should be displayed:</para>
\r
1627 # as the root user:
\r
1628 apache2ctl configtest && /etc/init.d/apache2 restart</userinput>
\r
1631 <simplesect xml:id="serversideinstallation-stopping">
\r
1632 <title>Stopping Evergreen</title>
\r
1633 <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the
\r
1634 Evergreen services. For completeness, following are instructions for stopping the
\r
1635 Evergreen services.</para>
\r
1636 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
\r
1637 services by using the following command:</para>
\r
1640 # as the opensrf user
\r
1641 # stop the server; use "-l" to force hostname to be "localhost"
\r
1642 osrf_ctl.sh -l -a stop_all</userinput>
\r
1644 <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the
\r
1645 <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the
\r
1646 fully qualified domain name for the system on which it will execute. That hostname may
\r
1647 have been specified in the configuration file <filename>opensrf.xml</filename>, which
\r
1648 you configured in a previous step.</note>
\r
1651 <section xml:id="serversideinstallation-postinstallation">
\r
1652 <title>Post-Installation Chores</title>
\r
1653 <para>There are several additional steps you may need to complete after Evergreen has been
\r
1654 successfully installed and tested. Some steps may not be needed (e.g., setting up support for
\r
1657 <title>Remove temporary Apache configuration changes</title>
\r
1658 <para>You modified the Apache configuration file
\r
1659 <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
\r
1660 temporary measure to expedite testing (see
\r
1661 <xref linkend="serversideinstallation-modify-apache"/> for further information).
\r
1662 Those changes must now be reversed in order to deny unwanted access to your
\r
1663 CGI scripts from users on other public networks.</para>
\r
1666 <emphasis>This temporary network update was done to expedite
\r
1667 testing. You <emphasis role="bold">must</emphasis> correct
\r
1668 this for a public production system.</emphasis>
\r
1671 <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
\r
1672 file again and comment out the line <literal>Allow from all</literal> and uncomment the
\r
1673 line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
\r
1674 address scheme.</para>
\r
1676 <section xml:id="serversideinstallation-ssl">
\r
1677 <title>Configure a permanent SSL key</title>
\r
1678 <para>You used the command <command>openssl</command> in an earlier step to
\r
1679 temporarily create a new SSL key for the Apache server (see
\r
1680 <xref linkend="serversideinstallation-createsslcertificate"/> for further
\r
1681 information). This self-signed security certificate was adequate during
\r
1682 testing and development, but will continue to generate warnings in the Staff
\r
1683 Client and browser. For a public production server you should configure or
\r
1684 purchase a signed SSL certificate.</para>
\r
1685 <para>There are several open source software solutions that provide schemes to
\r
1686 generate and maintain public key security certificates for your library
\r
1687 system. Some popular projects are listed below; please review them for
\r
1688 background information on why you need such a system and how you can provide
\r
1692 <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>
\r
1695 <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>
\r
1698 <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>
\r
1703 <emphasis>The temporary SSL key was only created to expedite
\r
1704 testing. You should install a proper SSL certificate for a public
\r
1705 production system.</emphasis>
\r
1710 <title>(OPTIONAL) IP-Redirection</title>
\r
1711 <para>By default, Evergreen is configured so searching the OPAC always starts in the
\r
1712 top-level (regional) library rather than in a second-level (branch) library. Instead,
\r
1713 you can use "IP-Redirection" to change the default OPAC search location to use the IP
\r
1714 address range assigned to the second-level library where the seach originates. You must
\r
1715 configure these IP ranges by creating the configuration file
\r
1716 <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script
\r
1717 <filename>/etc/apache2/startup.pl</filename>.</para>
\r
1718 <para>First, copy the sample file
\r
1719 <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>
\r
1720 to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single
\r
1721 line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use
\r
1722 the IP address ranges for your library system. Add new lines to represent the IP address
\r
1723 range for each branch library. Replace the values for <literal>MY-LIB</literal> with the
\r
1724 values for each branch library found in the table
\r
1725 <literal>actor.org_unit</literal>.</para>
\r
1726 <para>Finally, modify the Apache startup script
\r
1727 <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then
\r
1728 restarting the Apache server:</para>
\r
1729 <programlisting language="xml"><![CDATA[
\r
1730 # - Uncomment the following 2 lines to make use of the IP redirection code
\r
1731 # - The IP file should contain a map with the following format:
\r
1732 # - actor.org_unit.shortname <start_ip> <end_ip>
\r
1733 # - e.g. LIB123 10.0.0.1 10.0.0.254
\r
1734 use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);
\r
1735 OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');
\r
1736 ]]></programlisting>
\r
1739 <title>(OPTIONAL) Set Up Support For Reports</title>
\r
1740 <para>Evergreen reports are extremely powerful but require some simple configuration.
\r
1741 See <xref linkend="report_starting_reporter_service"/> for information on starting and
\r
1742 stopping the Reporter daemon processes.</para>
\r
projects / working / Evergreen.git / blob