1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter xml:id="serversideinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
4 <title>Server-side Installation of Evergreen Software</title>
6 <para>This section describes installation of the Evergreen server-side software and its associated components.
7 Installation, configuration, testing and verification
8 of the software is straightforward if you follow some simple directions.</para>
11 <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
12 stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
13 installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
15 <para>The current version of the Evergreen server-side software runs as a native application on any of several
16 well-known <systemitem class="osname">Linux</systemitem> distributions
17 (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>).
18 It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem>
19 operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
20 Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
21 installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
22 <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
23 <application>"VirtualBox"</application>, or <application>"VMware"</application>, or
24 <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>
25 environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
26 systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
27 <application>"VMware"</application>). More information on virtualized environments can be found in
28 <xref linkend="serversideinstallation-virtual"/>.</para>
29 <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
30 <para>The Evergreen server-side software has dependencies on particular versions of certain major software
31 sub-components. Successful installation of Evergreen software requires that software versions agree with those
33 <table xml:id="serversideinstall-software-dependencies">
34 <title>Evergreen Software Dependencies</title>
35 <tgroup align="left" cols="3" colsep="1" rowsep="1">
36 <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
37 <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
38 <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
41 <entry>Evergreen</entry>
42 <entry>OpenSRF</entry>
43 <entry>PostgreSQL</entry>
48 <entry>1.6.1.x</entry>
50 <entry>8.2 / 8.3</entry>
53 <entry>1.6.0.x</entry>
55 <entry>8.2 / 8.3</entry>
60 <entry>8.1 / 8.2</entry>
65 <entry>8.1 / 8.2</entry>
70 <section xml:id="serversideinstallation-all">
71 <title>Installing Server-Side Software</title>
72 <para>This section describes the installation of the major components of Evergreen server-side software.</para>
73 <para>As far as possible, you should perform the following steps in the exact order given since the
74 success of many steps relies on the successful completion of earlier steps. You should make backup
75 copies of files and environments when you are instructed to do so. In the event of installation problems
76 those copies can allow you to back out of a step gracefully and resume the installation from a known
77 state. See <xref linkend="backingup"/> for further information.</para>
78 <para>Of course, after you successfully complete and test the entire Evergreen installation you should
79 take a final snapshot backup of your system(s). This can be the first in the series of regularly
80 scheduled system backups that you should probably also begin.</para>
81 <section xml:id="serversideinstallation-opensrf">
82 <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or
83 <systemitem class="osname">Debian</systemitem></title>
84 <para>This section describes the installation of the latest version of the Open Service Request
85 Framework (OpenSRF), a major component of the Evergreen server-side software, on
86 <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
87 systems. Evergreen software is integrated with and depends on the OpenSRF software
89 <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
90 properly installed and configured. Do not continue with any further Evergreen installation steps
91 until you have verified that OpenSRF has been successfully installed.</para>
93 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
94 platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch
95 (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and
96 <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>
97 <para>In the following instructions, you are asked to perform certain steps as either
98 the <systemitem class="username">root</systemitem> user, the
99 <systemitem class="username">opensrf</systemitem> user, or the
100 <systemitem class="username">postgres</systemitem> user.</para>
103 <para><systemitem class="osname">Debian</systemitem> -- To become the
104 <systemitem class="username">root</systemitem> user, issue the command
105 <command>su -</command> and enter the password of the
106 <systemitem class="username">root</systemitem> user.</para>
109 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
110 <systemitem class="username">root</systemitem> user, issue the command
111 <command>sudo su -</command> and enter the password of the
112 <systemitem class="username">root</systemitem> user.</para>
115 <para>To switch from the <systemitem class="username">root</systemitem> user to a
116 different user, issue the command <command>su - USERNAME</command>. For example, to
117 switch from the <systemitem class="username">root</systemitem> user to the
118 <systemitem class="username">opensrf</systemitem> user, issue the command
119 <command>su - opensrf</command>. Once you have become a non-root user, to become
120 the <systemitem class="username">root</systemitem> user again, simply issue the command
121 <command>exit</command>.</para>
125 <title>Add the OpenSRF User</title>
126 <para>As the <systemitem class="username">root</systemitem> user, add the
127 opensrf user to the system. The default shell for the new user is automatically
128 set to <command>/bin/bash</command> to inherit a reasonable environment:</para>
130 <userinput>useradd -m -s /bin/bash opensrf</userinput>
131 <userinput>passwd opensrf</userinput>
135 <title>Download and Unpack Latest OpenSRF Version</title>
136 <para>As the <systemitem class="username">opensrf</systemitem> user, download
137 and extract the latest version of OpenSRF. The latest version can be found here:
138 <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>
140 <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>
141 <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>
143 <para>The new directory
144 <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>
147 <title>Install Prerequisites to Build OpenSRF</title>
148 <para>In this section you will install and configure a set of prerequisites that will be
149 used to build OpenSRF. In a following step you will actually build the OpenSRF software
150 using the <command>make</command> utility.</para>
151 <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
152 below to build the prerequisites from the software distribution that you just downloaded
153 and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the example with
154 the keyword corresponding to the name of the <systemitem class="osname">Linux</systemitem>
155 distribution listed in the distribution keywords table
156 <xref linkend="serversideinstallation-keywords-opensrf"/>. </para>
158 <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
159 <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
161 <table xml:id="serversideinstallation-keywords-opensrf">
162 <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
163 <tgroup align="left" cols="2" colsep="1" rowsep="1">
164 <colspec colnum="1" colwidth="1.0*"/>
165 <colspec colnum="2" colwidth="3.0*"/>
168 <entry>Keyword</entry>
169 <entry>Description</entry>
174 <entry>debian-etch</entry>
175 <entry>for Debian Etch (4.0)</entry>
178 <entry>debian-lenny</entry>
179 <entry>for Debian Lenny (5.0)</entry>
182 <entry>ubuntu-hardy</entry>
183 <entry>for Ubuntu Hardy Heron (8.04)</entry>
186 <entry>ubuntu-karmic</entry>
187 <entry>for Ubuntu Karmic Koala (9.10)</entry>
190 <entry>ubuntu-lucid</entry>
191 <entry>for Ubuntu Lucid Lynx (10.04)</entry>
196 <para>This will install a number of packages on the system that are required by OpenSRF,
197 including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
198 CPAN configuration prompt to allow it to automatically configure itself to download and
199 install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
200 it should install prerequisite modules - say <literal>Yes</literal>.</para>
203 <title>Build OpenSRF</title>
206 <title>Configure OpenSRF</title>
207 <para>As the <systemitem class="username">opensrf</systemitem>
208 user, return to the OpenSRF build directory and use the
209 <command>configure</command> utility to prepare for the next
210 step of compiling and linking the software. If you wish to
211 include support for Python and Java, add the configuration
212 options <option>--enable-python</option> and
213 <option>--enable-java</option>, respectively:</para>
215 <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
216 <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
217 <userinput>make</userinput>
221 <title>Compile, Link and Install OpenSRF</title>
222 <para>As the <systemitem class="username">root</systemitem>
223 user, return to the OpenSRF build directory and use the
224 <command>make</command> utility to compile, link and install
227 <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
228 <userinput>make install</userinput>
232 <title>Update the System Dynamic Library Path</title>
233 <para>You must update the system dynamic library path to force
234 your system to recognize the newly installed libraries. As the
235 <systemitem class="username">root</systemitem> user, do this by
236 creating the new file
237 <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
238 new library path, then run the command
239 <command>ldconfig</command> to automatically read the file and
240 modify the system dynamic library path:</para>
242 <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>
243 <userinput>ldconfig</userinput>
246 <step><title>Define Public and Private OpenSRF Domains</title><para>You must define your public and private OpenSRF
247 domains. For security purposes, OpenSRF uses Jabber domains to
248 separate services into public and private realms. Throughout
249 these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public
250 domain and <systemitem class="domainname">private.localhost</systemitem> for the
251 private domain. On a single-server system, the easiest way to
252 define public and private domains is to define separate host
253 names by adding entries to the file
254 <filename>/etc/hosts</filename>.</para> <para>As the <systemitem class="username">root</systemitem> user, edit the file
255 <filename>/etc/hosts</filename> and add the following entries
256 for our example domains:</para><screen><userinput>127.0.1.2 public.localhost public</userinput><userinput>127.0.1.3 private.localhost private</userinput></screen></step>
258 <title>Change File Ownerships</title>
259 <para>As the <systemitem class="username">root</systemitem>
260 user, change the ownership of all files installed in the
261 directory <filename class="directory">/openils</filename> to the
262 user <systemitem class="username">opensrf</systemitem>:</para>
264 <userinput>chown -R opensrf:opensrf /openils</userinput>
270 <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
271 <para>As the <systemitem class="username">root</systemitem> user, stop the
272 <systemitem class="service">ejabberd</systemitem> service:</para>
274 <userinput>/etc/init.d/ejabberd stop</userinput>
276 <para>If <systemitem class="service">ejabberd</systemitem> reports that it is
277 already stopped, it may have run into a problem starting back at the
278 installation stage. One possible fix is to kill any remaining
279 <systemitem class="daemon">beam</systemitem> and
280 <systemitem class="daemon">epmd</systemitem> processes, then edit the
281 configuration file <filename>/etc/ejabberd/ejabberd.cfg</filename>
282 to hardcode a domain:</para>
284 <userinput>epmd -kill</userinput>
285 <userinput>killall beam; killall beam.smp</userinput>
286 <userinput>rm /var/lib/ejabberd/*</userinput>
287 <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
291 <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
292 <para>As the <systemitem class="username">root</systemitem> user, edit the file
293 <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following
298 <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>
300 <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>
304 <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to
305 <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>
306 <para>If you see something like this instead:
307 <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>
309 <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>
312 <para>Change all three occurrences of <literal>max_stanza_size</literal>
313 to<literal>2000000</literal>.</para>
316 <para>Change both occurrences of <literal>maxrate</literal> to
317 <literal>500000</literal>.</para>
320 <para>Comment out the line <literal>{mod_offline, []}</literal>
321 by placing two <literal>%</literal> comment signs in front.</para>
325 <step xml:id="serversideinstallation-opensrf-continued">
326 <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
327 <para>As the <systemitem class="username">root</systemitem> user, restart the
328 <systemitem class="service">ejabberd</systemitem> service to test the
329 configuration changes and to register your users:</para>
331 <userinput>/etc/init.d/ejabberd start</userinput>
335 <title>Register <systemitem class="username">router</systemitem> and
336 <systemitem class="username">ejabberd</systemitem> users</title>
337 <para>On each domain, you need two
338 <systemitem class="service">ejabberd</systemitem> users to manage
339 the OpenSRF communications:</para>
342 <para>a <systemitem class="username">router</systemitem> user,
343 to whom all requests to connect to an OpenSRF service will be
344 routed; this <systemitem class="service">ejabberd</systemitem>
345 user must be named <systemitem class="username">router</systemitem></para>
348 <para>an <systemitem class="username">opensrf</systemitem> user,
349 which clients use to connect to OpenSRF services; this user can
350 be named anything you like, but we will use
351 <literal>opensrf</literal> in our examples</para>
354 <para>As the <systemitem class="username">root</systemitem> user, use the
355 <command>ejabberdctl</command> utility to register your ejabber users
356 <systemitem class="username">router</systemitem> and
357 <systemitem class="username">opensrf</systemitem> for the OpenSRF router service
358 on each domain. The users should have different passwords on each domain.
359 These users will correspond to those configured in the file
360 <filename>/openils/conf/opensrf_core.xml</filename>:</para>
361 <programlisting language="xml"><![CDATA[
362 # The syntax for registering a user with ejabberdctl is
363 # ejabberdctl register <user> <domain> <password>
365 ejabberdctl register router private.localhost <password>
366 ejabberdctl register opensrf private.localhost <password>
367 ejabberdctl register router public.localhost <password>
368 ejabberdctl register opensrf public.localhost <password>
372 <title>Create configuration files</title>
373 <para>As the <systemitem class="username">opensrf</systemitem> user, use the
374 example templates to create the configuration files
375 <filename>/openils/conf/opensrf_core.xml</filename> and
376 <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
378 <userinput>cd /openils/conf</userinput>
379 <userinput>cp opensrf.xml.example opensrf.xml</userinput>
380 <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
384 <title>Change Jabber usernames and passwords</title>
385 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
386 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
387 to update the Jabber usernames and passwords to match the values shown in the
388 following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
389 shows common XPath syntax to indicate the approximate position within the XML
390 file that needs changes. The right-hand side of the table shows the replacement
392 <table xml:id="serversideinstallation-xpath-table-1">
393 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
394 <tgroup align="left" cols="2" colsep="1" rowsep="1">
395 <colspec colname="Xpath" colnum="1" colwidth="1.5*"/>
396 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
399 <entry>XPath location</entry>
405 <entry>/config/opensrf/username</entry>
407 <systemitem class="username">opensrf</systemitem>
411 <entry>/config/opensrf/passwd </entry>
413 <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
417 <entry>/config/gateway/username</entry>
419 <systemitem class="username">opensrf</systemitem>
423 <entry>/config/gateway/passwd</entry>
425 <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
429 <entry>/config/routers/router/transport,
430 first entry where transport/server == public.localhost:
433 <systemitem class="username">router</systemitem>
437 <entry>/config/routers/router/transport,
438 first entry where transport/server == public.localhost:
441 <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">router</systemitem> user
445 <entry>/config/routers/router/transport,
446 second entry where transport/server == private.localhost:
449 <systemitem class="username">router</systemitem>
453 <entry>/config/routers/router/transport,
454 second entry where transport/server == private.localhost:
457 <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">router</systemitem> user
463 <para>You also need to specify the domains from which
464 <systemitem class="service">OpenSRF</systemitem> will accept and to which
465 <systemitem class="service">OpenSRF</systemitem> will make connections.
466 If you are installing <application>OpenSRF</application> on a single server
467 and using the <systemitem class="domainname">private.localhost</systemitem> /
468 <systemitem class="domainname">public.localhost</systemitem> domains,
469 these will already be set to the correct values. Otherwise, search and replace
470 to match your values.</para>
473 <title>Set location of persistent database</title>
474 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
475 file <filename>/openils/conf/opensrf.xml</filename> to set the location of the
476 persistent database in the <literal>dbfile</literal> element near the end of the
478 <programlisting language="xml"><![CDATA[
479 <!-- Example of an app-specific setting override -->
482 <dbfile>/tmp/persist.db</dbfile>
488 <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
489 <para>In this section you will set up a special configuration file for each user
490 who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
491 shell</emphasis>) utility.</para>
492 <para>The software installation will automatically create
493 <command>srfsh</command>. This is a command line diagnostic tool for testing and
494 interacting with <application>OpenSRF</application>. It will be used in a future
495 step to complete and test the Evergreen installation. See
496 <xref linkend="serversideinstallation-testing"/> for further information.</para>
497 <para>As the <systemitem class="username">root</systemitem> user, copy the short
498 sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
499 to the file <filename>.srfsh.xml</filename> (note the leading dot!) in the home
500 directory of each user who will use <command>srfsh</command>. Finally, edit each
501 file <filename>.srfsh.xml</filename> and make the following changes. When you
502 finish, remember to change the owner of the file to match the owner of the home
505 <listitem>Modify <literal>domain</literal> to be the router hostname
506 (following our domain examples,
507 <systemitem class="domainname">private.localhost</systemitem> will give
508 <command>srfsh</command> access to all OpenSRF services, while
509 <systemitem class="domainname">public.localhost</systemitem> will only
510 allow access to those OpenSRF services that are publicly
512 <listitem>Modify <literal>username</literal> and
513 <literal>password</literal> to match the <literal>opensrf</literal>
514 Jabber user for the chosen domain</listitem>
515 <listitem>Modify <literal>logfile</literal> to be the full path for a
516 log file to which the user has write access</listitem>
517 <listitem>Modify <literal>loglevel</literal> as needed for testing</listitem>
519 <programlisting language="xml"><![CDATA[
520 <?xml version="1.0"?>
521 <!-- This file follows the standard bootstrap config file layout -->
522 <!-- found in opensrf_core.xml -->
524 <router_name>router</router_name>
525 <domain>private.localhost</domain>
526 <username>opensrf</username>
527 <passwd>privsrf</passwd>
529 <logfile>/tmp/srfsh.log</logfile>
530 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
531 <loglevel>4</loglevel>
536 <title>Modify Environmental Variable PATH for
537 <systemitem class="username">opensrf</systemitem> User</title>
538 <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
539 environmental variable <envar>PATH</envar> by adding a new file path to the
540 <systemitem class="username">opensrf</systemitem> user's shell configuration
541 file <filename>.bashrc</filename>:</para>
543 <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
547 <title>Start OpenSRF</title>
548 <para>As the <systemitem class="username">root</systemitem> user, start the
549 <systemitem class="service">ejabberd</systemitem> and
550 <systemitem class="service">memcached</systemitem> services:</para>
552 <userinput>/etc/init.d/ejabberd start</userinput>
553 <userinput>/etc/init.d/memcached start</userinput>
555 <para>Finally, as the <systemitem class="username">opensrf</systemitem> user,
556 start OpenSRF. Use "-l" to force hostname to be "localhost":</para>
558 <userinput>osrf_ctl.sh -l -a start_all</userinput>
561 <para>If you receive the error message <errortext>bash: osrf_ctl.sh:
562 command not found</errortext>, then your environment variable
563 <envar>PATH</envar> does not include the
564 <filename class="directory">/openils/bin</filename> directory;
565 this should have been set by <filename>.bashrc</filename> when you
566 logged in as the <systemitem class="username">opensrf</systemitem> user,
567 but you can manually set it using the following command:</para>
569 <userinput>export PATH=$PATH:/openils/bin</userinput>
572 <para>You can also start Evergreen <emphasis role="bold">without</emphasis> the
573 <option>-l</option> flag, but <command>osrf_ctl.sh</command> must know the fully
574 qualified domain name for the system on which it will execute. That hostname may
575 have been specified in the configuration file <filename>opensrf.xml</filename>,
576 which you configured in a previous step.</para>
579 <title>Test connections to OpenSRF</title>
580 <para>Once you have installed and started OpenSRF, as the
581 <systemitem class="username">root</systemitem> user, test your connection to
582 <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
583 utility and trying to call the <command>add</command> method on the OpenSRF
584 <systemitem class="service">math</systemitem> service:</para>
586 <userinput>/openils/bin/srfsh</userinput>
587 <prompt>srfsh#</prompt>
588 <prompt>request opensrf.math add 2 2</prompt>
589 <prompt>Received Data: 4</prompt>
590 <prompt>------------------------------------</prompt>
591 <prompt>Request Completed Successfully</prompt>
592 <prompt>Request Time in seconds: 0.007519</prompt>
593 <prompt>------------------------------------</prompt>
594 <prompt>srfsh#</prompt>
596 <para>For other <command>srfsh</command> commands, type in
597 <userinput>help</userinput> at the prompt.</para>
600 <title>Stopping OpenSRF</title>
601 <para>As the <systemitem class="username">opensrf</systemitem> user, stop OpenSRF:</para>
603 <userinput>osrf_ctl.sh -l -a stop_all</userinput>
608 <section xml:id="serversideinstallation-ubuntudebian">
609 <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or
610 <systemitem class="osname">Debian</systemitem></title>
611 <para>This section outlines the installation process for the latest stable version of
613 <para>In this section you will download, unpack, install, configure and test the Evergreen
614 system, including the Evergreen server and the PostgreSQL database system. You will make several
615 configuration changes and adjustments to the software, including updates to configure the system
616 for your own locale, and some updates needed to work around a few known issues.</para>
618 <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
619 architectures. There may be differences between the Desktop and Server editions of
620 <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
622 <para>In the following instructions, you are asked to perform certain steps as
623 either the <systemitem class="username">root</systemitem> user, the
624 <systemitem class="username">opensrf</systemitem> user, or the
625 <systemitem class="username">postgres</systemitem> user.</para>
628 <para><systemitem class="osname">Debian</systemitem> -- To become the
629 <systemitem class="username">root</systemitem> user, issue the command
630 <command>su -</command> and enter the password of the
631 <systemitem class="username">root</systemitem> user.</para>
634 <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
635 <systemitem class="username">root</systemitem> user, issue the command
636 <command>sudo su -</command> and enter the password of the
637 <systemitem class="username">root</systemitem> user.</para>
640 <para>To switch from the <systemitem class="username">root</systemitem> user to a
641 different user, issue the command <command>su - USERNAME</command>. For example, to
642 switch from the <systemitem class="username">root</systemitem> user to the
643 <systemitem class="username">opensrf</systemitem> user, issue the command
644 <command>su - opensrf</command>. Once you have become a non-root user, to become the
645 <systemitem class="username">root</systemitem> user again, simply issue the command
646 <command>exit</command>.</para>
650 <title>Install OpenSRF</title>
651 <para>Evergreen software is integrated with and depends on the Open Service
652 Request Framework (OpenSRF) software system. For further information on
653 installing, configuring and testing OpenSRF, see
654 <xref linkend="serversideinstallation-opensrf"/>.</para>
655 <para>Follow the steps outlined in that section and run the specified tests to
656 ensure that OpenSRF is properly installed and configured. Do not continue with
657 any further Evergreen installation steps until you have verified that OpenSRF
658 has been successfully installed.</para>
661 <title>Download and Unpack Latest Evergreen Version</title>
662 <para>As the <systemitem class="username">opensrf</systemitem> user, download
663 and extract the latest version of Evergreen. The latest version can be found here:
664 <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>
666 <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
667 <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>
669 <para>The new directory
670 <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>
671 will be created.</para>
674 <title>Install Prerequisites to Build Evergreen</title>
675 <para>In this section you will install and configure a set of prerequisites that
676 will be used to build Evergreen. In a following step you will actually build the
677 Evergreen software using the <command>make</command> utility.</para>
678 <para>As the <systemitem class="username">root</systemitem> user, enter the
679 commands show below to build the prerequisites from the software distribution
680 that you just downloaded and unpacked. Remember to replace
681 <emphasis>[DISTRIBUTION]</emphasis> in the example with the keyword
682 corresponding to the name of the <systemitem class="osname">Linux</systemitem>
683 distribution listed in the distribution keywords table
684 <xref linkend="serversideinstallation-keywords-evergreen"/> .</para>
686 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
687 <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
689 <table xml:id="serversideinstallation-keywords-evergreen">
690 <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
691 <tgroup align="left" cols="2" colsep="1" rowsep="1">
692 <colspec colnum="1" colwidth="1.0*"/>
693 <colspec colnum="2" colwidth="3.0*"/>
696 <entry>Keyword</entry>
697 <entry>Description</entry>
702 <entry>debian-etch</entry>
703 <entry>for Debian Etch (4.0)</entry>
706 <entry>debian-lenny</entry>
707 <entry>for Debian Lenny (5.0)</entry>
710 <entry>ubuntu-hardy</entry>
711 <entry>for Ubuntu Hardy Heron (8.04)</entry>
714 <entry>ubuntu-karmic</entry>
715 <entry>for Ubuntu Karmic Koala (9.10)</entry>
718 <entry>ubuntu-karmic</entry>
719 <entry>for Ubuntu Lucid Lynx (10.04)</entry>
725 <step xml:id="serversideinstallation-postgresql-default">
726 <title>(OPTIONAL) Install the PostgreSQL Server</title>
727 <para>Since the PostgreSQL server is usually a standalone server in multi-server
728 production systems, the prerequisite installer Makefile in the previous step
729 does not automatically install PostgreSQL. You must install the PostgreSQL server
730 yourself, either on the same system as Evergreen itself or on another system.
731 If your PostgreSQL server is on a different system, just skip this step.</para>
732 <para>For further information on manually installing PostgreSQL, visit the official
733 <link xl:href="http://www.postgresql.org/">PostgreSQL Site</link>.</para>
734 <para>If your PostgreSQL server will be on the same system as your Evergreen
735 software, then as the <systemitem class="username">root</systemitem> user
736 install the required PostgreSQL server packages:</para>
737 <para>For <systemitem class="osname">Debian Lenny</systemitem> and
738 <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>
740 <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>
742 <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and
743 <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>
745 <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>
748 <para>PostgreSQL versions 8.3 or 8.4 are the recommended versions to work
749 with Evergreen 1.6. If you have an older version of PostgreSQL, you should
750 upgrade before installing Evergreen. To find the running version of
751 PostgreSQL, as the <systemitem class="username">postgres</systemitem>
752 user, run the <command>psql</command>. Then type <userinput>SELECT
753 version();</userinput> to get detailed information about your version
754 of PostgreSQL.</para>
757 <step performance="optional">
758 <title>Install Perl Modules on PostgreSQL Server</title>
759 <para>If PostgreSQL is running on the same system as your Evergreen software,
760 then the Perl modules will automatically be available. Just skip this step.
761 Otherwise, continue if your PostgreSQL server is running on another system.</para>
762 <para>You will need to install several Perl modules on the other system. As the
763 <systemitem class="username">root</systemitem> user install the following Perl
766 <userinput># first, ensure the gcc compiler is installed:</userinput>
767 <userinput>apt-get install gcc</userinput>
768 <userinput># then install the Perl modules:</userinput>
769 <userinput>perl -MCPAN -e shell</userinput>
770 <prompt>cpan></prompt>
771 <userinput>install JSON::XS</userinput>
772 <prompt>cpan></prompt>
773 <userinput>install MARC::Record</userinput>
774 <prompt>cpan></prompt>
775 <userinput>install MARC::File::XML</userinput>
777 <para>For more information on installing Perl Modules vist the official
778 <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
781 <title>Update the System Dynamic Library Path</title>
782 <para>You must update the system dynamic library path to force your system to
783 recognize the newly installed libraries. As the <systemitem class="username">root</systemitem> user, create a file named
784 /etc/ld.so.conf.d/eg.conf containing the new library paths:</para>
789 <para>Then run the command <command>ldconfig</command> to automatically read the
790 file and modify the system dynamic library path:</para>
792 <userinput>ldconfig</userinput>
795 <step performance="optional">
796 <title>(OPTIONAL) Restart the PostgreSQL Server</title>
797 <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
798 the <systemitem class="username">root</systemitem> user you must restart
799 PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
800 running on another system, you may skip this step. As the <systemitem class="username">opensrf</systemitem> user, execute the following command, where
801 <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL version
802 (e.g. <literal>8.3</literal>):</para>
804 <userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>
807 <step xml:id="serversideinstallation-configure">
808 <title>Configure Evergreen</title>
809 <para>As the <systemitem class="username">opensrf</systemitem> user, return to
810 the Evergreen build directory and use the <command>configure</command> and
811 <command>make</command> utilities to configure Evergreen so it can be compiled
812 and linked in the next step:</para>
814 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
815 <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
816 <userinput>make</userinput>
819 <step xml:id="serversideinstallation-compilingevergreen">
820 <title>Compile, Link and Install Evergreen</title>
821 <para>In this step you will actually compile, link and install Evergreen and the
822 default Evergreen Staff Client.</para>
823 <para>As the <systemitem class="username">root</systemitem> user, return to the
824 Evergreen build directory and use the <command>make</command> utility as shown
825 below. The Staff Client will also be automatically built, but you must remember
826 to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of
827 the Staff Client you will use to connect to the Evergreen server.</para>
828 <para>For further information on manually building the Staff Client, see
829 <xref linkend="staffclientinstallation-building-staffclient"/>.</para>
831 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
832 <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>
834 <para>The above commands will create a new subdirectory <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename> containing the
836 <para>To complete the Staff Client installation, as the <systemitem class="username">root</systemitem> user create a symbolic link named
837 <emphasis>server</emphasis> in the head of the Staff Client directory <filename class="directory">/openils/var/web/xul</filename> that points to the
838 subdirectory <filename class="directory">/server</filename> of the new Staff
841 <userinput>cd /openils/var/web/xul</userinput>
842 <userinput>ln -sf rel_1_6_1_2/server server</userinput>
846 <title>Copy the OpenSRF Configuration Files</title>
847 <para>As the <systemitem class="username">root</systemitem> user, copy the
848 example OpenSRF configuration files into place. This replaces the configuration
849 files that you set up in a previous step when you installed and tested
850 OpenSRF. You should also create backup copies of the old files for
851 troubleshooting purposes. Finally, change the ownership on the installed files
852 to the <systemitem class="username">opensrf</systemitem> user:</para>
854 <userinput>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</userinput>
855 <userinput>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</userinput>
856 <userinput>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</userinput>
857 <userinput>chown -R opensrf:opensrf /openils/</userinput>
861 <title>Create and Configure PostgreSQL Database</title>
862 <para>In this step you will create the Evergreen database. In the commands
863 below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis> repository to match your PostgreSQL server
864 layout. For example, if you built PostgreSQL from source the path would be
865 <filename class="directory">/usr/local/share/contrib</filename>; if you
866 installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>, the path would be <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem>.</para>
870 <emphasis role="bold">Create and configure the database</emphasis>
872 <para>As the <systemitem class="username">postgres</systemitem>
873 user on the PostgreSQL system create the PostgreSQL database,
874 then set some internal paths:</para>
875 <para>Create the database:</para>
877 <userinput>createdb -E UNICODE evergreen</userinput>
878 <userinput>createlang plperl evergreen</userinput>
879 <userinput>createlang plperlu evergreen</userinput>
880 <userinput>createlang plpgsql evergreen</userinput>
882 <para>Adjust the paths as shown, where
883 <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL
884 version (e.g. <literal>8.3</literal>).</para>
886 <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>
887 <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql evergreen</userinput>
888 <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql evergreen</userinput>
892 <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
893 <para>As the <systemitem class="username">postgres</systemitem>
894 user on the PostgreSQL system, create a new PostgreSQL user
895 named <systemitem class="username">evergreen</systemitem> and
896 assign a password:</para>
898 <userinput>createuser -P -s evergreen</userinput>
899 <prompt>Enter password for new role: MYNEWPASSWORD</prompt>
900 <prompt>Enter it again: MYNEWPASSWORD</prompt>
904 <title>Create Database Schema</title>
905 <para>As the <systemitem class="username">root</systemitem>
906 user, create the database schema and configure your system with
907 the corresponding database authentication details for the
908 <emphasis>evergreen</emphasis> database user that you created in
909 the previous step.</para>
910 <para>Enter the following commands and replace
911 <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and
912 <emphasis>DATABASENAME</emphasis> with appropriate
915 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
916 <userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>
917 <userinput> --service all --create-schema --create-bootstrap --create-offline \</userinput>
918 <userinput> --hostname HOSTNAME --port PORT \</userinput>
919 <userinput> --user evergreen --password PASSWORD --database DATABASENAME</userinput>
921 <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
922 <emphasis role="bold">localhost</emphasis>,
923 <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>,
924 and <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis>
925 will be <emphasis role="bold">evergreen</emphasis>.</para>
927 <para>If you are entering the above command on a single
928 line, do not include the <literal>\</literal>
929 (backslash) characters. If you are using the
930 <command>bash</command> shell, these should only be used
931 at the end of a line at a bash prompt to indicate that
932 the command is continued on the next line.</para>
936 <title>Configure the Apache web server</title>
937 <para>In this step you will configure the Apache web server to
938 support Evergreen software.</para>
939 <para>First, you must enable some built-in Apache modules and install
940 some additional Apache configuration files. Then you will create a new
941 Security Certificate. Finally, you must make several changes to the Apache
942 configuration file.</para>
945 <title>Enable the required Apache Modules</title>
946 <para>As the <systemitem class="username">root</systemitem> user, enable
947 some modules in the Apache server, then copy the
948 new configuration files to the Apache server
951 <userinput>a2enmod ssl # enable mod_ssl</userinput>
952 <userinput>a2enmod rewrite # enable mod_rewrite</userinput>
953 <userinput>a2enmod expires # enable mod_expires</userinput>
957 <title>Copy Apache configuration files</title>
958 <para>You must copy the Apache configuration
959 files from the Evergreen installation dierectory
960 to the Apache directory. As the <systemitem class="username">root</systemitem> user, perform
961 the following commands:</para>
963 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
964 <userinput>cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/</userinput>
965 <userinput>cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/</userinput>
966 <userinput>cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
970 <title>Create a Security Certificate</title>
971 <para>You must create a new Security Certificate (SSL Key)
972 for the Apache server using the <command>openssl</command>
973 command. For a public production server you must configure
974 or purchase a signed SSL certificate, but for now you can
975 just use a self-signed certificate and accept the warnings
976 in the Staff Client and browser during testing and
978 <systemitem class="username">root</systemitem> user,
979 perform the following commands:</para>
981 <userinput>mkdir /etc/apache2/ssl</userinput>
982 <userinput>cd /etc/apache2/ssl</userinput>
983 <userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
986 <para>This step generates a self-signed SSL
987 certificate. You must install a proper SSL
988 certificate for a public production system to
989 avoid warning messages when users login to their
990 account through the OPAC or when staff login
991 through the staff client.</para>
992 <para>For further information on getting a proper
994 <xref linkend="serversideinstallation-ssl"/>.</para>
997 <step xml:id="serversideinstallation-modify-apache">
998 <title>Update Apache configuration file</title>
999 <para>You must make several changes to the new Apache
1001 <filename>/etc/apache2/sites-available/eg.conf</filename>. As
1002 the <systemitem class="username">root</systemitem> user,
1003 edit the file and make the following changes:</para>
1006 <para>Comment out the line <literal>Allow
1007 from 10.0.0.0/8</literal> and uncomment
1008 the line <literal>Allow from
1009 all</literal>.</para>
1010 <para>This change allows access to your
1011 configuration CGI scripts from
1012 <emphasis role="bold">any</emphasis> workstation on
1013 <emphasis role="bold">any</emphasis>
1014 network. This is only a temporary change
1015 to expedite testing and should be removed
1016 after you have finished and successfully
1017 tested the Evergreen installation.</para>
1020 <emphasis>You must remove these changes
1021 after testing is completed. See
1022 <xref linkend="serversideinstallation-postinstallation"/>
1023 for further details on removing this change
1024 after the Evergreen installation is
1025 complete.</emphasis>
1030 <para>Comment out the line <literal>Listen
1031 443</literal>, since it conflicts with the
1032 same declaration in the configuration file:
1033 <filename>/etc/apache2/ports.conf</filename>.
1034 Note that <systemitem class="osname">Debian
1035 </systemitem> users should not do this
1036 since the conflict does not apply to that
1037 operating system.</para>
1040 <para>The following updates are needed to allow
1041 the logs to function properly, but it may break
1042 other Apache applications on your server:</para>
1043 <para>For the <systemitem class="osname">Linux</systemitem>
1044 distributions <systemitem class="osname">Ubuntu
1045 Hardy</systemitem> or
1046 <systemitem class="osname">Debian Etch</systemitem>,
1047 as the <systemitem class="username">root</systemitem>
1048 user, edit the Apache configuration file
1049 <filename>/etc/apache2/apache2.conf</filename> and
1050 change the line <literal>User www-data</literal>
1051 to <literal>User opensrf</literal>.</para>
1052 <para>For the <systemitem class="osname">Linux</systemitem>
1053 distributions <systemitem class="osname">Ubuntu
1054 Karmic</systemitem> or
1055 <systemitem class="osname">Ubuntu Lucid</systemitem>
1056 or <systemitem class="osname">Debian
1057 Lenny</systemitem>, as the
1058 <systemitem class="username">root</systemitem>
1059 user, edit the Apache configuration file
1060 <filename>/etc/apache2/envvars</filename> and
1061 change the line <literal>export
1062 APACHE_RUN_USER=www-data</literal> to
1064 APACHE_RUN_USER=opensrf</literal>.</para>
1068 <step performance="optional">
1069 <title>(OPTIONAL) Apache Performance Modifications</title>
1070 <para>Some further configuration changes to Apache may be
1071 necessary for busy systems. These changes increase the
1072 number of Apache server processes that are started to
1073 support additional browser connections.</para>
1074 <para>As the <systemitem class="username">root</systemitem>
1075 user, edit the Apache configuration file
1076 <filename>/etc/apache2/apache2.conf</filename> and add the
1077 lines <literal>KeepAliveTimeout 1</literal> and
1078 <literal>MaxKeepAliveRequests 100</literal>, or modify any
1079 existing lines. Then locate the section related to
1080 <emphasis>prefork configuration</emphasis> and modify it
1081 to suit the load on your system:</para>
1082 <programlisting language="xml"><![CDATA[
1083 <IfModule mpm_prefork_module>
1088 MaxRequestsPerChild 10000
1090 ]]></programlisting>
1093 <title>Enable the Evergreen web site</title>
1094 <para>Finally, you must enable the Evergreen web site. As the
1095 <systemitem class="username">root</systemitem> user, execute
1096 the following Apache configuration commands to disable the default
1097 <emphasis>It Works</emphasis> web page and enable the
1098 Evergreen web site:</para>
1100 <userinput>a2dissite default</userinput>
1101 <userinput>a2ensite eg.conf</userinput>
1108 <step xml:id="serversideinstallation-opensrf-config">
1109 <title>Modify the OpenSRF Configuration File</title>
1110 <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
1111 OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
1112 to update the Jabber usernames and passwords, and to specify the domain from
1113 which we will accept and to which we will make connections.</para>
1114 <para>If you are installing Evergreen on a single server and using the
1115 <systemitem class="domainname">private.localhost</systemitem> /
1116 <systemitem class="domainname">public.localhost</systemitem> domains,
1117 these will already be set to the correct values. Otherwise, search and replace
1118 to match your customized values.</para>
1119 <para>The left-hand side of <xref linkend="serversideinstallation-xpath-table-2"/>
1120 shows common XPath syntax to indicate the approximate position within the XML
1121 file that needs changes. The right-hand side of the table shows the replacement
1123 <table xml:id="serversideinstallation-xpath-table-2">
1124 <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
1125 <tgroup align="left" cols="2" colsep="1" rowsep="1">
1126 <colspec colname="Xpath" colnum="1" colwidth="1.5*"/>
1127 <colspec colname="Value" colnum="2" colwidth="2.0*"/>
1130 <entry>XPath location</entry>
1131 <entry>Value</entry>
1136 <entry>/config/opensrf/username</entry>
1138 <systemitem class="username">opensrf</systemitem>
1142 <entry>/config/opensrf/passwd </entry>
1144 <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
1148 <entry>/config/gateway/username</entry>
1150 <systemitem class="username">opensrf</systemitem>
1154 <entry>/config/gateway/passwd</entry>
1156 <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">opensrf</systemitem> user
1160 <entry>/config/routers/router/transport,
1161 first entry where transport/server == public.localhost:
1164 <systemitem class="username">router</systemitem>
1168 <entry>/config/routers/router/transport,
1169 first entry where transport/server == public.localhost:
1172 <systemitem class="domainname">public.localhost</systemitem><systemitem class="username">router</systemitem> user
1176 <entry>/config/routers/router/transport,
1177 second entry where transport/server == private.localhost:
1180 <systemitem class="username">router</systemitem>
1184 <entry>/config/routers/router/transport,
1185 second entry where transport/server == private.localhost:
1188 <systemitem class="domainname">private.localhost</systemitem><systemitem class="username">router</systemitem> user
1195 <step xml:id="serversideinstallation-srfsh">
1196 <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
1197 <para>The software installation will automatically create a utility named
1198 <command>srfsh</command> (surf shell). This is a command line diagnostic tool
1199 for testing and interacting with the OpenSRF network software. It will be used
1200 in a future step to complete and test the Evergreen installation. See
1201 <xref linkend="serversideinstallation-testing"/> for further information.</para>
1202 <para>In this section you will set up a special configuration file for each user
1203 who will need to run the utility. Copy the short sample configuration file
1204 <filename>/openils/conf/srfsh.xml.example</filename> to the file
1205 <filename>.srfsh.xml</filename> (note the leading dot!) in the home directory of
1206 each user who will use <command>srfsh</command>. Finally, edit each user's
1207 <filename>.srfsh.xml</filename> file and make the following changes:</para>
1210 <para>Modify <emphasis role="bold">domain</emphasis> to be the
1211 router hostname (following our domain examples,
1212 <systemitem class="domainname">private.localhost</systemitem>>
1213 will give <command>srfsh</command> access to all OpenSRF services,
1214 while <systemitem class="domainname">public.localhost</systemitem>
1215 will only allow access to those OpenSRF services that are
1216 publicly exposed).</para>
1219 <para>Modify <emphasis role="bold">username</emphasis> and
1220 <emphasis role="bold">password</emphasis> to match the
1221 <systemitem class="username">opensrf</systemitem> Jabber user
1222 for the chosen domain.</para>
1225 <para>Modify <emphasis role="bold">logfile</emphasis> to be the
1226 full path for a log file to which the user has write
1230 <para>Modify <emphasis role="bold">loglevel</emphasis> as needed
1234 <programlisting language="xml"><![CDATA[
1235 <?xml version="1.0"?>
1236 <!-- This file follows the standard bootstrap config file layout -->
1237 <!-- found in opensrf_core.xml -->
1239 <router_name>router</router_name>
1240 <domain>private.localhost</domain>
1241 <username>opensrf</username>
1242 <passwd>evergreen</passwd>
1244 <logfile>/tmp/srfsh.log</logfile>
1245 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
1246 <loglevel>4</loglevel>
1248 ]]></programlisting>
1250 <step xml:id="serversideinstallation-opensrf-env">
1251 <title>Modify the OpenSRF Environment</title>
1252 <para>Modify the shell configuration file <filename>~/.bashrc</filename> for
1253 user <systemitem class="username">opensrf</systemitem> by adding a Perl environmental
1254 variable, then execute the shell configuration file to load the new variables into
1255 your current environment.</para>
1258 <emphasis>In a multi-server environment, you must add any
1259 modifications to <filename>~/.bashrc</filename> to the top of
1260 the file <emphasis>before</emphasis> the line
1261 <literal>[ -z "$PS1" ] && return </literal>.
1262 This will allow headless (scripted) logins to load the correct
1263 environment.</emphasis>
1267 <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>
1268 <userinput>. ~/.bashrc</userinput>
1272 <title>(OPTIONAL) Enable and Disable Language Localizations</title>
1273 <para>You can load translations such as Armenian (hy-AM), Canadian French
1274 (fr-CA), and others into the database to complete the translations available in
1275 the OPAC and staff client. For further information, see <xref linkend="localization"/>.</para>
1279 <section xml:id="serversideinstallation-starting">
1280 <title>Starting Evergreen</title>
1283 <para>As the <systemitem class="username">root</systemitem>
1284 user, start the <systemitem class="service">ejabberd</systemitem> and
1285 <systemitem class="service">memcached</systemitem> services
1286 (if they are not already running):</para>
1288 <userinput>/etc/init.d/ejabberd start</userinput>
1289 <userinput>/etc/init.d/memcached start</userinput>
1293 <para>As the <systemitem class="username">opensrf</systemitem>
1294 user, start Evergreen.</para>
1295 <para>Use the flag <option>-l</option> to force Evergreen to use
1296 <systemitem class="domainname">localhost</systemitem> (your
1297 current system) as the hostname. Using the
1298 <option>start_all</option> option will start the OpenSRF
1299 <systemitem class="service">router</systemitem> ,
1300 <systemitem class="service">Perl</systemitem> , and
1301 <systemitem class="service">C</systemitem> services:</para>
1303 <userinput>$ osrf_ctl.sh -l -a start_all</userinput>
1307 <emphasis>You can also start Evergreen
1308 <emphasis role="bold">without</emphasis>
1309 the <option>-l</option> flag, but the
1310 <command>osrf_ctl.sh</command> utility must know
1311 the fully qualified domain name for the system
1312 on which it will execute. That hostname may have
1313 been specified in the configuration file
1314 <filename>opensrf.xml</filename>, which you
1315 configured in a previous step.</emphasis>
1317 <para>Use the <command>hostname</command> command to
1318 determine the fully qualified domain name of your
1323 <para>If you receive an error message similar to
1324 <emphasis>osrf_ctl.sh: command not found</emphasis>,
1325 then your environment variable
1326 <envar>PATH</envar> does not include the directory
1327 <filename class="directory">/openils/bin</filename>.
1329 <systemitem class="username">opensrf</systemitem>
1330 user, edit the configuration file
1331 <filename>/home/opensrf/.bashrc</filename> and
1332 add the following line:
1333 <literal>export PATH=$PATH:/openils/bin</literal></para>
1336 <para>If you receive an error message similar to
1337 <emphasis>Can't locate OpenSRF/System.pm in
1338 @INC ... BEGIN failed--compilation
1339 aborted</emphasis>, then your environment variable
1340 <emphasis role="bold">PERL5LIB</emphasis> does not
1341 include the directory
1342 <filename class="directory">/openils/lib/perl5</filename>.
1344 <systemitem class="username">opensrf</systemitem>
1345 user, edit the configuration file
1346 <filename>/home/opensrf/.bashrc</filename> and
1347 add the following line:
1348 <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
1353 <para>As the <systemitem class="username">opensrf</systemitem>
1354 user, generate the Web files needed by the Staff Client and
1355 catalog, and calculate the proximity of locations in the
1356 Organizational Unit tree (which allows
1357 <emphasis>Holds</emphasis> to work properly):</para>
1359 <userinput>cd /openils/bin</userinput>
1360 <userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
1361 <prompt>Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'</prompt>
1362 <prompt>Updating fieldmapper</prompt>
1364 <para>You must do this the first time you start Evergreen, and
1365 after making any changes to the library hierarchy.</para>
1368 <para>As the <systemitem class="username">root</systemitem>
1369 user, restart the Apache Web server:</para>
1371 <userinput>/etc/init.d/apache2 restart</userinput>
1374 <para>If the Apache Web server was running when you
1375 started the OpenSRF services, you might not be able to
1376 successfully log in to the OPAC or Staff Client until
1377 the Apache Web server is restarted.</para>
1382 <section xml:id="serversideinstallation-testing">
1383 <title>Testing the Installation</title>
1384 <para>This section describes several simple tests you can perform to verify that the Evergreen
1385 server-side software has been installed and configured properly and is running as
1387 <simplesect xml:id="serversideinstallation-testing-connections">
1388 <title>Testing Connections to Evergreen</title>
1389 <para>Once you have installed and started Evergreen, test your connection to
1390 Evergreen. As the <systemitem class="username">opensrf</systemitem> user start the
1391 <command>srfsh</command> application and try logging onto the Evergreen server using the
1392 default administrator username and password. Following is sample output generated by
1393 executing <command>srfsh</command> after a successful Evergreen installation.
1394 For help with <command>srfsh</command> commands, type <userinput>help</userinput>
1395 at the prompt:</para>
1397 <userinput>/openils/bin/srfsh</userinput>
1398 <prompt>srfsh%</prompt>
1399 <userinput>login admin open-ils</userinput>
1400 <prompt>Received Data: "250bf1518c7527a03249858687714376"</prompt>
1401 <prompt>------------------------------------</prompt>
1402 <prompt>Request Completed Successfully</prompt>
1403 <prompt>Request Time in seconds: 0.045286</prompt>
1404 <prompt>------------------------------------</prompt>
1405 <prompt>Received Data: {</prompt>
1406 <prompt> "ilsevent":0,</prompt>
1407 <prompt> "textcode":"SUCCESS",</prompt>
1408 <prompt> "desc":" ",</prompt>
1409 <prompt> "pid":21616,</prompt>
1410 <prompt> "stacktrace":"oils_auth.c:304",</prompt>
1411 <prompt> "payload":{</prompt>
1412 <prompt> "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",</prompt>
1413 <prompt> "authtime":420</prompt>
1416 <prompt>------------------------------------</prompt>
1417 <prompt>Request Completed Successfully</prompt>
1418 <prompt>Request Time in seconds: 1.336568</prompt>
1419 <prompt>------------------------------------</prompt>
1421 <para>If this does not work, try the following:</para>
1423 <listitem>As the <systemitem class="username">opensrf</systemitem> user, run the
1424 script <filename>Open-ILS/src/support-scripts/settings-tester.pl</filename> to
1425 see if it finds any system configuration problems. If the output of
1426 <command>settings-tester.pl</command> does not help you find the problem, please
1427 do not make any significant changes to your configuration.</listitem>
1428 <listitem>Follow the steps in the troubleshooting guide in
1429 <xref linkend="troubleshooting"/>.</listitem>
1430 <listitem>If you have followed the entire set of installation steps listed here
1431 closely, you are probably extremely close to a working system. Gather your
1432 configuration files and log files and contact the
1433 <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
1434 list for assistance before making any drastic changes to your
1435 system configuration.</listitem>
1439 <section xml:id="serversideinstallation-running-staffclient">
1440 <title>Running the Staff Client</title>
1441 <para>You can run the Staff Client on <systemitem class="osname">Linux</systemitem> by using the
1442 application <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox
1443 version 3.0 and later on <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem> distributions).</para>
1444 <para>As the <emphasis role="bold">opensrf</emphasis> user, start the Staff Client as
1447 <userinput>xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput>
1450 <section xml:id="serversideinstallation-starting-apache-server">
1451 <title>Starting the Apache Web Server</title>
1452 <para>Once you have started Evergreen and confirmed that a basic login attempt works, you can
1453 test and start the Apache web server.</para>
1454 <para>As the <systemitem class="username">root</systemitem> user, execute the following
1455 commands. Use the command <command>restart</command> to force the new Evergreen modules to be
1456 reloaded even if the Apache server is already running. Any problems found with your
1457 configuration files should be displayed:</para>
1459 <userinput>apache2ctl configtest && /etc/init.d/apache2 restart</userinput>
1462 <section xml:id="serversideinstallation-stopping">
1463 <title>Stopping Evergreen</title>
1464 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen services
1465 by using the following command:</para>
1467 <userinput># stop the server:</userinput>
1468 <userinput># use "-l" to force hostname to be "localhost"</userinput>
1469 <userinput>osrf_ctl.sh -l -a stop_all</userinput>
1472 <section xml:id="serversideinstallation-postinstallation">
1473 <title>Post-Installation Chores</title>
1474 <para>There are a few additional steps that you must complete after Evergreen has been
1475 successfully installed and tested. These remaining chores include removing temporary changes to
1476 the Apache configuration files that helped with Evergreen installation and testing, setting up
1477 Reports, and configuring a permanent Security Certificate (SSL Key).</para>
1479 <title>Remove temporary changes from Apache configuration file</title>
1480 <para>As the <systemitem class="username">root</systemitem> user, edit the Apache
1481 configuration file <filename>/etc/apache2/sites-available/eg.conf</filename> again and
1482 make the following change:</para>
1483 <para>Uncomment the line <literal>Allow from 10.0.0.0/8</literal>, then comment out the
1484 line <literal>Allow from all</literal>. You modified this file in an earlier step as a
1485 temporary measure to expedite testing (see <xref linkend="serversideinstallation-modify-apache"/>
1486 for further information). Those changes
1487 must now be reversed in order to deny unwanted access to your CGI scripts from users on
1488 other public networks. You <emphasis role="bold">must</emphasis> secure this for a
1489 public production system.</para>
1491 <section xml:id="serversideinstallation-reports">
1492 <title>Setting Up Support For Reports</title>
1493 <para>Evergreen reports are extremely powerful but some configuration is required. See
1494 <xref linkend="report-introduction"/> for a more detailed description of Reports.</para>
1496 <title>Starting the Reporter Daemon</title>
1497 <para>Once the <emphasis>open-ils.reporter</emphasis> process is running and
1498 enabled on the gateway, you can start the reporter daemon. The reporter daemon
1499 periodically checks for requests for new reports or scheduled reports and gets
1500 them running.</para> <para>As the <emphasis role="bold">opensrf</emphasis> user,
1501 start the reporter daemon using the following command:</para>
1503 <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter</userinput>
1504 <userinput>./clark-kent.pl --daemon</userinput>
1506 <para>You can also specify other options with the reporter daemone:</para>
1508 <listitem><literal>--sleep=interval</literal>
1509 : number of seconds to sleep between checks for new reports to run; defaults to 10</listitem>
1510 <listitem><literal>--lockfile=filename</literal>
1511 : where to place the lockfile for the process; defaults to <emphasis>/tmp/reporter-LOCK</emphasis></listitem>
1512 <listitem><literal>--concurrency=integer</literal>
1513 : number of reporter daemon processes to run; defaults to "1"</listitem>
1514 <listitem><literal>--bootstrap=filename</literal>
1515 : OpenSRF bootstrap configuration file; defaults to <emphasis>/openils/conf/opensrf_core.xml</emphasis></listitem>
1519 <title>Stopping the Reporter Daemon</title>
1520 <para>To stop the Reporter daemon, you must kill the process and remove the
1521 lockfile. Assuming the daemon has just a single process and a lockfile in the default
1522 location, as the <emphasis role="bold">opensrf</emphasis> user perform the following
1523 commands to stop the Reporter daemon:</para>
1525 <userinput># find and kill the process ID</userinput>
1526 <userinput>kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`</userinput>
1527 <userinput># remove the lock file</userinput>
1528 <userinput>rm /tmp/reporter-LOCK</userinput>
1532 <section xml:id="serversideinstallation-ssl">
1533 <title>Configure a permanent SSL key</title>
1534 <para>This section describes how to get a properly signed SSL certificate.</para>
1535 <para>In a previous step, we used the command <command>openssl</command> to temporarily
1536 create a new SSL key for the Apache server. This is just a self-signed certificate and
1537 will generate warnings in the Staff Client and browser during testing and
1538 development. For a public production server you should configure or purchase a properly
1539 signed SSL certificate. For a public production server you should configure or purchase
1540 a signed SSL certificate.</para>
1543 <emphasis>The temporary SSL key was only created to expedite
1544 testing. You <emphasis role="bold"> must</emphasis> get a proper SSL
1545 certificate for a public production system.</emphasis>
1549 <primary>ZZZ-REVIEW</primary>
1550 <secondary>ADD INFO ON HOW TO GET A SIGNED SSL CERTIFICATE </secondary>
1552 <caution>ADD INFO ON HOW TO GET A SIGNED SSL CERTIFICATE </caution>
1555 <section xml:id="serversideinstallation-virtual">
1556 <title>(OPTIONAL) Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
1557 <para>This section describes the installation of Evergreen software in so-called "virtualized"
1558 software environments. Evergreen software runs as a native application on any of several
1559 well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>
1560 distributions including <systemitem class="osname">Ubuntu</systemitem> and
1561 <systemitem class="osname">Debian</systemitem> but it does not run as a native application
1562 on the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
1563 However, it is possible to execute Evergreen on a <systemitem class="osname">Windows</systemitem>
1564 host system by running it within a virtual Linux-guest installation, which itself executes
1565 on the <systemitem class="osname">Windows</systemitem> system.
1566 The <systemitem class="osname">Linux</systemitem> environment is fully emulated and acts
1567 (within limits) just as if it were executing on a real standalone system.</para>
1568 <para>This technique of emulating a <systemitem class="osname">Linux</systemitem> environment on
1569 a <systemitem class="osname">Windows</systemitem> host is a practical way to install and run an
1570 Evergreen system if it is not possible to dedicate a physical machine solely as a
1571 <systemitem class="osname">Linux</systemitem> host for Evergreen. This architecture is not
1572 recommended for large scale systems since there are performance limitations to running Evergreen
1573 in a virtualized environment. However, it is a reasonable architecture for smaller experimental
1574 systems, as a proof of concept, or as a conference-room pilot.</para>
1576 <title>Installing Virtualization Software</title>
1577 <para>As described above, Evergreen can be installed on top of an emulated
1578 <systemitem class="osname">Linux</systemitem> environment. The
1579 <systemitem class="osname">Linux</systemitem> environment, in turn, is installed
1580 on top of a software application such as <application>"VirtualBox"</application>,
1581 <application>"VMware"</application> or <application>"VirtualPC"</application> which must
1582 first be installed on the <systemitem class="osname">Windows</systemitem> system. This
1583 section contains step-by-step examples that show installing popular virtualization
1584 applications on a <systemitem class="osname">Windows</systemitem> host system. Following
1585 this section are further descriptions of installing
1586 <systemitem class="osname">Linux</systemitem> and Evergreen systems using that
1587 virtualization software.</para>
1588 <section xml:id="serversideinstallation-virtual-vbox-install">
1589 <title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
1590 <para>This section reviews installation of the
1591 <application>"VirtualBox"</application> application on
1592 <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
1593 Download <application>VirtualBox</application> from their official website:
1594 <ulink url="http://download.virtualbox.org/virtualbox/3.2.8/VirtualBox-3.2.8-64453-Win.exe">
1595 http://download.virtualbox.org/virtualbox/3.2.8/VirtualBox-3.2.8-64453-Win.exe</ulink>,
1596 then run the executable file. Continue with the steps shown in the next five
1597 figures until the software has been successfully installed:</para>
1599 <title>Starting the Windows installation file</title>
1602 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-1.png" format="PNG" scalefit="1" width="70%"/>
1605 <phrase>Starting the Windows installation file</phrase>
1610 <title>Welcome to <application>VirtualBox</application> setup wizard</title>
1613 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-2.png" format="PNG" scalefit="1" width="70%"/>
1616 <phrase>Welcome to VirtualBox setup wizard</phrase>
1621 <title>Accept the license agreement</title>
1624 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-3.png" format="PNG" scalefit="1" width="70%"/>
1627 <phrase>Accept the license agreement</phrase>
1632 <title>Waiting for files to be copied</title>
1635 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-4.png" format="PNG" scalefit="1" width="70%"/>
1638 <phrase>Waiting for files to be copied</phrase>
1643 <title>Installation is complete</title>
1646 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-5.png" format="PNG" scalefit="1" width="70%"/>
1649 <phrase>Installation is complete</phrase>
1655 <title>Installing <application>"VMware"</application> Virtualization Software</title>
1656 <para>This section reviews installation of the
1657 <application>"VMware"</application> application on <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. Download
1658 <application>VMware</application> from their official website: <ulink url="">link</ulink>, then run the executable file. Continue with the steps shown
1659 in the figures until the software has been successfully installed:</para>
1661 <title>Starting the Windows installation file</title>
1664 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-1.png" format="PNG" scalefit="1" width="75%"/>
1667 <phrase>Starting the Windows installation file</phrase>
1672 <primary>ZZZ-REVIEW</primary>
1673 <secondary>ADD INFO ON VMWARE</secondary>
1675 <caution>ADD INFO ON VMWARE</caution>
1676 <para>At this point, <application>VirtualBox</application> has been installed,
1677 started for the first time, and a new virtual machine (VM) has been
1678 created. This VM is the environment in which the
1679 <systemitem class="osname">Linux</systemitem> / Evergreen installation will
1680 execute. Please continue in
1681 <xref linkend="serversideinstallation-virtual-install-linux-ev"/> with the
1682 installation of the <systemitem class="osname">Linux</systemitem> / Evergreen
1683 distribution.</para>
1686 <title>Installing <application>"VirtualPC"</application> Virtualization Software</title>
1687 <para>This section reviews installation of the
1688 <application>"VirtualPC"</application> application on <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. Download
1689 <application>VMware</application> from their official website: <ulink url="">link</ulink>, then run the executable file. Continue with the steps shown
1690 in the figures until the software has been successfully installed:</para>
1692 <title>Starting the Windows installation file</title>
1695 <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-1.png" format="PNG" scalefit="1" width="75%"/>
1698 <phrase>Starting the Windows installation file</phrase>
1703 <primary>ZZZ-REVIEW</primary>
1704 <secondary>ADD INFO ON VIRTUALPC</secondary>
1706 <caution>ADD INFO ON VIRTUALPC</caution>
1707 <para>At this point, <application>VirtualBox</application> has been installed,
1708 started for the first time, and a new virtual machine (VM) has been
1709 created. This VM is the environment in which the
1710 <systemitem class="osname">Linux</systemitem> / Evergreen installation will
1711 execute. Please continue in
1712 <xref linkend="serversideinstallation-virtual-install-linux-ev"/> with the
1713 installation of the <systemitem class="osname">Linux</systemitem> / Evergreen
1714 distribution.</para>
1717 <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">
1718 <title>Installing <systemitem class="osname">Linux</systemitem> /
1719 Evergreen on Virtualization Software</title>
1720 <para>After the virtualization software is installed and running, there are two ways to
1721 continue with installing <systemitem class="osname">Linux</systemitem> and Evergreen
1722 software in the new virtualized environment:</para>
1725 <para>Download and install a prebuilt software image that contains a
1726 working <systemitem class="osname">Linux</systemitem> / Evergreen system
1727 (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
1731 <para>Manually install a <systemitem class="osname">Linux</systemitem>
1732 guest system, then manually install Evergreen on it (see
1733 <xref linkend="serversideinstall-virtual-manual"/> for details)</para>
1736 <para>We review each method in the following sections.</para>
1737 <section xml:id="serversideinstall-virtual-prebuilt">
1738 <title>Download and install a prebuilt software image</title>
1739 <para>You can download a prebuilt software image that, when installed with your
1740 virtualization software, emulates a
1741 <systemitem class="osname">Linux</systemitem> guest system containing a running
1742 Evergreen distribution. The image is essentially a snapshot of a hard disk from
1743 a fully configured, functional <systemitem class="osname">Linux</systemitem>
1744 system with Evergreen already installed.</para>
1745 <para>We recommend this approach if you wish to get Evergreen running quickly
1746 with minimal attention to configuration. After reviewing only a few
1747 configuration details you can have a working Evergreen system that integrates
1748 smoothly with the rest of your network. See
1749 <xref linkend="serversideinstall-virtual-versions"/> for a list of prebuilt
1750 software images that are currently available to download and install</para>
1751 <note>DISCLAIMER: The following virtual images have been contributed by members
1752 of the Evergreen community for the purposes of testing, evaluation, training,
1753 and development.</note>
1754 <table xml:id="serversideinstall-virtual-versions">
1755 <title>Linux / Evergreen Virtual Images</title>
1756 <tgroup align="left" cols="4" colsep="1" rowsep="1">
1759 <entry>Linux Version</entry>
1760 <entry>Evergreen Version</entry>
1761 <entry>Image</entry>
1762 <entry>Comments</entry>
1767 <entry>Debian lenny (5.0)</entry>
1768 <entry>1.6.0.1</entry>
1770 <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip"> download </ulink>
1772 <entry>VirtualBox image</entry>
1775 <entry>Ubuntu karmic koala (9.10)</entry>
1776 <entry>1.6.0.0</entry>
1778 <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip"> download </ulink>
1780 <entry>VirtualBox image</entry>
1783 <entry>Ubuntu hardy heron (8.04)</entry>
1784 <entry>1.2.3.1</entry>
1786 <ulink url="http://open-ils.org/dokuwiki/doku.php?id=server:1.2:ubuntu804:readme"> download </ulink>
1788 <entry>VirtualBox image; no preloaded data</entry>
1791 <entry>Debian etch (4.0)</entry>
1792 <entry>1.2.2.3</entry>
1794 <ulink url="http://open-ils.org/dokuwiki/doku.php?id=vmware:debian"> download </ulink>
1796 <entry>VMware image; preloaded with 13,000 Gutenberg records</entry>
1799 <entry>Ubuntu gutsy gibbon (7.10)</entry>
1800 <entry>1.2.1.4</entry>
1802 <ulink url="http://www.open-ils.org/downloads/vmware/Evergreen_1.2.1.4_on_Ubuntu_7.10.zip"> download </ulink>
1804 <entry>VMware image</entry>
1807 <entry>Gentoo</entry>
1808 <entry>1.1.5</entry>
1810 <ulink url="http://www.open-ils.org/~denials/Evergreen_1.1.5_Gentoo_x86.zip"> download </ulink>
1812 <entry>VMware image</entry>
1818 <primary>ZZZ-REVIEW</primary>
1819 <secondary>EXPAND LIST OF OTHER PREBUILT IMAGES</secondary>
1821 <caution>EXPAND LIST OF OTHER PREBUILT IMAGES</caution>
1822 <para>For the following example, we have already installed the
1823 <application>VirtualBox</application> application (see <xref linkend="serversideinstallation-virtual-vbox-install"/> for details). Continue
1824 with the steps as shown; refer to the accompanying figures for further
1828 <para>Start VirtualBox for the first time and select
1829 <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media
1830 Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>
1831 to locate the prebuilt software image just downloaded (the
1832 example shows it was extracted from the original
1833 <literal>.ZIP</literal> file into a temporary directory
1834 <literal>C:\temp</literal>).
1835 See <xref linkend="serversideinstallation-virtual-vm-install-2"/>
1839 <para>After selecting the file, click
1840 <guibutton>Open</guibutton> to import it (see <xref linkend="serversideinstallation-virtual-vm-install-3"/> for
1844 <para>Then click <guibutton>OK</guibutton> to save the selection
1845 and return to the VirtualBox Media Manager (see <xref linkend="serversideinstallation-virtual-vm-install-4"/> for
1849 <para>Click <guibutton>New</guibutton> to start the "Virtual
1850 Machine Wizard", then <guibutton>Next</guibutton> to continue
1851 and create a new virtual machine (VM) <xref linkend="serversideinstallation-virtual-vm-install-5"/>).</para>
1854 <para>Create a new name for the VM and set the operating system
1855 type, then click <guibutton>Next</guibutton> (see <xref linkend="serversideinstallation-virtual-vm-install-6"/>).</para>
1858 <para>Set the memory size (we chose the default value of 512Mb),
1859 then click <guibutton>Next</guibutton> (see <xref linkend="serversideinstallation-virtual-vm-install-7"/>).</para>
1862 <para>Edit the Virtual Hard Disk configuration settings; click
1863 the radio boxes "Boot Hard Disk" and "Use existing hard disk"
1864 and ensure that the disk name "Evergreen1601_DebianLenny.vmdk"
1865 is selected. Click <guibutton>Finish</guibutton> to finish the
1866 setup (see <xref linkend="serversideinstallation-virtual-vm-install-8"/>).</para>
1869 <para>Install the <application>VirtualBox Guest
1870 Additions</application> (really a required upgrade to
1873 <primary>ZZZ-REVIEW</primary>
1874 <secondary>ADD INFO ON INSTALLING VIRTUALBOX GUEST ADDITIONS</secondary>
1876 <caution>ADD INFO ON INSTALLING VIRTUALBOX GUEST ADDITIONS</caution>
1879 <para>Return to VirtualBox and see the summary of the VM just
1880 created. Click <guibutton>Start</guibutton> to boot the new VM
1881 (see <xref linkend="serversideinstallation-virtual-vm-install-9"/>).</para>
1884 <para>See the start of the <systemitem class="osname">Linux</systemitem> boot sequence. Choose "Debian
1885 Gnu/Linux, kernel 2.6.26-2-686" from the startup menu and type
1886 <guibutton>Enter</guibutton> to start <systemitem class="osname">Linux</systemitem> and Evergreen (see <xref linkend="serversideinstallation-virtual-vm-install-11"/>). After
1887 some delay you should see the command line prompt:
1888 <literal>debian-lenny login:</literal> . Log in with username
1889 <literal>root</literal> and password
1890 <literal>evergreen</literal> to continue (see <xref linkend="serversideinstallation-virtual-vm-install-14"/>).</para>
1893 <para>At this point you have a running <systemitem class="osname">Linux</systemitem> / Evergreen system. If you need to modify the
1894 Evergreen configuration in any way, review the standard Evergreen installation
1895 instructions in <xref linkend="serversideinstallation-ubuntudebian"/> that deal
1896 with configuration.</para>
1897 <figure xml:id="serversideinstallation-virtual-vm-install-2">
1898 <title>Starting <application>VirtualBox</application> for the first time</title>
1901 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-2.png" format="PNG" scalefit="1" width="70%"/>
1904 <phrase>Starting VirtualBox for the first time</phrase>
1908 <figure xml:id="serversideinstallation-virtual-vm-install-3">
1909 <title>Selecting the software image in Virtual Media Manager</title>
1912 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-3.png" format="PNG" scalefit="1" width="70%"/>
1915 <phrase>Selecting the software image in Virtual Media Manager</phrase>
1919 <figure xml:id="serversideinstallation-virtual-vm-install-4">
1920 <title>New software image added to <application>VirtualBox</application></title>
1923 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-4.png" format="PNG" scalefit="1" width="75%"/>
1926 <phrase>New software image added to VirtualBox</phrase>
1930 <figure xml:id="serversideinstallation-virtual-vm-install-5">
1931 <title>Creating a new VM</title>
1934 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-5.png" format="PNG" scalefit="1" width="75%"/>
1937 <phrase>Creating a new VM</phrase>
1941 <figure xml:id="serversideinstallation-virtual-vm-install-6">
1942 <title>Setting the VM name and OS type</title>
1945 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-6.png" format="PNG" scalefit="1" width="75%"/>
1948 <phrase>Setting the VM name and OS type</phrase>
1952 <figure xml:id="serversideinstallation-virtual-vm-install-7">
1953 <title>Setting memory size</title>
1956 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-7.png" format="PNG" scalefit="1" width="75%"/>
1959 <phrase>Setting memory size</phrase>
1963 <figure xml:id="serversideinstallation-virtual-vm-install-8">
1964 <title>Setting up the Virtual Hard Disk</title>
1967 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-8.png" format="PNG" scalefit="1" width="75%"/>
1970 <phrase>Setting up the Virtual Hard Disk</phrase>
1974 <figure xml:id="serversideinstallation-virtual-vm-install-9">
1975 <title>Finishing definition of new VM</title>
1978 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-9.png" format="PNG" scalefit="1" width="75%"/>
1981 <phrase>Finishing definition of new VM</phrase>
1985 <figure xml:id="serversideinstallation-virtual-vm-install-10">
1986 <title>Summary of the new VM</title>
1989 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-10.png" format="PNG" scalefit="1" width="75%"/>
1992 <phrase>Summary of the new VM</phrase>
1996 <figure xml:id="serversideinstallation-virtual-vm-install-11">
1997 <title>Selecting VM from startup menu</title>
2000 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-11.png" format="PNG" scalefit="1" width="75%"/>
2003 <phrase>Selecting VM from startup menu</phrase>
2007 <figure xml:id="serversideinstallation-virtual-vm-install-12">
2008 <title>Starting the new VM</title>
2011 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-12.png" format="PNG" scalefit="1" width="75%"/>
2014 <phrase>Starting the new VM</phrase>
2018 <figure xml:id="serversideinstallation-virtual-vm-install-13">
2019 <title>Starting the new VM (continued)</title>
2022 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-13.png" format="PNG" scalefit="1" width="75%"/>
2025 <phrase>Starting the new VM (continued)</phrase>
2029 <figure xml:id="serversideinstallation-virtual-vm-install-14">
2030 <title>Logging into the new VM</title>
2033 <imagedata fileref="../media/serversideinstallation-virtual-vm-install-14.png" format="PNG" scalefit="1" width="75%"/>
2036 <phrase>Logging into the new VM</phrase>
2041 <section xml:id="serversideinstall-virtual-manual"><title>Manually install <systemitem class="osname">Linux</systemitem> and Evergreen</title><para>You can manually install a <systemitem class="osname">Linux</systemitem>
2042 guest system and Evergreen on your virtualization software.</para><para>We recommend this approach if you need to specially configure either the
2043 <systemitem class="osname">Linux</systemitem> system or Evergreen itself. This
2044 will require a detailed review of both <systemitem class="osname">Linux</systemitem> and Evergreen configuration details. You are
2045 essentially doing a normal Evergreen installation on a <systemitem class="osname">Linux</systemitem> system; it just happens that <systemitem class="osname">Linux</systemitem> is running within a virtualized
2046 environment. Refer to <xref linkend="serversideinstallation-ubuntudebian"/> for
2047 information on the normal Evergreen installation, then continue with this
2048 section.</para> <para>For the following example, we have already installed the
2049 <application>VirtualBox</application> application (see <xref linkend="serversideinstallation-virtual-vbox-install"/> for details). Continue
2050 with the steps as shown; refer to the accompanying figures for further
2051 information:</para><procedure><step><para>Download and install a standard <systemitem class="osname">Ubuntu</systemitem> distribution in
2052 <application>"VirtualBox"</application>.</para> <para>You can
2053 download a software image of a prebuilt <systemitem class="osname">Ubuntu</systemitem> distribution and immediately
2054 import it into <application>"VirtualBox"</application> , or you
2055 can download and install</para><indexterm><primary>ZZZ-REVIEW</primary><secondary>ADD DETAILS ON MANUAL INSTALLATION OF LINUX</secondary></indexterm><caution>ADD DETAILS ON MANUAL INSTALLATION OF LINUX</caution></step><step><para>Start (boot) <systemitem class="osname">Ubuntu</systemitem>.</para><indexterm><primary>ZZZ-REVIEW</primary><secondary>ADD DETAILS ON VM LINUX BOOT SEQUENCE</secondary></indexterm><caution>ADD DETAILS ON VM LINUX BOOT SEQUENCE</caution></step><step><para>Install Evergreen on <systemitem class="osname">Ubuntu</systemitem>.</para><indexterm><primary>ZZZ-REVIEW</primary><secondary>ADD DETAILS ON MANUAL INSTALLATION OF EVERGREEN</secondary></indexterm><caution>ADD DETAILS ON MANUAL INSTALLATION OF EVERGREEN</caution></step></procedure><para>At this point, the <systemitem class="osname">Windows</systemitem> system
2056 is hosting an <systemitem class="osname">Ubuntu</systemitem> system, which
2057 itself is hosting the Evergreen distribution. So far as Evergreen is concerned,
2058 it is happily executing in a standard
2059 <systemitem class="osname">Ubuntu</systemitem> environment and behaves exactly
2060 as if it were executing on a standalone
2061 <systemitem class="osname">Ubuntu</systemitem> system.</para><para>Of course, there are limitations to how well a virtualized
2062 <systemitem class="osname">Ubuntu</systemitem> system emulates a real one.
2063 The <application>"VirtualBox"</application> application itself consumes memory,
2064 and it contributes to the CPU load on the
2065 <systemitem class="osname">Windows</systemitem> host system. The emulated
2066 <systemitem class="osname">Ubuntu</systemitem> system will have less available
2067 memory and will execute more slowly than if it were a standalone system,
2068 therefore Evergreen itself will inherit some limitations from this overall
2069 environment.</para><para>However, this technique of using a
2070 <systemitem class="osname">Windows</systemitem> host to emulate a
2071 <systemitem class="osname">Linux</systemitem> environment is a practical way
2072 to install and run an Evergreen system even if it isn't possible to dedicate a
2073 real machine solely as a <systemitem class="osname">Linux</systemitem> host for
2074 testing. This is a reasonable architecture for simple experiments, or as a proof
2075 of concept, or as a conference-room pilot.</para></section>