2.0/admin/Upgrading-Evergreen-2.0.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
   3         xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="upgradingevergreen-2.0">
   4         <info>
   5                 <title>Upgrading Evergreen to 2.0</title>
   6                 <abstract>
   7                         <para>This Chapter will explain the step-by-step process of upgrading <application>Evergreen
   8                         </application> to 2.0, including steps to upgrade <application>OpenSRF</application>. Before
   9                         upgrading, it is important to carefully plan an upgrade strategy to minimize system downtime and
  10                         service interruptions. All of the steps in this chapter are to be completed from the command line.</para>
  11
  12                 </abstract>
  13         </info>
  14                 <para>Evergreen 2.0 has several software requirements:</para>
  15                 <itemizedlist>
  16                         <listitem>PostgreSQL: Version 8.4 is the minimum supported version of PostgreSQL. </listitem>
  17                         <listitem>Linux: Evergreen 2.0 has been tested on Debian Squeeze (6.0) and Ubuntu Lucid Lynx (10.04). If you are runnung an older version of these distributions,
  18                         you may want to upgrade befor installing Evergreen 2.0. For instructions on upgrading these distributions, visit the
  19                         <ulink url="http://www.debian.org/releases/squeeze/">Debian</ulink> or <ulink url="https://help.ubuntu.com/community/LucidUpgrades">Ubuntu</ulink> websites.</listitem>
  20                 </itemizedlist>
  21                 <para>In the following instructions, you are asked to perform certain steps as either the <systemitem class="username">root</systemitem>  or
  22                 <systemitem class="username">opensrf</systemitem> user.</para>
  23                 <itemizedlist>
  24                         <listitem>Debian: To become the <systemitem class="username">root</systemitem> user, issue the <command>su</command> command and enter the password of the
  25                         <systemitem class="username">root</systemitem> user.</listitem>
  26                         <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>
  27                 </itemizedlist>
  28                 <para>To switch from the <systemitem class="username">root</systemitem> user to a different user, issue the <command>su - [user]</command> command; for example,
  29                 <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>
  30                 <para>In the following instructions, <filename class='directory'>/path/to/OpenSRF/</filename> represents the path to the OpenSRF source directory.</para>
  31         <section xml:id="upgradingevergreen-stop_evergreen">
  32                 <title>Backing Up Data</title>
  33                 <procedure>
  34                         <step>
  35                                 <para>As <systemitem class="username">root</systemitem>, stop the <application>Apache</application>
  36                                 web server<indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm>.</para>
  37                         </step>
  38                         <step>
  39                                 <para>As the <systemitem class="username">opensrf</systemitem> user, stop all
  40                                 <application>Evergreen</application>
  41                                 and <application>OpenSRF</application> services:</para>
  42                                 <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>
  43                         </step>
  44                         <step>
  45                                 <para>Back up of the <filename class='directory'>/openils</filename>
  46                                 directory.</para>
  47                         </step>
  48                         <step>
  49                                 <para><link linkend="backingup">Back up the <application>evergreen
  50                                 </application> database</link>.</para>
  51                         </step>
  52                 </procedure>
  53         </section>
  54         <section xml:id="upgradingevergreen-upgradingOpenSRF">
  55                 <title>Upgrading OpenSRF to 1.6.2</title><indexterm><primary>OpenSRF</primary></indexterm>
  56                 <procedure>
  57                         <step>
  58                                 <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the source files for <application>OpenSRF</application>
  59                                 1.6.2:</para>
  60 <screen><userinput>
  61 wget http://open-ils.org/downloads/OpenSRF-1.6.2.tar.gz
  62 tar xzf OpenSRF-1.6.2.tar.gz
  63 </userinput></screen>
  64                                 <para>A new directory OpenSRF-1.6.2 is created.</para>
  65                                 <note><para>For the latest edition of OpenSRF, check the Evergreen download page at
  66                                 <ulink url="http://www.open-ils.org/downloads.php" />.
  67                                 </para></note>
  68                         </step>
  69                         <step>
  70                                 <para>As the <systemitem class="username">root</systemitem> user, install the software prerequisites using the automatic
  71                                 prerequisite installer.</para>
  72 <screen><userinput>
  73 aptitude install make
  74 cd /home/opensrf/OpenSRF-1.6.2
  75 </userinput></screen>
  76                                 <para>Replace <option>[distribution]</option> below with the following value
  77                                 for your distribution:</para>
  78                                 <itemizedlist>
  79                                         <listitem>
  80                                                 <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem>
  81                                                 <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>
  82                                         </listitem>
  83                                         <listitem>
  84                                                 <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx
  85                                                 (10.04)</systemitem><indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>
  86                                         </listitem>
  87                                         <listitem>
  88                                                 <para><option>centos</option> for <systemitem class="osname">CentOS 5</systemitem>
  89                                                 <indexterm><primary>Linux</primary><secondary>CentOS</secondary></indexterm></para>
  90                                         </listitem>
  91                                         <listitem>
  92                                                 <para><option>rhel</option> for <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem>
  93                                                 <indexterm><primary>Linux</primary><secondary>Red Hat</secondary></indexterm></para>
  94                                         </listitem>
  95                                 </itemizedlist>
  96 <screen><userinput>
  97 cd /path/to/OpenSRF
  98 make -f src/extras/Makefile.install [distribution]
  99 </userinput></screen>
 100                                 <para>This will install a number of packages required by OpenSRF on your system,
 101                                 including some Perl modules from <systemitem class="resource">CPAN</systemitem><indexterm><primary>Perl</primary><secondary>CPAN</secondary>
 102                                 </indexterm>. You can type <userinput>no</userinput> to the initial <systemitem class="resource">CPAN</systemitem>
 103                                 configuration prompt to allow it to automatically configure itself to download
 104                                 and install Perl modules from <systemitem class="resource">CPAN</systemitem>. The <systemitem class="resource">CPAN</systemitem> installer will ask you a number of
 105                                 times whether it should install prerequisite modules - type <userinput>yes</userinput>.</para>
 106                         </step>
 107                         <step>
 108                                 <para>As the <systemitem class="username">opensrf</systemitem> user, configure and compile OpenSRF:</para>
 109                                 <note>You can include the <option>–enable-python</option> and <option>–enable-java</option> configure options if
 110                                 you want to include support for Python<indexterm><primary>Python</primary></indexterm> and Java
 111                                 <indexterm><primary>Java</primary></indexterm>, respectively.</note>
 112 <screen><userinput>
 113 cd /home/opensrf/OpenSRF-1.6.2
 114 ./configure --prefix=/openils --sysconfdir=/openils/conf
 115 make
 116 </userinput></screen>
 117                         </step>
 118                         <step>
 119                                 <para>As the <systemitem class="username">root</systemitem> user, return to your OpenSRF build directory and install
 120                                 OpenSRF:</para>
 121 <screen><userinput>
 122 cd /home/opensrf/OpenSRF-1.6.2
 123 make install
 124 </userinput></screen>
 125                         </step>
 126                         <step>
 127                                 <para>As the <systemitem class="username">root</systemitem> user, change the ownership of the installed files to the
 128                                 <systemitem class="username">opensrf</systemitem> user:</para>
 129                                 <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>
 130                         </step>
 131                         <step>
 132                                 <para>Restart and Test OpenSRF</para>
 133 <screen><userinput>
 134 osrf_ctl.sh -l -a start_all
 135 /openils/bin/srfsh
 136 srfsh#  request opensrf.math add 2 2
 137 </userinput></screen>
 138                                 <para>You should see output such as:</para>
 139 <screen>
 140 Received Data: 4
 141
 142 ------------------------------------
 143 Request Completed Successfully
 144 Request Time in seconds: 0.007519
 145 ------------------------------------
 146
 147 srfsh#
 148 </screen>
 149                                 <para>If test completed successfully move onto the next section.
 150                                 Otherwise, refer to the <link linkend="troubleshooting">troubleshooting</link> chapter
 151                                 of this documentation.</para>
 152                         </step>
 153                 </procedure>
 154         </section>
 155         <section xml:id="upgradingevergreen-upgrading_from_1.6_to_2.0">
 156                 <title>Upgrade <application>Evergreen</application> from 1.6.1 to 2.0</title>
 157                 <note>
 158                         <para>PostgreSQL 8.4 is the minimum supported version of PostgreSQL.</para>
 159                         <para>Evergreen 2.0 has been tested on Debian Squeeze (6.0) and Ubuntu Lucid (10.04). If you are runnung an older version of
 160                         these distributions, you may want to upgrade befor installing Evergreen 2.0. For instructions on upgrading these distribuitions, visit the
 161                         <ulink url="http://www.debian.org/releases/squeeze/">Debian</ulink> or <ulink url="https://help.ubuntu.com/community/LucidUpgrades">Ubuntu</ulink> websites.</para>
 162                 </note>
 163                 <procedure>
 164                         <step>
 165                                 <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract <application>Evergreen 2.0</application>
 166                                 </para>
 167 <screen><userinput>
 168 wget http://www.open-ils.org/downloads/Evergreen-ILS-2.0.1.tar.gz
 169 tar xzf Evergreen-ILS-2.0.1.tar.gz
 170 </userinput></screen>
 171                                 <note><para>For the latest edition of Evergreen 2.0, check the Evergreen download page at
 172                                 <ulink url="http://www.open-ils.org/downloads.php" /> and adjust upgrading instructions accordingly.</para></note>
 173                         </step>
 174                         <step>
 175                                 <para>As the <systemitem class="username">root</systemitem> user, install the prerequisites:</para>
 176                                 <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen>
 177                                 <para>On the next command, replace <option>[distribution]</option> with one of
 178                                 these values for your distribution of Debian or Ubuntu:</para>
 179                                 <itemizedlist>
 180
 181                                         <listitem>
 182                                                 <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>
 183                                         </listitem>
 184
 185                                         <listitem>
 186                                                 <para><option>ubuntu-lucid</option> for  <systemitem class="osname">Ubuntu Lucid Lynx
 187                                                 (10.04)</systemitem></para>
 188                                         </listitem>
 189                                 </itemizedlist>
 190                                 <screen><userinput>make -f Open-ILS/src/extras/Makefile.install <option>[distribution]</option></userinput></screen>
 191                         </step>
 192                         <step>
 193                                 <para>As the <systemitem class="username">opensrf</systemitem> user, configure and compile
 194                                 <application>Evergreen</application>:</para>
 195                                 <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen>
 196                                 <screen><userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput></screen>
 197                                 <screen><userinput>make</userinput></screen>
 198                         </step>
 199                         <step>
 200                                 <para>As the <systemitem class="username">root</systemitem> user, install
 201                                 <application>Evergreen</application>:</para>
 202                                 <screen><userinput>make STAFF_CLIENT_BUILD_ID=rel_2_0_1 install</userinput></screen>
 203                         </step>
 204                         <step>
 205                                 <para>Change to the <application>Evergreen</application> installation
 206                                 directory:</para>
 207                                 <screen><userinput>cd /home/opensrf/Evergreen-ILS-2.0.1</userinput></screen>
 208                         </step>
 209                         <step>
 210                                 <para>As the <emphasis>root</emphasis> user, change all files to be owned by the
 211                                 <emphasis>opensrf</emphasis> user and group:</para>
 212                                 <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>
 213                         </step>
 214                         <step>
 215                                 <para>As the <systemitem class="username">opensrf</systemitem> user, update server symlink in <filename class="directory">/openils/var/web/xul/</filename>:</para>
 216 <screen><userinput>
 217 cd /openils/var/web/xul/
 218 rm server
 219 ln -s rel_2_0_1/server
 220 </userinput></screen>
 221                         </step>
 222                         <step>
 223                                 <para>Update the <database>evergreen</database> database:</para>
 224                                 <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>
 225 <screen>
 226 <userinput>
 227 psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.1-2.0-upgrade-db.sql evergreen
 228 psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/2.0.0-2.0.1-upgrade-db.sql evergreen
 229 </userinput>
 230 </screen>
 231                                  <note><para>The <filename>1.6.1-2.0-upgrade-db.sql</filename> upgrade script may take a long time (hours) to process
 232                                  on larger systems.</para></note>
 233                         </step>
 234 <step>
 235                                 <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
 236                                 <database>evergreen</database> database. This is required to make the new facet sidebar in OPAC search results work and to upgrade the keyword indexes to use
 237                                 the revised NACO normalization routine.</para>
 238                                 <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
 239                                 may take several hours.</para></note>
 240 <screen><userinput>perl Open-ILS/src/sql/Pg/reingest-1.6-2.0.pl</userinput></screen>
 241 <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/reingest-1.6-2.0.sql evergreen</userinput></screen>
 242                         </step>
 243                         <step>
 244                                 <para>As the <systemitem class="username">opensrf</systemitem> user,
 245                                 copy <filename>/openils/conf/oils_web.xml.example</filename> to <filename>/openils/conf/oils_web.xml</filename>
 246                                 . (If upgrading from 1.6.1.x, <filename>oils_web.xml</filename> should already exist.)</para>
 247                                 <indexterm><primary>configuration files</primary><secondary>oils_web.xml</secondary></indexterm>
 248                                 <screen><userinput>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</userinput></screen>
 249                         </step>
 250                         <step>
 251                                 <para>Update <filename>opensrf_core.xml</filename> and <filename>opensrf.xml</filename> by copying the new example files
 252                                 (<filename>/openils/conf/opensrf_core.xml.example</filename> and <filename>/openils/conf/opensrf.xml</filename>).</para>
 253                                 <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>
 254                                 <screen><userinput>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</userinput></screen>
 255                                 <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>
 256                                 <screen><userinput>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</userinput></screen>
 257                                 <caution><para>Copying these configuration files will remove any customizations you have made to them. Remember to redo your customizations after copying
 258                                 them.</para></caution>
 259                         </step>
 260                         <step>
 261                                 <para>Update <filename>opensrf.xml</filename> with the database connection info:</para>
 262 <screen><userinput>
 263 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config --service all --create-offline --user evergreen \
 264 --password evergreen --hostname localhost --port 5432 --database evergreen
 265 </userinput></screen>
 266                         </step>
 267                         <step>
 268                                 <para>Update /etc/apache2/startup.pl by copying the example from
 269                                 Open-ILS/examples/apache/startup.pl.</para><indexterm><primary>configuration files</primary><secondary>startup.pl</secondary></indexterm>
 270                         </step>
 271                         <step>
 272                                 <para>Update /etc/apache2/eg_vhost.conf by copying the example from
 273                                 Open-ILS/examples/apache/eg_vhost.conf.</para><indexterm><primary>configuration files</primary><secondary>eg_vhost.conf</secondary></indexterm>
 274                         </step>
 275                         <step>
 276                         <para>Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/
 277                         examples/apache/eg.conf.</para><indexterm><primary>configuration files</primary><secondary>eg.conf</secondary></indexterm>
 278                         </step>
 279                         <caution>
 280                                 <para>Copying these Apache configuration files will remove any customizations you have made to them. Remember to redo your customizations after copying
 281                                 them. For example, if you purchased an SSL certificate, you
 282                                 will need to edit <filename>eg.conf</filename> to point to the appropriate SSL certificate files.</para>
 283                                 <indexterm><primary>SSL</primary><secondary>certificates</secondary></indexterm>
 284                         </caution>
 285                 </procedure>
 286         </section>
 287         <section xml:id="testing_after_upgrade">
 288                 <title>Restart Evergreen and Test</title>
 289                 <procedure>
 290                         <step>
 291                                 <para>As the <systemitem class="username">opensrf</systemitem> user, start all
 292                                 <application>Evergreen</application> and <application>OpenSRF</application>
 293                                 services:</para>
 294                                 <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>
 295                         </step>
 296                         <step>
 297                                 <para>As the <systemitem class="username">opensrf</systemitem> user, run <command>autogen</command> to refresh the static
 298                                 organizational data files:</para><indexterm><primary>autogen</primary></indexterm>
 299 <screen><userinput>
 300 cd /openils/bin
 301 ./autogen.sh -c /openils/conf/opensrf_core.xml -u
 302 </userinput></screen>
 303
 304                         </step>
 305                         <step>
 306                                 <para>Start <command>srfsh</command> and try logging in  using your <application>Evergreen</application>
 307                                 username and password:</para>
 308 <screen>
 309 <userinput>/openils/bin/srfsh</userinput>
 310 <prompt>srfsh%</prompt> <userinput>login <option>username</option> <option>password</option></userinput>
 311 </screen>
 312                         </step>
 313                         <step>
 314                                 <para>Start the <application>Apache</application> web server.</para>
 315                         </step>
 316                 </procedure>
 317                 <note>
 318                         <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting
 319                         section</link> of this documentation for tips
 320                         on finding solutions and seeking further assistance from the Evergreen community.</para>
 321                 </note>
 322         </section>
 323         <section xml:id="upgrading_Postgresqlto8.4">
 324                 <title>Upgrading PostgreSQL from 8.2 to 8.4 (if required)</title>
 325                 <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>
 326                 <note><para>The order of the following steps is very important.</para></note><indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>
 327                 <procedure>
 328                         <step>
 329                                 <para>As <systemitem class="username">opensrf</systemitem>, stop the evergreen and opensrf services:</para>
 330                                 <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>
 331                         </step>
 332                         <step>
 333                                 <para><link linkend="backingup">Backup the Evergreen database data</link></para>
 334                         </step>
 335                         <step>
 336                                 <para>Upgrade to Postgresql 8.4 by removing old version and installing Postgresql 8.4</para>
 337                         </step>
 338                         <step>
 339                                 <para>Create an empty Evergreen database in postgresql 8.4 by issuing the following commands as the postgres user:</para>
 340 <screen>
 341 <userinput>
 342 createdb -E UNICODE evergreen
 343 createlang plperl   evergreen
 344 createlang plperlu  evergreen
 345 createlang plpgsql  evergreen
 346 psql -f /usr/share/postgresql/8.4/contrib/tablefunc.sql evergreen
 347 psql -f /usr/share/postgresql/8.4/contrib/tsearch2.sql evergreen
 348 psql -f /usr/share/postgresql/8.4/contrib/pgxml.sql evergreen
 349 </userinput>
 350 </screen>
 351                         </step>
 352                         <step>
 353                                 <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>
 354                                 <screen><userinput>createuser -P -s evergreen</userinput></screen>
 355                                 <para>Enter the password for the new PostgreSQL superuser (<systemitem class="username">evergreen</systemitem>)</para>
 356                         </step>
 357                         <step>
 358                                 <para>Restore data from backup created in step 1.</para>
 359                         </step>
 360                         <step>
 361                                 <para>To point tsearch2 to proper function names in 8.4, run the SQL script
 362                                 <filename>/home/opensrf/Evergreen-ILS*/Open-ILS/src/sql/Pg/000.english.pg84.fts-config.sql</filename> using the <command>psql</command> command.</para>
 363                                 <screen><userinput>cd /home/opensrf/Evergreen-ILS*</userinput></screen>
 364                                 <screen><userinput>psql -f /Open-ILS/src/sql/Pg/000.english.pg84.fts-config.sql evergreen</userinput></screen>
 365                         </step>
 366                         <step>
 367                                 <para><link linkend="upgraderestart">Restart Evergreen and OpenSRF services</link></para>
 368                         </step>
 369                         <step>
 370                                 <para>For additional information regarding upgrading PostgreSQL, see the following documentation in PostgreSQL:</para>
 371                                 <para><ulink url="http://www.postgresql.org/docs/8.4/static/install-upgrading.html" /></para>
 372                                 <para><ulink url="http://www.postgresql.org/docs/8.4/interactive/textsearch-migration.html" />
 373                                 </para>
 374                                 <para><ulink url="http://www.postgresql.org/docs/current/static/tsearch2.html#AEN102824" /></para>
 375                         </step>
 376                 </procedure>
 377         </section>
 378 </chapter>