1.6/admin/Upgrading-Evergreen_1.6.xml

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