--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>\r
+<chapter xml:id="server_install" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+\r
+\r
+<info>\r
+ <title>Installing the Evergreen 2.1 Server</title>\r
+</info>\r
+<simplesect id="_preamble_referenced_user_accounts">\r
+<title>Preamble: referenced user accounts</title>\r
+<simpara>In subsequent simplesects, we will refer to a number of different accounts, as\r
+follows:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+Linux user accounts:\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">user</emphasis> Linux account is the account that you use to log onto the\r
+ Linux system as a regular user.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">root</emphasis> Linux account is an account that has system administrator\r
+ privileges. On Debian and Fedora you can switch to this account from\r
+ your <emphasis role="strong">user</emphasis> account by issuing the <literal>su -</literal> command and entering the\r
+ password for the <emphasis role="strong">root</emphasis> account when prompted. On Ubuntu you can switch\r
+ to this account from your <emphasis role="strong">user</emphasis> account using the <literal>sudo su -</literal> command\r
+ and entering the password for your <emphasis role="strong">user</emphasis> account when prompted.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">opensrf</emphasis> Linux account is an account that you create when installing\r
+ OpenSRF. You can switch to this account from the <emphasis role="strong">root</emphasis> account by\r
+ issuing the <literal>su - opensrf</literal> command.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">postgres</emphasis> Linux account is created automatically when you install\r
+ the PostgreSQL database server. You can switch to this account from the\r
+ <emphasis role="strong">root</emphasis> account by issuing the <literal>su - postgres</literal> command.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+PostgreSQL user accounts:\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">evergreen</emphasis> PostgreSQL account is a superuser account that you will\r
+ create to connect to the PostgreSQL database server.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Evergreen administrator account:\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+The <emphasis role="strong">egadmin</emphasis> Evergreen account is an administrator account for\r
+ Evergreen that you will use to test connectivity and configure your\r
+ Evergreen instance.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+</itemizedlist>\r
+</simplesect>\r
+<simplesect id="_preamble_getting_an_evergreen_official_release_tarball">\r
+<title>Preamble: Getting an Evergreen official release tarball</title>\r
+<simpara>To download and extract the source for the current release of Evergreen, issue\r
+the following commands as the <emphasis role="strong">user</emphasis> Linux account:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">wget -c http://evergreen-ils.org/downloads/Evergreen-ILS-2.1.1.tar.gz\r
+tar xzf Evergreen-ILS-2.1.1.tar.gz</programlisting>\r
+</simplesect>\r
+<simplesect id="_preamble_developer_instructions">\r
+<title>Preamble: Developer instructions</title>\r
+<note><simpara>Skip this simplesect if you are using an official release tarball downloaded\r
+from <ulink url="http://evergreen-ils.org/downloads">http://evergreen-ils.org/downloads</ulink></simpara></note>\r
+<simpara>Developers working directly with the source code from the Git repository,\r
+rather than an official release tarball, must install some extra packages\r
+and perform one step before they can proceed with the <literal>./configure</literal> step.</simpara>\r
+<simpara>As the <emphasis role="strong">root</emphasis> Linux account, install the following packages:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+autoconf\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+automake\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+libtool\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+<simpara>As the <emphasis role="strong">user</emphasis> Linux account, issue the following command in the Evergreen\r
+source directory to generate the configure script and Makefiles:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">./autogen.sh</programlisting>\r
+<simpara>After running <literal>make install</literal>, developers also need to install the Dojo Toolkit\r
+set of JavaScript libraries. The appropriate version of Dojo is included\r
+in Evergreen release tarballs. Developers should install the Dojo 1.3.3\r
+version of Dojo by issuing the following commands as the <emphasis role="strong">opensrf</emphasis> Linux\r
+account:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz\r
+tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz\r
+cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.</programlisting>\r
+</simplesect>\r
+<simplesect id="_installing_prerequisites">\r
+<title>Installing prerequisites</title>\r
+<simpara>Evergreen has a number of prerequisite packages that must be installed\r
+before you can successfully configure, compile, and install Evergreen.</simpara>\r
+<orderedlist numeration="arabic">\r
+<listitem>\r
+<simpara>\r
+Begin by installing the most recent version of OpenSRF (2.0 or later).\r
+ You can download OpenSRF releases from <ulink url="http://evergreen-ils.org/opensrf.php">http://evergreen-ils.org/opensrf.php</ulink>\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+On many distributions, it is necessary to install PostgreSQL 9 from external\r
+ repositories.\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+On Debian Squeeze, open <literal>/etc/apt/sources.list</literal> in a text editor as the\r
+ <emphasis role="strong">root</emphasis> Linux account and add the following line:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">deb http://backports.debian.org/debian-backports squeeze-backports main contrib</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+On Ubuntu Lucid, you can use a PPA (personal package archive), which are\r
+ package sources hosted on Launchpad. The one most commonly used by Evergreen\r
+ Community members is maintained by Martin Pitt, who also maintains the\r
+ official PostgreSQL packages for Ubuntu. As the <emphasis role="strong">root</emphasis> Linux account, issue\r
+ the following commands to add the PPA source:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">apt-get install python-software-properties\r
+add-apt-repository ppa:pitti/postgresql</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Fedora 15 comes with PostgreSQL 9, so no additional steps are required.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+On Debian and Ubuntu, run <literal>aptitude update</literal> as the <emphasis role="strong">root</emphasis> Linux account to\r
+ retrieve the new packages from the backports repository.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Issue the following commands as the <emphasis role="strong">root</emphasis> Linux account to install\r
+ prerequisites using the <literal>Makefile.install</literal> prerequisite installer,\r
+ substituting <literal>debian-squeeze</literal>, <literal>fedora15</literal>, <literal>ubuntu-lucid</literal>, <literal>centos</literal>, or\r
+ <literal>rhel</literal> for <osname> below:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install <osname></programlisting>\r
+<note><simpara><literal>centos</literal> and <literal>rhel</literal> are less tested than the <literal>debian</literal>, <literal>fedora</literal>,\r
+and <literal>ubuntu</literal> options. Your patches and suggestions for improvement are\r
+welcome!</simpara></note>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Add the libdbi-libdbd libraries to the system dynamic library path by\r
+ issuing the following commands as the <emphasis role="strong">root</emphasis> Linux account:\r
+</simpara>\r
+<formalpara><title>Debian / Ubuntu</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf\r
+ldconfig</programlisting>\r
+</para></formalpara>\r
+<formalpara><title>Fedora</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">echo "/usr/lib64/dbd" > /etc/ld.so.conf.d/eg.conf\r
+ldconfig</programlisting>\r
+</para></formalpara>\r
+</listitem>\r
+</orderedlist>\r
+</simplesect>\r
+<simplesect id="_configuration_and_compilation_instructions">\r
+<title>Configuration and compilation instructions</title>\r
+<simpara>For the time being, we are still installing everything in the <literal>/openils/</literal>\r
+directory. From the Evergreen source directory, issue the following commands as\r
+the <emphasis role="strong">user</emphasis> Linux account to configure and build Evergreen:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">./configure --prefix=/openils --sysconfdir=/openils/conf\r
+make</programlisting>\r
+</simplesect>\r
+<simplesect id="_installation_instructions">\r
+<title>Installation instructions</title>\r
+<orderedlist numeration="arabic">\r
+<listitem>\r
+<simpara>\r
+Once you have configured and compiled Evergreen, issue the following\r
+ command as the <emphasis role="strong">root</emphasis> Linux account to install Evergreen, build the server\r
+ portion of the staff client, and copy example configuration files to\r
+ <literal>/openils/conf</literal>.\r
+ Change the value of the <literal>STAFF_CLIENT_STAMP_ID</literal> variable to match the version\r
+ of the staff client that you will use to connect to the Evergreen server.\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">make STAFF_CLIENT_STAMP_ID=rel_2_1_1 install</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+The server portion of the staff client expects <literal>http://hostname/xul/server</literal>\r
+ to resolve. Issue the following commands as the <emphasis role="strong">root</emphasis> Linux account to\r
+ create a symbolic link pointing to the <literal>server</literal> subdirectory of the server\r
+ portion of the staff client that we just built using the staff client ID\r
+ <emphasis>rel_name</emphasis>:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">cd /openils/var/web/xul\r
+ln -sf rel_name/server server</programlisting>\r
+</listitem>\r
+</orderedlist>\r
+</simplesect>\r
+<simplesect id="_change_ownership_of_the_evergreen_files">\r
+<title>Change ownership of the Evergreen files</title>\r
+<simpara>All files in the <literal>/openils/</literal> directory and subdirectories must be owned by the\r
+<literal>opensrf</literal> user. Issue the following command as the <emphasis role="strong">root</emphasis> Linux account to\r
+change the ownership on the files:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">chown -R opensrf:opensrf /openils</programlisting>\r
+</simplesect>\r
+<simplesect id="_create_the_oils_web_xml_configuration_file">\r
+<title>Create the oils_web.xml configuration file</title>\r
+<simpara>Many administration interfaces, such as acquisitions, bookings, and various\r
+configuration screens, depend on the correct configuration of HTML templates.\r
+Copying the sample configuration file into place should work in most cases:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</programlisting>\r
+</simplesect>\r
+<simplesect id="_configure_the_apache_web_server">\r
+<title>Configure the Apache Web server</title>\r
+<orderedlist numeration="arabic">\r
+<listitem>\r
+<simpara>\r
+Use the example configuration files in <literal>Open-ILS/examples/apache/</literal> to\r
+configure your Web server for the Evergreen catalog, staff client, Web\r
+services, and administration interfaces. Issue the following commands as the\r
+<emphasis role="strong">root</emphasis> Linux account:\r
+</simpara>\r
+<formalpara><title>Debian and Ubuntu</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">cp Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/\r
+cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/\r
+cp Open-ILS/examples/apache/startup.pl /etc/apache2/\r
+# Now set up SSL\r
+mkdir /etc/apache2/ssl\r
+cd /etc/apache2/ssl</programlisting>\r
+</para></formalpara>\r
+<formalpara><title>Fedora</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">cp Open-ILS/examples/apache/eg.conf /etc/httpd/sites-available/\r
+cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/\r
+cp Open-ILS/examples/apache/startup.pl /etc/httpd/\r
+# Now set up SSL\r
+mkdir /etc/httpd/ssl\r
+cd /etc/httpd/ssl</programlisting>\r
+</para></formalpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+The <literal>openssl</literal> command cuts a new SSL key for your Apache server. For a\r
+production server, you should purchase a signed SSL certificate, but you can\r
+just use a self-signed certificate and accept the warnings in the staff client\r
+and browser during testing and development. Create an SSL key for the Apache\r
+server by issuing the following command as the <emphasis role="strong">root</emphasis> Linux account:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">root</emphasis> Linux account, edit the <literal>eg.conf</literal> file that you copied into\r
+place.\r
+</simpara>\r
+<orderedlist numeration="loweralpha">\r
+<listitem>\r
+<simpara>\r
+Replace <literal>Allow from 10.0.0.0/8</literal> with <literal>Allow from all</literal> (to enable\r
+ access to the offline upload / execute interface from any workstation on\r
+ any network - note that you must secure this for a production instance)\r
+</simpara>\r
+</listitem>\r
+</orderedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Change the user for the Apache server.\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+(Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, edit\r
+ <literal>/etc/apache2/envvars</literal>. Change <literal>export APACHE_RUN_USER=www-data</literal> to\r
+ <literal>export APACHE_RUN_USER=opensrf</literal>.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+(Fedora): As the <emphasis role="strong">root</emphasis> Linux account , edit <literal>/etc/httpd/conf/httpd.conf</literal>.\r
+ Change <literal>User apache</literal> to <literal>User opensrf</literal>.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Configure Apache with performance settings appropriate for Evergreen:\r
+</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+(Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, edit\r
+ <literal>/etc/apache2/apache2.conf</literal>:\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+(Fedora): As the <emphasis role="strong">root</emphasis> Linux account, edit <literal>/etc/httpd/conf/httpd.conf</literal>:\r
+</simpara>\r
+<orderedlist numeration="loweralpha">\r
+<listitem>\r
+<simpara>\r
+Change <literal>KeepAliveTimeout</literal> to <literal>1</literal>. Higher values reduce the chance of\r
+ a request timing out unexpectedly, but increase the risk of using up\r
+ all available Apache child processes.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+<emphasis>Optional</emphasis>: Change <literal>MaxKeepAliveRequests</literal> to <literal>100</literal>\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Update the prefork configuration simplesect to suit your environment. The\r
+ following settings apply to a busy system:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered"><IfModule mpm_prefork_module>\r
+ StartServers 20\r
+ MinSpareServers 5\r
+ MaxSpareServers 15\r
+ MaxClients 150\r
+ MaxRequestsPerChild 10000\r
+</IfModule></programlisting>\r
+</listitem>\r
+</orderedlist>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+(Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, enable the Evergreen site:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">a2dissite default # OPTIONAL: disable the default site (the "It Works" page)\r
+a2ensite eg.conf</programlisting>\r
+</listitem>\r
+</orderedlist>\r
+</simplesect>\r
+<simplesect id="_configure_opensrf_for_the_evergreen_application">\r
+<title>Configure OpenSRF for the Evergreen application</title>\r
+<simpara>There are a number of example OpenSRF configuration files in <literal>/openils/conf/</literal>\r
+that you can use as a template for your Evergreen installation. Issue the\r
+following commands as the <emphasis role="strong">opensrf</emphasis> Linux account:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml\r
+cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</programlisting>\r
+<simpara>When you installed OpenSRF, you created four Jabber users on two\r
+separate domains and edited the <literal>opensrf_core.xml</literal> file accordingly. Please\r
+refer back to the OpenSRF README and, as the <emphasis role="strong">opensrf</emphasis> Linux account, edit the\r
+Evergreen version of the <literal>opensrf_core.xml</literal> file using the same Jabber users\r
+and domains as you used while installing and testing OpenSRF.</simpara>\r
+<note><simpara>The <literal>-b</literal> flag tells the <literal>cp</literal> command to create a backup version of the\r
+destination file. The backup version of the destination file has a tilde (<literal>~</literal>)\r
+appended to the file name, so if you have forgotten the Jabber users and\r
+domains, you can retrieve the settings from the backup version of the files.</simpara></note>\r
+<simpara><literal>eg_db_config.pl</literal>, described in the following simplesect, sets the database\r
+connection information in <literal>opensrf.xml</literal> for you.</simpara>\r
+</simplesect>\r
+<simplesect id="_creating_the_evergreen_database">\r
+<title>Creating the Evergreen database</title>\r
+<simpara>By default, the <literal>Makefile.install</literal> prerequisite installer does not install\r
+the PostgreSQL 9.0 database server required by every Evergreen system;\r
+for production use, most libraries install the PostgreSQL database server on a\r
+dedicated machine. You can install the packages required by Debian, Ubuntu, or\r
+Fedora on the machine of your choice using the following commands as the <emphasis role="strong">root</emphasis>\r
+Linux account:</simpara>\r
+<formalpara><title>(Debian / Ubuntu) Installing PostgreSQL 9.0 server packages</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_90</programlisting>\r
+</para></formalpara>\r
+<formalpara><title>(Fedora 15) Installing PostgreSQL 9.0 server packages</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server</programlisting>\r
+</para></formalpara>\r
+<simpara>For a standalone PostgreSQL server, install the following Perl modules as the\r
+<emphasis role="strong">root</emphasis> Linux account:</simpara>\r
+<formalpara><title>(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9.0 server</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">aptitude install gcc libxml-libxml-perl libxml-libxslt-perl\r
+cpan Business::ISBN\r
+cpan JSON::XS\r
+cpan Library::CallNumber::LC\r
+cpan MARC::Record\r
+cpan MARC::File::XML\r
+cpan UUID::Tiny</programlisting>\r
+</para></formalpara>\r
+<formalpara><title>(Fedora 15) Installing additional Perl modules on a standalone PostgreSQL 9.0 server</title><para>\r
+<programlisting language="bash" linenumbering="unnumbered">yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN\r
+cpan JSON::XS\r
+cpan Library::CallNumber::LC\r
+cpan MARC::Record\r
+cpan MARC::File::XML\r
+cpan UUID::Tiny</programlisting>\r
+</para></formalpara>\r
+<simpara>You need to create a PostgreSQL superuser to create and access the database.\r
+Issue the following command as the <emphasis role="strong">postgres</emphasis> Linux account to create a new\r
+PostgreSQL superuser named <literal>evergreen</literal>. When prompted, enter the new user’s\r
+password:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">createuser -s -P evergreen</programlisting>\r
+<simpara>Once you have created the <emphasis role="strong">evergreen</emphasis> PostgreSQL account, you also need to\r
+create the database and schema, and configure your configuration files to point\r
+at the database server. Issue the following command as the <emphasis role="strong">root</emphasis> Linux account\r
+from inside the Evergreen source directory, replacing <user>, <password>,\r
+<hostname>, <port>, and <dbname> with the appropriate values for your\r
+PostgreSQL database (where <user> and <password> are for the <emphasis role="strong">evergreen</emphasis>\r
+PostgreSQL account you just created), and replace <admin-user> and <admin-pass>\r
+with the values you want for the <emphasis role="strong">egadmin</emphasis> Evergreen administrator account:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
+ --service all --create-database --create-schema --create-offline \\r
+ --user <user> --password <password> --hostname <hostname> --port <port> \\r
+ --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass></programlisting>\r
+<simpara>This creates the database and schema and configures all of the services in\r
+your <literal>/openils/conf/opensrf.xml</literal> configuration file to point to that database.\r
+It also creates the configuration files required by the Evergreen <literal>cgi-bin</literal>\r
+administration scripts, and sets the user name and password for the <emphasis role="strong">egadmin</emphasis>\r
+Evergreen administrator account to your requested values.</simpara>\r
+<simplesect id="_creating_the_database_on_a_remote_server">\r
+<title>Creating the database on a remote server</title>\r
+<simpara>In a production instance of Evergreen, your PostgreSQL server should be\r
+installed on a dedicated server. To create the database in that case, you\r
+can either:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+Install the PostgreSQL contrib modules on the machine on which you\r
+ are installing the Evergreen code, and use the --create-database\r
+ option from that machine, or\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Copy the <literal>Open-ILS/src/sql/Pg/create_database.sql</literal> script to your\r
+ PostgreSQL server and invoke it as the <emphasis role="strong">postgres</emphasis> Linux account:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">psql -vdb_name=<dbname> -vcontrib_dir=`pg_config --sharedir`/contrib -f create_database.sql</programlisting>\r
+</listitem>\r
+</itemizedlist>\r
+<simpara>Then you can issue the <literal>eg_db_config.pl</literal> command as above <emphasis>without</emphasis> the\r
+<literal>--create-database</literal> argument to create your schema and configure your\r
+configuration files.</simpara>\r
+</simplesect>\r
+</simplesect>\r
+<simplesect id="_starting_evergreen">\r
+<title>Starting Evergreen</title>\r
+<orderedlist numeration="arabic">\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">root</emphasis> Linux account, start the <literal>memcached</literal> and <literal>ejabberd</literal> services\r
+(if they aren’t already running):\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">/etc/init.d/ejabberd start\r
+/etc/init.d/memcached start</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">opensrf</emphasis> Linux account, start Evergreen. The <literal>-l</literal> flag in the\r
+following command is only necessary if you want to force Evergreen to treat the\r
+hostname as <literal>localhost</literal>; if you configured <literal>opensrf.xml</literal> using the real\r
+hostname of your machine as returned by <literal>perl -ENet::Domain 'print\r
+Net::Domain::hostfqdn() . "\n";'</literal>, you should not use the <literal>-l</literal> flag.\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">osrf_ctl.sh -l -a start_all</programlisting>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+If you receive the error message <literal>bash: osrf_ctl.sh: command not found</literal>,\r
+ then your environment variable <literal>PATH</literal> does not include the <literal>/openils/bin</literal>\r
+ directory; this should have been set in the <emphasis role="strong">opensrf</emphasis> Linux account’s\r
+ <literal>.bashrc</literal> configuration file. To manually set the <literal>PATH</literal> variable, edit the\r
+ configuration file <literal>~/.bashrc</literal> as the <emphasis role="strong">opensrf</emphasis> Linux account and add the\r
+ following line:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">export PATH=$PATH:/openils/bin</programlisting>\r
+</listitem>\r
+</itemizedlist>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">opensrf</emphasis> Linux account, generate the Web files needed by the staff\r
+ client and catalogue and update the organization unit proximity (you need to do\r
+ this the first time you start Evergreen, and after that each time you change\r
+ the library hierarchy in <literal>config.cgi</literal>):\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">autogen.sh -u</programlisting>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">root</emphasis> Linux account, restart the Apache Web server:\r
+</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">/etc/init.d/apache2 restart</programlisting>\r
+<simpara>If the Apache Web server was running when you started the OpenSRF services, you\r
+might not be able to successfully log in to the OPAC or staff client until the\r
+Apache Web server is restarted.</simpara>\r
+</listitem>\r
+</orderedlist>\r
+</simplesect>\r
+<simplesect id="_testing_connections_to_evergreen">\r
+<title>Testing connections to Evergreen</title>\r
+<simpara>Once you have installed and started Evergreen, test your connection to\r
+Evergreen via <literal>srfsh</literal>. As the <emphasis role="strong">opensrf</emphasis> Linux account, issue the following\r
+commands to start <literal>srfsh</literal> and try to log onto the Evergreen server using the\r
+<emphasis role="strong">egadmin</emphasis> Evergreen administrator user name and password that you set using the\r
+<literal>eg_db_config.pl</literal> command:</simpara>\r
+<programlisting language="bash" linenumbering="unnumbered">/openils/bin/srfsh\r
+srfsh% login <admin-user> <admin-pass></programlisting>\r
+<simpara>You should see a result like:</simpara>\r
+<literallayout class="monospaced">Received Data: "250bf1518c7527a03249858687714376"\r
+------------------------------------\r
+Request Completed Successfully\r
+Request Time in seconds: 0.045286\r
+------------------------------------</literallayout>\r
+<literallayout class="monospaced">Received Data: {\r
+ "ilsevent":0,\r
+ "textcode":"SUCCESS",\r
+ "desc":" ",\r
+ "pid":21616,\r
+ "stacktrace":"oils_auth.c:304",\r
+ "payload":{\r
+ "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",\r
+ "authtime":420\r
+ }</literallayout>\r
+<literallayout class="monospaced">}</literallayout>\r
+<literallayout class="monospaced">------------------------------------\r
+Request Completed Successfully\r
+Request Time in seconds: 1.336568\r
+------------------------------------</literallayout>\r
+<simpara>If this does not work, it’s time to do some troubleshooting.</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+As the <emphasis role="strong">opensrf</emphasis> Linux acccount, run the <literal>settings-tester.pl</literal> script to see\r
+ if it finds any system configuration problems. The script is found at\r
+ <literal>Open-ILS/src/support-scripts/settings-tester.pl</literal> in the Evergreen source\r
+ tree.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+Follow the steps in the <ulink url="http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors">troubleshooting guide</ulink>.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+If you have faithfully followed the entire set of installation steps\r
+ listed here, you are probably extremely close to a working system.\r
+ Gather your configuration files and log files and contact the\r
+ <ulink url="http://open-ils.org/listserv.php">Evergreen development mailing list</ulink>\r
+ for assistance before making any drastic changes to your system\r
+ configuration.\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+</simplesect>\r
+<simplesect id="_getting_help">\r
+<title>Getting help</title>\r
+<simpara>Need help installing or using Evergreen? Join the mailing lists at\r
+<ulink url="http://evergreen-ils.org/listserv.php">http://evergreen-ils.org/listserv.php</ulink> or contact us on the Freenode\r
+IRC network on the #evergreen channel.</simpara>\r
+</simplesect>\r
+</chapter>\r
projects / Evergreen-DocBook.git / commitdiff