--- /dev/null
+<?xml version='1.0' encoding='UTF-8'?>\r
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
+ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="upgradingevergreen-2.0">\r
+ <info>\r
+ <title>Upgrading Evergreen to 2.0</title>\r
+ <abstract>\r
+ <para>This Chapter will explain the step-by-step process of upgrading <application>Evergreen\r
+ </application> to 2.0, including steps to upgrade <application>OpenSRF</application>. Before \r
+ upgrading, it is important to carefully plan an upgrade strategy to minimize system downtime and \r
+ service interruptions. All of the steps in this chapter are to be completed from the command line.</para>\r
+ </abstract>\r
+ </info> \r
+ <para>In the following instructions, you are asked to perform certain steps as either the <systemitem class="username">root</systemitem> or <systemitem class="username">opensrf</systemitem> user.</para>\r
+ <itemizedlist>\r
+ <listitem>Debian: To become the <systemitem class="username">root</systemitem> user, issue the <command>su</command> command and enter the password of the \r
+ <systemitem class="username">root</systemitem> user.</listitem>\r
+ <listitem>Ubuntu: To become the <systemitem class="username">root</systemitem> user, issue the <command>sudo su</command> command and enter the password of your current user.</listitem>\r
+ </itemizedlist>\r
+ <para>To switch from the <systemitem class="username">root</systemitem> user to a different user, issue the <command>su - [user]</command> command; for example, \r
+ <command>su - opensrf</command>. Once you have become a non-root user, to become the <systemitem class="username">root</systemitem> user again simply issue the exit command.</para> \r
+ <para>In the following instructions, <filename class='directory'>/path/to/OpenSRF/</filename> represents the path to the OpenSRF source directory.</para>\r
+ <section xml:id="upgradingevergreen-stop_evergreen">\r
+ <title>Backing Up Data</title>\r
+ <procedure>\r
+ <step>\r
+ <para>As <systemitem class="username">root</systemitem>, stop the <application>Apache</application> \r
+ web server<indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm>.</para>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, stop all \r
+ <application>Evergreen</application>\r
+ and <application>OpenSRF</application> services:</para>\r
+ <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Back up of the <filename class='directory'>/openils</filename> \r
+ directory.</para>\r
+ </step>\r
+ <step>\r
+ <para><link linkend="backingup">Back up the <application>evergreen\r
+ </application> database</link>.</para>\r
+ </step>\r
+ </procedure>\r
+ </section>\r
+ <section xml:id="upgradingevergreen-upgradingOpenSRF">\r
+ <title>Upgrading OpenSRF to 1.6.2</title><indexterm><primary>OpenSRF</primary></indexterm>\r
+ <procedure>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the source files for <application>OpenSRF</application> \r
+ 1.6.2:</para>\r
+<screen><userinput>\r
+wget http://open-ils.org/downloads/OpenSRF-1.6.2.tar.gz\r
+tar xzf OpenSRF-1.6.2.tar.gz\r
+</userinput></screen>\r
+ <para>A new directory OpenSRF-1.6.2 is created.</para>\r
+ <note><para>For the latest edition of OpenSRF, check the Evergreen download page at \r
+ <ulink url="http://www.open-ils.org/downloads.php" />.\r
+ </para></note>\r
+ </step>\r
+ <step> \r
+ <para>As the <systemitem class="username">root</systemitem> user, install the software prerequisites using the automatic \r
+ prerequisite installer.</para> \r
+<screen><userinput>\r
+aptitude install make\r
+cd /home/opensrf/OpenSRF-1.6.2\r
+</userinput></screen> \r
+ <para>Replace <option>[distribution]</option> below with the following value \r
+ for your distribution:</para>\r
+ <itemizedlist>\r
+ \r
+ <listitem>\r
+ <para><option>debian-lenny</option> for <systemitem class="osname">Debian Lenny (5.0)</systemitem></para>\r
+ </listitem>\r
+ <listitem>\r
+ <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem>\r
+ <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>\r
+ </listitem>\r
+ <listitem>\r
+ <para><option>ubuntu-hardy</option> for <systemitem class="osname">Ubuntu Hardy Heron (8.04)</systemitem>\r
+ <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>\r
+ </listitem>\r
+ <listitem>\r
+ <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx\r
+ (10.04)</systemitem></para>\r
+ </listitem>\r
+ <listitem>\r
+ <para><option>centos</option> for <systemitem class="osname">CentOS 5</systemitem></para>\r
+ </listitem>\r
+ <listitem>\r
+ <para><option>rhel</option> for <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem></para>\r
+ </listitem>\r
+ </itemizedlist>\r
+<screen><userinput>\r
+cd /path/to/OpenSRF\r
+make -f src/extras/Makefile.install [distribution]\r
+</userinput></screen>\r
+ <para>This will install a number of packages required by OpenSRF on your system, \r
+ including some Perl modules from <systemitem class="resource">CPAN</systemitem><indexterm><primary>Perl</primary><secondary>CPAN</secondary>\r
+ </indexterm>. You can type <userinput>no</userinput> to the initial <systemitem class="resource">CPAN</systemitem> \r
+ configuration prompt to allow it to automatically configure itself to download \r
+ and install Perl modules from <systemitem class="resource">CPAN</systemitem>. The <systemitem class="resource">CPAN</systemitem> installer will ask you a number of \r
+ times whether it should install prerequisite modules - type <userinput>yes</userinput>.</para>\r
+ </step>\r
+ <step> \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, configure and compile OpenSRF:</para> \r
+ <note>You can include the <option>–enable-python</option> and <option>–enable-java</option> configure options if \r
+ you want to include support for Python<indexterm><primary>Python</primary></indexterm> and Java\r
+ <indexterm><primary>Java</primary></indexterm>, respectively.</note>\r
+<screen><userinput>\r
+cd /home/opensrf/OpenSRF-1.6.2\r
+./configure --prefix=/openils --sysconfdir=/openils/conf\r
+make\r
+</userinput></screen> \r
+ </step>\r
+ <step> \r
+ <para>As the <systemitem class="username">root</systemitem> user, return to your OpenSRF build directory and install \r
+ OpenSRF:</para>\r
+<screen><userinput>\r
+cd /home/opensrf/OpenSRF-1.6.2\r
+make install\r
+</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">root</systemitem> user, change the ownership of the installed files to the \r
+ <systemitem class="username">opensrf</systemitem> user:</para>\r
+ <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Restart and Test OpenSRF</para>\r
+<screen><userinput>\r
+osrf_ctl.sh -l -a start_all\r
+/openils/bin/srfsh\r
+srfsh# request opensrf.math add 2 2\r
+</userinput></screen>\r
+ <para>You should see output such as:</para>\r
+<screen>\r
+Received Data: 4\r
+\r
+------------------------------------\r
+Request Completed Successfully\r
+Request Time in seconds: 0.007519\r
+------------------------------------\r
+\r
+srfsh#\r
+</screen> \r
+ <para>If test completed successfully move onto the next section. \r
+ Otherwise, refer to the <link linkend="troubleshooting">troubleshooting</link> chapter \r
+ of this documentation.</para> \r
+ </step> \r
+ </procedure> \r
+ </section>\r
+ <section xml:id="upgradingevergreen-upgrading_from_1.6_to_2.0">\r
+ <title>Upgrade <application>Evergreen</application> from 1.6.1 to 2.0</title>\r
+ <procedure>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract <application>Evergreen 2.0</application>\r
+ </para>\r
+<screen><userinput>\r
+wget http://www.open-ils.org/downloads/exit\r
+uEvergreen-ILS-2.0.1.tar.gz\r
+tar xzf Evergreen-ILS-2.0.1.tar.gz\r
+</userinput></screen>\r
+ <note><para>For the latest edition of Evergreen 2.0, check the Evergreen download page at\r
+ <ulink url="http://www.open-ils.org/downloads.php" /> and adjust upgrading instructions accordingly.</para></note>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">root</systemitem> user, install the prerequisites:</para> \r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen> \r
+ <para>On the next command, replace <option>[distribution]</option> with one of \r
+ these values for your distribution of Debian or Ubuntu:</para>\r
+ <itemizedlist>\r
+ \r
+ <listitem>\r
+ <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>\r
+ </listitem>\r
+ \r
+ <listitem>\r
+ <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx \r
+ (10.04)</systemitem></para>\r
+ </listitem>\r
+ </itemizedlist>\r
+ <screen><userinput>make -f Open-ILS/src/extras/Makefile.install <option>[distribution]</option></userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, configure and compile \r
+ <application>Evergreen</application>:</para>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen>\r
+ <screen><userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput></screen>\r
+ <screen><userinput>make</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">root</systemitem> user, install \r
+ <application>Evergreen</application>:</para>\r
+ <screen><userinput>make STAFF_CLIENT_BUILD_ID=rel_2_0_1 install</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Change to the <application>Evergreen</application> installation \r
+ directory:</para>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <emphasis>root</emphasis> user, change all files to be owned by the \r
+ <emphasis>opensrf</emphasis> user and group:</para>\r
+ <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>\r
+ </step> \r
+ <step>\r
+ <para>As the <systemitem class="username">root</systemitem> user, build <filename>live-db-setup.pl</filename> for the cgi-bin \r
+ bootstrapping scripts and <filename>offline-config.pl</filename> for the offline staff client data uploader:</para>\r
+<screen><userinput>\r
+cd /home/opensrf/Evergreen-ILS-2.0.1\r
+perl Open-ILS/src/support-scripts/eg_db_config.pl --create-bootstrap --create-offline \ \r
+--user evergreen --password evergreen --hostname localhost --port 5432 \\r
+--database evergreen\r
+</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, update server symlink in <filename class="directory">/openils/var/web/xul/</filename>:</para>\r
+<screen><userinput>\r
+cd /openils/var/web/xul/\r
+rm server\r
+ln -s rel_1_6_1_5/server\r
+</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Update the Evergreen database:</para>\r
+ <note><para>It is recommended that you <link linkend="backingup">back up your Evergreen database</link> in order to restore your data if anything goes wrong.</para></note>\r
+<screen>\r
+<userinput>\r
+psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.1-2.0-upgrade-db.sql evergreen\r
+psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/2.0.0-2.0.1-upgrade-db.sql evergreen\r
+</userinput>\r
+</screen> \r
+ </step>\r
+<step>\r
+ <para>Run the <filename>reingest-1.6-2.0.pl<filename> script to generate an sql script. Then use the sql file to reingest bib records into your \r
+ <database>evergreen<batabase> database. This is required to make the new facet sidebar in OPAC search results work and to upgrade the keyword indexes to use \r
+ the revised NACO normalization routine</para>\r
+ <note><para>If you are running a large Evergreen installation, it is recommend that you examine the script first. Reingesting a large number of bibliographic records \r
+ may take several hours.</para></note>\r
+<screen><userinput>perl Open-ILS/src/sql/Pg/reingest-1.6-2.0.pl</userinput></screen>\r
+<screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/reingest-1.6-2.0.sql evergreen</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, \r
+ copy <filename>/openils/conf/oils_web.xml.example</filename> to <filename>/openils/conf/oils_web.xml</filename>\r
+ <indexterm><primary>configuration files</primary><secondary>oils_web.xml</secondary></indexterm>\r
+ (needed for acquisitions templates).</para>\r
+ <screen><userinput>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Update <filename>opensrf_core.xml</filename> and <filename>opensrf.xml</filename> by copying the new example files \r
+ (<filename>/openils/conf/opensrf_core.xml.example</filename> and <filename>/openils/conf/opensrf.xml</filename>).</para>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>\r
+ <screen><userinput>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</userinput></screen>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>\r
+ <screen><userinput>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Update <filename>opensrf.xml</filename> with the database connection info:</para>\r
+<screen><userinput>\r
+perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config --service all --user evergreen \\r
+--password evergreen --hostname localhost --port 5432 --database evergreen\r
+</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Update /etc/apache2/startup.pl by copying the example from \r
+ Open-ILS/examples/apache/startup.pl.</para><indexterm><primary>configuration files</primary><secondary>startup.pl</secondary></indexterm>\r
+ </step>\r
+ <step>\r
+ <para>Update /etc/apache2/eg_vhost.conf by copying the example from \r
+ Open-ILS/examples/apache/eg_vhost.conf.</para><indexterm><primary>configuration files</primary><secondary>eg_vhost.conf</secondary></indexterm>\r
+ </step>\r
+ <step>\r
+ <para>Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/\r
+ examples/apache/eg.conf.</para><indexterm><primary>configuration files</primary><secondary>eg.conf</secondary></indexterm>\r
+ </step>\r
+ <step>\r
+ <para>Recover customizations you have made to the <application>Apache</application><indexterm><primary>Apache</primary></indexterm> \r
+ configuration files. For example, if you purchased an SSL certificate, you \r
+ will need to edit <filename>eg.conf</filename> to point to the appropriate SSL certificate files.</para>\r
+ <indexterm><primary>SSL</primary><secondary>certificates</secondary></indexterm>\r
+ </step> \r
+ </procedure> \r
+ </section>\r
+ <section xml:id="testing_after_upgrade">\r
+ <title>Restart Evergreen and Test</title>\r
+ <procedure>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, start all \r
+ <application>Evergreen</application> and <application>OpenSRF</application> \r
+ services:</para>\r
+ <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run <command>autogen</command> to refresh the static \r
+ organizational data files:</para><indexterm><primary>autogen</primary></indexterm>\r
+<screen><userinput>\r
+cd /openils/bin\r
+./autogen.sh -c /openils/conf/opensrf_core.xml -u\r
+</userinput></screen>\r
+ \r
+ </step>\r
+ <step>\r
+ <para>Start <command>srfsh</command> and try logging in using your <application>Evergreen</application>\r
+ username and password:</para>\r
+<screen>\r
+<userinput>/openils/bin/srfsh</userinput>\r
+<prompt>srfsh%</prompt> <userinput>login <option>username</option> <option>password</option></userinput>\r
+</screen> \r
+ </step> \r
+ <step>\r
+ <para>Start the <application>Apache</application> web server.</para>\r
+ </step>\r
+ </procedure>\r
+ <note>\r
+ <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting \r
+ section</link> of this documentation for tips \r
+ on finding solutions and seeking further assistance from the Evergreen community.</para> \r
+ </note>\r
+ </section>\r
+ <section xml:id="upgrading_Postgresqlto8.4">\r
+ <title>Upgrading PostgreSQL from 8.2 to 8.4 (if required)</title>\r
+ <para>Evergreen 1.6.1 supports PostgreSQL version 8.4 and it is recommended that you upgrade PostgreSQL when you upgrade Evergreen to 1.6.</para>\r
+ <note><para>The order of the following steps is very important.</para></note><indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
+ <procedure>\r
+ <step>\r
+ <para>As <systemitem class="username">opensrf</systemitem>, stop the evergreen and opensrf services:</para>\r
+ <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
+ </step> \r
+ <step>\r
+ <para><link linkend="backingup">Backup the Evergreen database data</link></para>\r
+ </step>\r
+ <step>\r
+ <para>Upgrade to Postgresql 8.4 by removing old version and installing Postgresql 8.4</para>\r
+ </step>\r
+ <step> \r
+ <para>Create an empty Evergreen database in postgresql 8.4 by issuing the following commands as the postgres user:</para>\r
+<screen>\r
+<userinput>\r
+createdb -E UNICODE evergreen\r
+createlang plperl evergreen\r
+createlang plperlu evergreen\r
+createlang plpgsql evergreen\r
+psql -f /usr/share/postgresql/8.4/contrib/tablefunc.sql evergreen\r
+psql -f /usr/share/postgresql/8.4/contrib/tsearch2.sql evergreen\r
+psql -f /usr/share/postgresql/8.4/contrib/pgxml.sql evergreen\r
+</userinput>\r
+</screen> \r
+ </step>\r
+ <step>\r
+ <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL server, create a PostgreSQL user named <systemitem class="username">evergreen</systemitem> for the database cluster:</para>\r
+ <screen><userinput>createuser -P -s evergreen</userinput></screen>\r
+ <para>Enter the password for the new PostgreSQL superuser (<systemitem class="username">evergreen</systemitem>)</para> \r
+ </step> \r
+ <step>\r
+ <para>Restore data from backup created in step 1.</para>\r
+ </step>\r
+ <step>\r
+ <para>To point tsearch2 to proper function names in 8.4, run the SQL script \r
+ <filename>/home/opensrf/Evergreen-ILS*/Open-ILS/src/sql/Pg/000.english.pg84.fts-config.sql</filename> using the <command>psql</command> command.</para>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS*</userinput></screen>\r
+ <screen><userinput>psql -f /Open-ILS/src/sql/Pg/000.english.pg84.fts-config.sql evergreen</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para><link linkend="upgraderestart">Restart Evergreen and OpenSRF services</link></para>\r
+ </step>\r
+ <step>\r
+ <para>For additional information regarding upgrading PostgreSQL, see the following documentation in PostgreSQL:</para>\r
+ <para><ulink url="http://www.postgresql.org/docs/8.4/static/install-upgrading.html" /></para>\r
+ <para><ulink url="http://www.postgresql.org/docs/8.4/interactive/textsearch-migration.html" /> \r
+ </para>\r
+ <para><ulink url="http://www.postgresql.org/docs/current/static/tsearch2.html#AEN102824" /></para>\r
+ </step>\r
+ </procedure>\r
+ </section>\r
+</chapter>\r
projects / Evergreen-DocBook.git / commitdiff