From 7530060ab0959a6cc98f6a809c0c1369c5a0298d Mon Sep 17 00:00:00 2001
From: Steve Sheppard <ssheps@gmail.com>
Date: Sat, 15 Jan 2011 12:30:25 -0500
Subject: [PATCH] update the section "Installing in Virtualized Linux
Environments";
---
1.6/admin/serversideinstallation.xml | 815 +++++++++++++++++++++++------------
1 file changed, 533 insertions(+), 282 deletions(-)
diff --git a/1.6/admin/serversideinstallation.xml b/1.6/admin/serversideinstallation.xml
index eccabd85e5..ffbcf7ed2d 100644
--- a/1.6/admin/serversideinstallation.xml
+++ b/1.6/admin/serversideinstallation.xml
@@ -20,8 +20,8 @@
Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
<emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
- <application>"VirtualBox"</application>, or <application>"VMware"</application>, or
- <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>
+ <application>"VirtualBox"</application> or <application>"VMware"</application>
+ to emulate a <systemitem class="osname">Linux</systemitem>
environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem>
systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
<application>"VMware"</application>). More information on virtualized environments can be found in
@@ -145,12 +145,12 @@
In the following example, the default shell for the
<systemitem class="username">opensrf</systemitem> user is automatically set
to <command>/bin/bash</command> to inherit a reasonable environment:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
useradd -m -s /bin/bash opensrf
passwd opensrf</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Download and Unpack Latest OpenSRF Version</title>
@@ -164,13 +164,13 @@
the directory <filename class="directory">/home/opensrf</filename> then download
and extract OpenSRF. The new subdirectory
<filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /home/opensrf
wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz
tar zxf OpenSRF-1.4.0.tar.gz</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Install Prerequisites to Build OpenSRF</title>
@@ -185,12 +185,12 @@
distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> .
For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/OpenSRF-1.4.0
make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
-</screen>
+ </screen>
<table xml:id="serversideinstallation-keywords-opensrf">
<?dbfo keep-together="always" ?>
<title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
@@ -267,13 +267,13 @@
include support for Python and Java, add the configuration
options <option>--enable-python</option> and
<option>--enable-java</option>, respectively:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /home/opensrf/OpenSRF-1.4.0
./configure --prefix=/openils --sysconfdir=/openils/conf
make</userinput>
-</screen>
+ </screen>
<para>This step will take several minutes to complete.</para>
</step>
<step>
@@ -282,12 +282,12 @@
user, return to the new OpenSRF build directory and use the
<command>make</command> utility to compile, link and install
OpenSRF:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/OpenSRF-1.4.0
make install</userinput>
-</screen>
+ </screen>
<para>This step will take several minutes to complete.</para>
</step>
<step>
@@ -300,12 +300,12 @@
new library path, then run the command
<command>ldconfig</command> to automatically read the file and
modify the system dynamic library path:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
ldconfig</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-definedomains">
<title>Define Public and Private OpenSRF Domains</title>
@@ -324,12 +324,12 @@
<indexterm>
<primary>Jabber</primary>
</indexterm>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
127.0.1.2 public.localhost public
127.0.1.3 private.localhost private</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Change File Ownerships</title>
@@ -337,11 +337,11 @@
user, change the ownership of all files installed in the
directory <filename class="directory">/openils</filename> to the
user <systemitem class="username">opensrf</systemitem>:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
chown -R opensrf:opensrf /openils</userinput>
-</screen>
+ </screen>
</step>
</substeps>
</step>
@@ -353,25 +353,25 @@
<para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
you must stop that service. As the <systemitem class="username">root</systemitem> user,
execute the following command to stop the service:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/etc/init.d/ejabberd stop</userinput>
-</screen>
+ </screen>
<para>If <systemitem class="service">ejabberd</systemitem> reports that it
is already stopped, there may have been a problem when it started back
in the installation step. If there are any remaining daemon processes such as
<systemitem class="daemon">beam</systemitem> or
<systemitem class="daemon">epmd</systemitem>
you may need to perform the following commands to kill them:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
epmd -kill
killall beam; killall beam.smp
rm /var/lib/ejabberd/*
echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
@@ -425,11 +425,11 @@
<para>As the <systemitem class="username">root</systemitem> user, restart the
<systemitem class="service">ejabberd</systemitem> service to test the
configuration changes and to register your users:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/etc/init.d/ejabberd start</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Register <systemitem class="username">router</systemitem> and
@@ -462,8 +462,8 @@
for the users <systemitem class="username">router</systemitem> and
<systemitem class="username">opensrf</systemitem> on each domain (remember to replace
<emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
# Note: the syntax for registering a user with ejabberdctl is:
# ejabberdctl register USER DOMAIN PASSWORD
@@ -471,7 +471,7 @@
ejabberdctl register router public.localhost NEWPASSWORD
ejabberdctl register opensrf private.localhost NEWPASSWORD
ejabberdctl register opensrf public.localhost NEWPASSWORD</userinput>
-</screen>
+ </screen>
<para>Note that the users <systemitem class="username">router</systemitem> and
<systemitem class="username">opensrf</systemitem> and their respective passwords
will be used again in <xref linkend="serversideinstallation-passwords"/> when
@@ -483,13 +483,13 @@
execute the following commands to create the new configuration files
<filename>/openils/conf/opensrf_core.xml</filename> and
<filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /openils/conf
cp opensrf.xml.example opensrf.xml
cp opensrf_core.xml.example opensrf_core.xml</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-passwords">
<title>Update usernames and passwords in the OpenSRF configuration file</title>
@@ -591,7 +591,7 @@
<para>to instead read:</para>
<literal>/tmp/persist.db</literal>
<para>Following is a sample modification of that portion of the file:</para>
-<programlisting language="xml"><![CDATA[
+ <programlisting language="xml"><![CDATA[
<!-- Example of an app-specific setting override -->
<opensrf.persist>
<app_settings>
@@ -618,11 +618,11 @@
to the home directory of each user who will use <command>srfsh</command>.
For instance, do the following for the
<systemitem class="username">opensrf</systemitem> user:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml</userinput>
-</screen>
+ </screen>
<para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
following changes:</para>
<itemizedlist>
@@ -653,7 +653,7 @@
</listitem>
</itemizedlist>
<para>Following is a sample of the file:</para>
-<programlisting language="xml"><![CDATA[
+ <programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<!-- This file follows the standard bootstrap config file layout -->
<!-- found in opensrf_core.xml -->
@@ -676,30 +676,30 @@
environmental variable <envar>PATH</envar> by adding a new file path to the
<systemitem class="username">opensrf</systemitem> user's shell configuration
file <filename>~/.bashrc</filename>:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Start OpenSRF</title>
<para>As the <systemitem class="username">root</systemitem> user, start the
<systemitem class="service">ejabberd</systemitem> and
<systemitem class="service">memcached</systemitem> services:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/etc/init.d/ejabberd start
/etc/init.d/memcached start</userinput>
-</screen>
+ </screen>
<para>As the <systemitem class="username">opensrf</systemitem> user,
start OpenSRF as follows:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
osrf_ctl.sh -l -a start_all</userinput>
-</screen>
+ </screen>
<para>The flag <option>-l</option> forces Evergreen to use
<systemitem class="domainname">localhost</systemitem> (your current system)
as the hostname. The flag <option>-a start_all</option> starts the other
@@ -734,19 +734,19 @@
<systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command>
utility and trying to call the <command>add</command> method on the OpenSRF
<systemitem class="service">math</systemitem> service:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/openils/bin/srfsh</userinput>
- <computeroutput>
+ <computeroutput>
srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
- <computeroutput>
+ <computeroutput>
Received Data: 4
------------------------------------
Request Completed Successfully
Request Time in seconds: 0.007519
------------------------------------</computeroutput>
-</screen>
+ </screen>
<para>For other <command>srfsh</command> commands, type in
<userinput>help</userinput> at the prompt.</para>
</step>
@@ -756,11 +756,11 @@
<command>osrf_ctl.sh</command> again. As the
<systemitem class="username">opensrf</systemitem>
user, stop OpenSRF as follows:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
osrf_ctl.sh -l -a stop_all</userinput>
-</screen>
+ </screen>
</step>
</procedure>
</section>
@@ -833,13 +833,13 @@
the directory <filename class="directory">/home/opensrf</filename> then download
and extract Evergreen. The new subdirectory
<filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename> will be created:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /home/opensrf
wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz
tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-installprereq">
<title>Install Prerequisites to Build Evergreen</title>
@@ -856,12 +856,12 @@
For example, to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would
enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
ubuntu-karmic</command>.</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/Evergreen-ILS-1.6.1.2
make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
-</screen>
+ </screen>
<table xml:id="serversideinstallation-keywords-evergreen">
<?dbfo keep-together="always" ?>
<title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
@@ -950,19 +950,19 @@
<para>You will need to install several Perl modules on the other system. As the
<systemitem class="username">root</systemitem> user install the following Perl
modules:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
# first, ensure the gcc compiler is installed:
apt-get install gcc
# then install the Perl modules:
perl -MCPAN -e shell</userinput>
- <computeroutput>
+ <computeroutput>
cpan> <userinput>install JSON::XS</userinput>
cpan> <userinput>install MARC::Record</userinput>
cpan> <userinput>install MARC::File::XML</userinput></computeroutput>
-</screen>
+ </screen>
<para>For more information on installing Perl Modules vist the official
<link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
<indexterm>
@@ -977,13 +977,13 @@
do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
containing a new library path, then run the command <command>ldconfig</command> to
automatically read the file and modify the system dynamic library path:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
echo "/usr/local/lib" >> /etc/ld.so.conf.d/osrf.conf
echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
ldconfig</userinput>
-</screen>
+ </screen>
</step>
<step performance="optional">
<title>Restart the PostgreSQL Server</title>
@@ -995,11 +995,11 @@
execute the following command (remember to replace
<emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
for example <literal>8.3</literal>):</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
/etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-configure">
<title>Configure Evergreen</title>
@@ -1008,13 +1008,13 @@
and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
<para>As the <systemitem class="username">opensrf</systemitem> user, return to
the Evergreen build directory and execute these commands:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /home/opensrf/Evergreen-ILS-1.6.1.2
./configure --prefix=/openils --sysconfdir=/openils/conf
make</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-compile">
<title>Compile, Link and Install Evergreen</title>
@@ -1022,12 +1022,12 @@
default Evergreen Staff Client.</para>
<para>As the <systemitem class="username">root</systemitem> user, return to the
Evergreen build directory and use the <command>make</command> utility as shown below:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/Evergreen-ILS-1.6.1.2
make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>
-</screen>
+ </screen>
<para>The Staff Client will also be automatically built, but you must remember
to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the
Staff Client you will use to connect to the Evergreen server.</para>
@@ -1040,12 +1040,12 @@
directory <filename class="directory">/openils/var/web/xul</filename> that points to the
subdirectory <filename class="directory">/server</filename> of the new Staff Client
build:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /openils/var/web/xul
ln -sf rel_1_6_1_2/server server</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Copy the OpenSRF Configuration Files</title>
@@ -1057,8 +1057,8 @@
to <systemitem class="username">opensrf</systemitem>.
As the <systemitem class="username">root</systemitem> user, execute the following
commands:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /openils/conf
cp opensrf.xml opensrf.xml.BAK
@@ -1067,7 +1067,7 @@
cp opensrf_core.xml.example opensrf_core.xml
cp oils_web.xml.example oils_web.xml
chown -R opensrf:opensrf /openils/</userinput>
-</screen>
+ </screen>
</step>
<step>
<title>Create and Configure PostgreSQL Database</title>
@@ -1091,25 +1091,25 @@
<para>As the <systemitem class="username">postgres</systemitem>
user on the PostgreSQL system create the PostgreSQL database,
then set some internal paths:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the postgres user:
createdb evergreen -E UTF8 -T template0
createlang plperl evergreen
createlang plperlu evergreen
createlang plpgsql evergreen</userinput>
-</screen>
+ </screen>
<para>Continue as the <systemitem class="username">postgres</systemitem> user
and execute the SQL scripts as shown below (remember to adjust the paths as needed,
where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL
version, for example <literal>8.3</literal>).</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the postgres user:
psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql evergreen
psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql evergreen</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-postgresqlcreateuser">
<title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
@@ -1118,14 +1118,14 @@
named <systemitem class="username">evergreen</systemitem> and
assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>
with an appropriate new password):</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the postgres user:
createuser -P -s evergreen</userinput>
- <computeroutput>
+ <computeroutput>
Enter password for new role: <userinput>NEWPASSWORD</userinput>
Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
-</screen>
+ </screen>
</step>
<step>
<title>Create database schema</title>
@@ -1137,15 +1137,15 @@
the following commands and replace <emphasis>HOSTNAME, PORT,
PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
values:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/Evergreen-ILS-1.6.1.2
perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
--service all --create-schema --create-bootstrap --create-offline \
--hostname HOSTNAME --port PORT \
--user evergreen --password PASSWORD --database DATABASENAME</userinput>
-</screen>
+ </screen>
<para>On most systems, <emphasis>HOSTNAME</emphasis> will be
<emphasis role="bold">localhost</emphasis> and
<emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
@@ -1184,13 +1184,13 @@
<indexterm>
<primary>Apache modules</primary>
</indexterm>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
a2enmod ssl # enable mod_ssl
a2enmod rewrite # enable mod_rewrite
a2enmod expires # enable mod_expires</userinput>
-</screen>
+ </screen>
<para>As the commands execute, you may see warnings similar to:
<literal>Module SOMEMODULE already enabled</literal> but you can
safely ignore them.</para>
@@ -1201,14 +1201,14 @@
Evergreen installation directory to the Apache directory. As the
<systemitem class="username">root</systemitem> user, perform the
following commands:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
cd /home/opensrf/Evergreen-ILS-1.6.1.2
cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/
cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
cp Open-ILS/examples/apache/startup.pl /etc/apache2/</userinput>
-</screen>
+ </screen>
</step>
<step xml:id="serversideinstallation-createsslcertificate">
<title>Create a Security Certificate</title>
@@ -1219,13 +1219,13 @@
accept the warnings in the Staff Client and browser during testing and
development. As the <systemitem class="username">root</systemitem> user,
perform the following commands:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
mkdir /etc/apache2/ssl
cd /etc/apache2/ssl
openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
-</screen>
+ </screen>
<para>You will be prompted for several items of information; enter
the appropriate information for each item. The new files
<filename>server.crt</filename> and <filename>server.key</filename> will
@@ -1250,7 +1250,7 @@
<para>In the section
<literal><Directory "/openils/var/cgi-bin"></literal>
replace the line:</para>
- <literal>Allow from 10.0.0.0/8</literal>
+ <literal>Allow from 10.0.0.0/8</literal>
<para>with the line:</para>
<literal>Allow from all</literal>
<warning>This change allows access to your configuration
@@ -1293,17 +1293,17 @@
<systemitem class="osname">Debian Lenny</systemitem>, as
the <systemitem class="username">root</systemitem> user,
edit the Apache configuration file and change the lines:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
export APACHE_RUN_USER=www-data
export APACHE_RUN_GROUP=www-data</userinput>
-</screen>
+ </screen>
<para>to instead read:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
export APACHE_RUN_USER=opensrf
export APACHE_RUN_GROUP=opensrf</userinput>
-</screen>
+ </screen>
</listitem>
<listitem>
<para>As the
@@ -1313,11 +1313,11 @@
modify the value for <literal>KeepAliveTimeout</literal>
and <literal>MaxKeepAliveRequests</literal> to match
the following:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
KeepAliveTimeout 1
MaxKeepAliveRequests 100</userinput>
-</screen>
+ </screen>
</listitem>
<listitem>
<para>Further configuration changes to Apache may be
@@ -1331,7 +1331,7 @@
and modify the section related to <emphasis>prefork
configuration</emphasis> to suit the load on your
system:</para>
-<programlisting language="xml"><![CDATA[
+ <programlisting language="xml"><![CDATA[
<IfModule mpm_prefork_module>
StartServers 20
MinSpareServers 5
@@ -1350,15 +1350,15 @@
following Apache configuration commands to disable the default
<emphasis>It Works</emphasis> web page and enable the Evergreen
web site, and then restart the Apache server:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
# disable/enable web sites
a2dissite default
a2ensite eg.conf
# restart the server
/etc/init.d/apache2 reload</userinput>
-</screen>
+ </screen>
</step>
</substeps>
</step>
@@ -1468,11 +1468,11 @@
<para>Modify the permissions in the directory
<filename class="directory">/openils/var/cgi-bin</filename>
to make the files executable:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
chmod 755 /openils/var/cgi-bin/*.cgi</userinput>
-</screen>
+ </screen>
</listitem>
<listitem>
<para>As the <systemitem class="username">opensrf</systemitem> user,
@@ -1485,12 +1485,12 @@
<emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &&
return </literal>. This will allow headless (scripted) logins to load the
correct environment.</note>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc
. ~/.bashrc</userinput>
-</screen>
+ </screen>
</listitem>
</itemizedlist>
</step>
@@ -1513,21 +1513,21 @@
<para>As the <systemitem class="username">root</systemitem>
user, start the <systemitem class="service">ejabberd</systemitem> and
<systemitem class="service">memcached</systemitem> services as follows:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/etc/init.d/ejabberd start
/etc/init.d/memcached start</userinput>
-</screen>
+ </screen>
</step>
<step>
<para>As the <systemitem class="username">opensrf</systemitem> user,
start Evergreen as follows:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
osrf_ctl.sh -l -a start_all</userinput>
-</screen>
+ </screen>
<para>The flag <option>-l</option> forces Evergreen to use
<systemitem class="domainname">localhost</systemitem> (your current system)
as the hostname. The flag <option>-a start_all</option> starts the other
@@ -1574,12 +1574,12 @@
changes to the library hierarchy.</para>
<para>As the <systemitem class="username">opensrf</systemitem> user, execute the
following command and review the results:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /openils/bin
./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
- <computeroutput>
+ <computeroutput>
Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'
Updating fieldmapper
Updating web_fieldmapper
@@ -1596,16 +1596,16 @@
Refreshing proximity of org units
Successfully updated the organization proximity
Done</computeroutput>
-</screen>
+ </screen>
</step>
<step>
<para>As the <systemitem class="username">root</systemitem> user, restart the
Apache Web server:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
/etc/init.d/apache2 restart</userinput>
-</screen>
+ </screen>
<note>If the Apache Web server was running when you started the OpenSRF
services, you might not be able to successfully log into the OPAC or Staff
Client until the Apache Web server has been restarted.</note>
@@ -1626,11 +1626,11 @@
<command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
As the <systemitem class="username">opensrf</systemitem> user,
execute the following commands to test your Evergreen connection:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
/openils/bin/srfsh</userinput>
- <computeroutput>
+ <computeroutput>
srfsh% <userinput>login admin open-ils</userinput>
Received Data: "250bf1518c7527a03249858687714376"
------------------------------------
@@ -1651,21 +1651,20 @@
------------------------------------
Request Completed Successfully
Request Time in seconds: 1.336568
- ------------------------------------
- </computeroutput>
-</screen>
+ ------------------------------------</computeroutput>
+ </screen>
<para>If this does not work, try the following:</para>
<itemizedlist>
<listitem>
<para>As the <systemitem class="username">opensrf</systemitem> user, run the
<filename>settings-tester.pl</filename> utility to review your Evergreen
installation for any system configuration problems:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user:
cd /home/opensrf
./Evergreen-ILS-1.6.1.2/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
-</screen>
+ </screen>
<para>If the output of <command>settings-tester.pl</command> does not help you
find the problem, please do not make any significant changes to your
configuration.</para>
@@ -1693,11 +1692,11 @@
version 3.0 and later on Ubuntu and Debian distributions).</para>
<para>As the <systemitem class="username">root</systemitem> user, start the Staff Client
as shown:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
xulrunner /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/xul/staff_client/build/application.ini</userinput>
-</screen>
+ </screen>
<para>A login screen for the Staff Client similar to this should appear:</para>
<mediaobject>
<alt>Logging into the Staff Client</alt>
@@ -1743,11 +1742,11 @@
commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen
modules to be reloaded even if the Apache server is already running. Any problems found
with your configuration files should be displayed:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the root user:
apache2ctl configtest && /etc/init.d/apache2 restart</userinput>
-</screen>
+ </screen>
</simplesect>
<simplesect xml:id="serversideinstallation-stopping">
<title>Stopping Evergreen</title>
@@ -1756,12 +1755,12 @@
Evergreen services.</para>
<para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen
services by using the following command:</para>
-<screen>
- <userinput>
+ <screen>
+ <userinput>
# as the opensrf user
# stop the server; use "-l" to force hostname to be "localhost"
osrf_ctl.sh -l -a stop_all</userinput>
-</screen>
+ </screen>
<note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the
<option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the
fully qualified domain name for the system on which it will execute. That hostname may
@@ -1799,7 +1798,7 @@
<para>You used the command <command>openssl</command> in an earlier step to
temporarily create a new SSL key for the Apache server (see
<xref linkend="serversideinstallation-createsslcertificate"/> for further
- information). This self-signed security certificate was adequate during
+ information). This self-signed security certificate was adequate during
testing and development, but will continue to generate warnings in the Staff
Client and browser. For a public production server you should configure or
purchase a signed SSL certificate.</para>
@@ -1836,105 +1835,168 @@
</section>
<section xml:id="serversideinstallation-virtual">
<title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
- <para>This section describes the installation of Evergreen software in so-called "virtualized"
- software environments. Evergreen software runs as a native application on any of several
- well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>
- distributions including <systemitem class="osname">Ubuntu</systemitem> and
- <systemitem class="osname">Debian</systemitem> but it does not run as a native application
- on the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
- However, it is possible to execute Evergreen on a <systemitem class="osname">Windows</systemitem>
- host system by running it within a virtual Linux-guest installation, which itself executes
- on the <systemitem class="osname">Windows</systemitem> system.
- The <systemitem class="osname">Linux</systemitem> environment is fully emulated and acts
- (within limits) just as if it were executing on a real standalone system.</para>
- <para>This technique of emulating a <systemitem class="osname">Linux</systemitem> environment on
- a <systemitem class="osname">Windows</systemitem> host is a practical way to install and run an
- Evergreen system if it is not possible to dedicate a physical machine solely as a
- <systemitem class="osname">Linux</systemitem> host for Evergreen. This architecture is not
- recommended for large scale systems since there are performance limitations to running Evergreen
- in a virtualized environment. However, it is a reasonable architecture for smaller experimental
- systems, as a proof of concept, or as a conference-room pilot.</para>
- <simplesect>
+ <para>This section describes the installation of Evergreen software in so-called
+ "virtualized" software environments running on the
+ <systemitem class="osname">Microsoft Windows</systemitem> operating system.
+ Evergreen software runs as a native application
+ on any of several well-known x86 (32-bit) and x86-64 (64-bit)
+ <systemitem class="osname">Linux</systemitem> distributions including
+ <systemitem class="osname">Ubuntu</systemitem> and
+ <systemitem class="osname">Debian</systemitem>, but will not run directly on
+ the <systemitem class="osname">Microsoft Windows</systemitem> operating system.
+ Instead, Evergreen executes within an encapsulated virtual
+ <systemitem class="osname">Linux</systemitem> "guest" installation,
+ which itself executes directly on <systemitem class="osname">Windows</systemitem>.
+ The <systemitem class="osname">Linux</systemitem> environment is fully emulated
+ and acts (within limits) just as if it were executing on a real standalone system.</para>
+ <para>This technique of emulating a <systemitem class="osname">Linux</systemitem>
+ environment on a <systemitem class="osname">Windows</systemitem> host is a practical
+ way to install and run an Evergreen system if it is not possible to dedicate a
+ physical machine solely as a <systemitem class="osname">Linux</systemitem> host, but
+ the architecture is not recommended for large scale systems. There are performance
+ limitations to running Evergreen in a virtualized environment, since the
+ virtualization application itself consumes memory and contributes to the CPU load on
+ the <systemitem class="osname">Windows</systemitem> host system. The emulated
+ Evergreen environment will execute more slowly than if it were a standalone system.
+ However, it is still a reasonable architecture for smaller experimental systems or as
+ a proof of concept.</para>
+ <section>
<title>Installing Virtualization Software</title>
<para>As described above, Evergreen can be installed on top of an emulated
- <systemitem class="osname">Linux</systemitem> environment. The
- <systemitem class="osname">Linux</systemitem> environment, in turn, is installed
- on top of a software application such as <application>"VirtualBox"</application>,
- <application>"VMware"</application> or <application>"VirtualPC"</application> which must
- first be installed on the <systemitem class="osname">Windows</systemitem> system. This
- section contains step-by-step examples that show installing popular virtualization
- applications on a <systemitem class="osname">Windows</systemitem> host system. Following
- this section are further descriptions of installing
- <systemitem class="osname">Linux</systemitem> and Evergreen systems using that
- virtualization software.</para>
- <section>
+ <systemitem class="osname">Linux</systemitem> environment which, in turn,
+ is installed on top of a software application such as
+ <application>"VirtualBox"</application> or <application>"VMware"</application>
+ executing on <systemitem class="osname">Windows</systemitem>.
+ This section contains step-by-step examples on installing popular virtualization
+ applications on a <systemitem class="osname">Windows</systemitem> host system.
+ Following this section are further descriptions of installing
+ <systemitem class="osname">Linux</systemitem> and Evergreen systems on top
+ of that virtualization software.</para>
+ <section xml:id="serversideinstallation-virtual-vbox-install">
<title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
<para>This section reviews installation of the
<application>"VirtualBox"</application> application on
- <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
- Download the latest edition of <application>VirtualBox</application> from their official website:
- <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link>
- and follow the on screen instructions to install the software.</para>
+ <systemitem class="osname">WindowsXP Professional (SP3)</systemitem>.
+ Download the latest version of the
+ <application>VirtualBox</application> from the official website:
+ <ulink url="http://www.virtualbox.org/wiki/Downloads">
+ http://www.virtualbox.org/wiki/Downloads</ulink>,
+ then run the executable file. Continue with the steps shown in the
+ next five figures until the software has been successfully
+ installed. The following example shows the installation of VirtualBox
+ version 3.8.2 .</para>
+ <figure>
+ <title>Starting the Windows installation of <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-1.png" scalefit="0" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Welcome to <application>VirtualBox</application> setup wizard</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-2.png" scalefit="0" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Accept the license agreement</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-3.png" scalefit="0" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Waiting for installation to complete</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-4.png" scalefit="0" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Installation is complete; start <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vbox-install-5.png" scalefit="0" width="70%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>At this point, <application>VirtualBox</application> has been
+ installed and started for the first time. Please continue with
+ <xref linkend="serversideinstallation-virtual-install-linux-ev"/>
+ for further instructions on the next step: installing the
+ <systemitem class="osname">Linux</systemitem> / Evergreen distribution.</para>
</section>
<section>
- <title>Installing VMware Virtualization Software</title>
- <indexterm>
- <primary>virtualization software</primary>
- <secondary>VMware</secondary>
- </indexterm>
- <para>This section reviews installation of the
- <application>"VMware"</application> application on
- <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>.
- Find and Download the free virtual machine software of from the VMware
- official website:
- <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink>
- and follow the on-screen instructions.</para>
+ <title>Installing <application>"VMware"</application> Virtualization Software</title>
+ <para>For instructions on installing <application>VMware</application>,
+ visit the official website <ulink url="http://www.vmware.com/">
+ http://www.vmware.com/</ulink>. Then continue with
+ <xref linkend="serversideinstallation-virtual-install-linux-ev"/> for
+ further instructions on the next step: installing the
+ <systemitem class="osname">Linux</systemitem> / Evergreen distribution.</para>
</section>
- </simplesect>
- <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">
- <title>Installing <systemitem class="osname">Linux</systemitem> /
- Evergreen on Virtualization Software</title>
- <para>After the virtualization software is installed and running, there are two ways to
- continue with installing <systemitem class="osname">Linux</systemitem> and Evergreen
- software in the new virtualized environment:</para>
+ </section>
+ <section xml:id="serversideinstallation-virtual-install-linux-ev">
+ <title>Installing <systemitem class="osname">Linux</systemitem>
+ / Evergreen on Virtualization Software</title>
+ <para>After the virtualization software is installed and running, there are
+ two ways to continue with installing
+ <systemitem class="osname">Linux</systemitem> and Evergreen software in the new
+ virtualized environment:</para>
<orderedlist>
<listitem>
- <para>Download and install a prebuilt software image that contains a
- working <systemitem class="osname">Linux</systemitem> / Evergreen system
- (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
+ <para>Download and install a prebuilt software image that
+ contains a working
+ <systemitem class="osname">Linux</systemitem> / Evergreen
+ system (see
+ <xref linkend="serversideinstall-virtual-prebuilt"/> for
details)</para>
</listitem>
<listitem>
- <para>Manually install a <systemitem class="osname">Linux</systemitem>
- guest system, then manually install Evergreen on it.</para>
+ <para>Manually install a
+ <systemitem class="osname">Linux</systemitem> guest system,
+ then manually install Evergreen on it (see
+ <xref linkend="serversideinstall-virtual-manual"/> for
+ details)</para>
</listitem>
</orderedlist>
<para>We review each method in the following sections.</para>
<section xml:id="serversideinstall-virtual-prebuilt">
<title>Download and install a prebuilt software image</title>
- <para>You can download a prebuilt software image that, when installed with your
- virtualization software, emulates a
- <systemitem class="osname">Linux</systemitem> guest system containing a running
- Evergreen distribution. The image is essentially a snapshot of a hard disk from
- a fully configured, functional <systemitem class="osname">Linux</systemitem>
- system with Evergreen already installed.</para>
- <para>We recommend this approach if you wish to get Evergreen running quickly
- with minimal attention to configuration. After reviewing only a few
- configuration details you can have a working Evergreen system that integrates
- smoothly with the rest of your network. See
- <xref linkend="serversideinstall-virtual-versions"/> for a list of prebuilt
- software images that are currently available to download and install</para>
- <note>DISCLAIMER: The following virtual images have been contributed by members
- of the Evergreen community for the purposes of testing, evaluation, training,
- and development.</note>
+ <para>You can download a prebuilt software image that, when installed
+ on your virtualization software, emulates a
+ <systemitem class="osname">Linux</systemitem> guest system containing
+ a running Evergreen distribution. The image is essentially a snapshot
+ of a hard disk from a fully configured, functional
+ <systemitem class="osname">Linux</systemitem> system with Evergreen
+ already installed. It is even possible to install a software image
+ that is preloaded with useful data, e.g., Gutenberg records.</para>
+ <para>We recommend this approach if you wish to get Evergreen running
+ quickly with minimal attention to configuration. After adjusting only
+ a few configuration details you can have a working Evergreen system
+ that integrates smoothly with the rest of your network. See
+ <xref linkend="serversideinstall-virtual-versions"/> for a list of
+ prebuilt software images that are currently available to download and
+ install.</para>
+ <note>Evergreen servers and staff clients must match. For example, if
+ you are running server version 1.4.0.1, you should use version 1.4.0.1
+ of the staff client.</note>
+ <note>DISCLAIMER: The following virtual images have been contributed
+ by members of the Evergreen community for the purposes of testing,
+ evaluation, training, and development.</note>
<table xml:id="serversideinstall-virtual-versions">
<?dbfo keep-together="always" ?>
<title>Linux / Evergreen Virtual Images</title>
<tgroup align="left" cols="4" colsep="1" rowsep="1">
- <colspec colname="linux_version" colnum="1" colwidth="1.0*"/>
- <colspec colname="evergreen_version" colnum="2" colwidth="1.0*"/>
- <colspec colname="image" colnum="3" colwidth="3.0*"/>
- <colspec colname="comments" colnum="4" colwidth="1.0*"/>
+ <colspec colname="Linux_version" colnum="1" colwidth="2*"/>
+ <colspec colname="EV_version" colnum="2" colwidth="1*"/>
+ <colspec colname="download_link" colnum="3" colwidth="1*"/>
+ <colspec colname="comments" colnum="4" colwidth="3*"/>
<thead>
<row>
<entry>Linux Version</entry>
@@ -1945,88 +2007,277 @@
</thead>
<tbody>
<row>
- <entry>Debian lenny (5.0)</entry>
+ <entry>Debian "Lenny" (5.0)</entry>
+ <entry>1.6.1.4</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen_1_6_1_4_Lenny.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Debian "Lenny" (5.0)</entry>
<entry>1.6.0.1</entry>
<entry>
- <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip"> download </ulink>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip">
+ download</ulink>
</entry>
- <entry>VirtualBox image</entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
</row>
<row>
- <entry>Ubuntu karmic koala (9.10)</entry>
+ <entry>Ubuntu "Karmic Koala" (9.10)</entry>
<entry>1.6.0.0</entry>
<entry>
- <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip"> download </ulink>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Ubuntu "Hardy Heron" (8.04)</entry>
+ <entry>1.2.3.1</entry>
+ <entry>
+ <ulink url="http://open-ils.org/~denials/Ubuntu804.zip">
+ download</ulink>
+ </entry>
+ <entry>VirtualBox image (no preloaded data)</entry>
+ </row>
+ <row>
+ <entry>Debian Etch (4.0)</entry>
+ <entry>1.2.2.3</entry>
+ <entry>
+ <ulink url="http://evergreen-ils.org/~denials/Evergreen_Debian_1.2.2.3.zip">
+ download</ulink>
+ </entry>
+ <entry>VMware image (preloaded with 13,000 Gutenberg records)</entry>
+ </row>
+ <row>
+ <entry>Ubuntu "Gutsy Gibbon" (7.10)</entry>
+ <entry>1.2.1.4</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/downloads/vmware/Evergreen_1.2.1.4_on_Ubuntu_7.10.zip">
+ download</ulink>
+ </entry>
+ <entry>VMware image, contributed by
+ <ulink url="http://library.calvin.edu/">
+ the Hekman Library, Calvin College</ulink></entry>
+ </row>
+ <row>
+ <entry>Gentoo</entry>
+ <entry>1.1.5</entry>
+ <entry>
+ <ulink url="http://www.open-ils.org/~denials/Evergreen_1.1.5_Gentoo_x86.zip">
+ download </ulink>
</entry>
- <entry>VirtualBox image</entry>
+ <entry>VMware image on Gentoo, courtesy of
+ <ulink url="http://coffeecode.net/">Dan Scott</ulink>,
+ <ulink url="http://laurentian.ca/library">Laurentian University</ulink>
+ (file size is 1.1GB)</entry>
</row>
</tbody>
</tgroup>
</table>
+ <para>For the following example, we have already installed the
+ <application>VirtualBox</application> application (see
+ <xref linkend="serversideinstallation-virtual-vbox-install"/> for details).
+ Continue with the steps as shown; refer to the accompanying figures for further
+ information:</para>
<procedure>
- <title>VirtualBox Example</title>
- <indexterm>
- <primary>virtualization software</primary>
- <secondary>VirtualBox</secondary>
- </indexterm>
<step>
<para>Start VirtualBox for the first time and select
<menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>
to locate the prebuilt software image just downloaded (the
example shows it was extracted from the original
- <filename class="extension">zip</filename> file into a temporary directory
- <filename class="directory">C:\temp</filename>).</para>
+ <literal>.ZIP</literal> file into a temporary directory
+ <literal>C:\temp</literal>). See
+ <xref linkend="serversideinstallation-virtual-vm-install-2"/>
+ for details.</para>
</step>
<step>
- <para>After selecting the file, click <guibutton>'Open'</guibutton> to import it.</para>
+ <para>After selecting the file, click
+ <guibutton>Open</guibutton> to import it (see
+ <xref linkend="serversideinstallation-virtual-vm-install-3"/>
+ for details).</para>
</step>
<step>
- <para>Then click <guibutton>'OK'</guibutton> to save the selection
- and return to the VirtualBox Media Manager</para>
+ <para>Then click <guibutton>OK</guibutton> to save the
+ selection and return to the VirtualBox Media Manager (see
+ <xref linkend="serversideinstallation-virtual-vm-install-4"/>
+ for details).</para>
</step>
<step>
- <para>Click <guibutton>'New'</guibutton>, then <guibutton>'Next'</guibutton>
- to continue and create a new virtual machine (VM).</para>
+ <para>Click <guibutton>New</guibutton> to start the "Virtual
+ Machine Wizard", then <guibutton>Next</guibutton> to continue
+ and create a new virtual machine (VM)
+ <xref linkend="serversideinstallation-virtual-vm-install-5"/>).</para>
</step>
<step>
- <para>Create a new name for the VM and set the operating system
- type, then click <guibutton>'Next'</guibutton>.</para>
+ <para>Create a new name for the VM and set the operating
+ system type, then click <guibutton>Next</guibutton> (see
+ <xref linkend="serversideinstallation-virtual-vm-install-6"/>).</para>
</step>
<step>
- <para>Set the memory size (at least 512Mb),
- then click <guibutton>'Next'</guibutton>.</para>
+ <para>Set the memory size (we chose the default value of
+ 512Mb), then click <guibutton>Next</guibutton> (see
+ <xref linkend="serversideinstallation-virtual-vm-install-7"/>).</para>
</step>
<step>
<para>Edit the Virtual Hard Disk configuration settings; click
- the radio boxes <guilabel>Boot Hard Disk</guilabel> and
- <guilabel>Use existing hard disk</guilabel>
- and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel>
- is selected. Click <guibutton>'Finish'</guibutton> to finish the
- setup.</para>
+ the radio boxes "Boot Hard Disk" and "Use existing hard disk"
+ and ensure that the disk name "Evergreen1601_DebianLenny.vmdk"
+ is selected. Click <guibutton>Finish</guibutton> to finish the
+ setup (see
+ <xref linkend="serversideinstallation-virtual-vm-install-8"/>).</para>
</step>
<step>
<para>Install the <application>VirtualBox Guest
Additions</application> (really a required upgrade to
- VirtualBox)</para>
+ VirtualBox).</para>
</step>
<step>
- <para>Return to VirtualBox and see the summary of the VM just
- created. Click <guibutton>'Start'</guibutton> to boot the new VM.</para>
+ <para>Return to VirtualBox and see the summary of the VM just created
+ (see <xref linkend="serversideinstallation-virtual-vm-install-9"/>
+ and <xref linkend="serversideinstallation-virtual-vm-install-10"/>).
+ Click <guibutton>Start</guibutton> to boot the new VM, then
+ log in with username <literal>root</literal> and
+ password <literal>evergreen</literal> to continue.</para>
</step>
+ </procedure>
+ <para>At this point you have a running
+ <systemitem class="osname">Linux</systemitem> / Evergreen system.
+ If you need to modify the Evergreen configuration in any way, review
+ the sectons of the standard Evergreen installation instructions in
+ <xref linkend="serversideinstallation-ubuntudebian"/> that deal with
+ configuration.</para>
+ <figure xml:id="serversideinstallation-virtual-vm-install-2">
+ <title>Starting <application>VirtualBox</application> for the first time</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-2.png" scalefit="0" width="60%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-3">
+ <title>Selecting the software image in Virtual Media Manager</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-3.png" scalefit="0" width="60%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-4">
+ <title>New software image added to <application>VirtualBox</application></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-4.png" scalefit="0" width="40%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-5">
+ <title>Creating a new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-5.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-6">
+ <title>Setting the VM name and OS type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-6.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-7">
+ <title>Setting memory size</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-7.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-8">
+ <title>Setting up the Virtual Hard Disk</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-8.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-9">
+ <title>Finishing definition of new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-9.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure xml:id="serversideinstallation-virtual-vm-install-10">
+ <title>Summary of the new VM</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../media/serversideinstallation-virtual-vm-install-10.png" scalefit="0" width="50%"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section xml:id="serversideinstall-virtual-manual">
+ <title>Manually install <systemitem class="osname">Linux</systemitem> and Evergreen</title>
+ <para>Instead of installing a pre-built, pre-configured virtual image
+ of <systemitem class="osname">Linux</systemitem> containing the
+ Evergreen software, you could also manually install a
+ <systemitem class="osname">Linux</systemitem> guest system, then install
+ Evergreen from scratch on that system.</para>
+ <para>We recommend this approach if you need to specially configure
+ either the <systemitem class="osname">Linux</systemitem> system or
+ Evergreen itself. This will require a detailed review of both
+ <systemitem class="osname">Linux</systemitem> and Evergreen
+ configuration details. You are 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 environment on a <systemitem class="osname">Windows</systemitem>
+ system. See <xref linkend="serversideinstallation-ubuntudebian"/> for
+ information on the normal Evergreen installation, then continue with this
+ section.</para>
+ <para>For the following example, we have already installed the
+ <application>VirtualBox</application> application (see
+ <xref linkend="serversideinstallation-virtual-vbox-install"/> for details).
+ Continue with the steps as shown; refer to the accompanying figures
+ for further information:</para>
+ <procedure>
<step>
- <para>See the start of the <systemitem class="osname">Linux</systemitem>
- boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel
- 2.6.26-2-686</guimenuitem> from the startup menu and click
- <guibutton>'Enter'</guibutton> to start
- <systemitem class="osname">Linux</systemitem> and Evergreen.
- After some delay you should see the command line prompt
- <prompt>debian-lenny login:</prompt>. Log in with username
- <userinput>root </userinput> and password <userinput>evergreen</userinput>
- to continue.</para>
+ <para>Download and install an appropriate version of the
+ standard <systemitem class="osname">Ubuntu</systemitem> software
+ distribution on <application>"VirtualBox"</application>.</para>
+ </step>
+ <step>
+ <para>Start (boot) <systemitem class="osname">Ubuntu</systemitem>.</para>
+ </step>
+ <step>
+ <para>Install Evergreen on the
+ <systemitem class="osname">Ubuntu</systemitem> system.</para>
</step>
</procedure>
</section>
- </simplesect>
+ <section>
+ <title>Summary</title>
+ <para>Whether you install a pre-built, pre-configured virtual image of
+ <systemitem class="osname">Linux</systemitem> already containing the
+ Evergreen software (see <xref linkend="serversideinstall-virtual-prebuilt"/>),
+ or you install a plain virtual
+ image <systemitem class="osname">Linux</systemitem> and then install
+ Evergreen from scratch (see <xref linkend="serversideinstall-virtual-manual"/>),
+ your <systemitem class="osname">Windows</systemitem> system is now hosting
+ an <systemitem class="osname">Linux</systemitem> system, which itself is
+ hosting the Evergreen distribution. So far as Evergreen is concerned,
+ it is happily executing in a standard
+ <systemitem class="osname">Linux</systemitem> environment and should
+ behave as if it were executing on a standalone
+ <systemitem class="osname">Linux</systemitem> system.</para>
+ </section>
+ </section>
</section>
</section>
</chapter>
--
2.11.0