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 <emphasis>root</emphasis>, 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 <emphasis>opensrf</emphasis> user, stop all \r
  22                                 <application>Evergreen</application>\r
  23                                 and <application>OpenSRF</application> services:</para>\r
  24                                 <screen>osrf_ctl.sh -l -a stop_all</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="backupevergreendatabase">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 opensrf user, download and extract the source files for OpenSRF \r
  41                                 1.2:</para>\r
  42                                 <screen>wget http://open-ils.org/downloads/OpenSRF-1.2.2.tar.gz</screen>\r
  43                                 <screen>tar xzf OpenSRF-1.2.2.tar.gz</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 root user, install the software prerequisites using the automatic \r
  51                                 prerequisite installer.</para> \r
  52                                 <screen>aptitude install make</screen>\r
  53                                 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
  54                                 \r
  55                                 <para>Replace <emphasis>[distribution]</emphasis> below with the following value \r
  56                                 for your distribution:</para>\r
  57                                 <itemizedlist>\r
  58                                         <listitem>\r
  59                                                 <para><emphasis>debian-etch</emphasis> for Debian Etch (4.0)<indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>\r
  60                                         </listitem>\r
  61                                         <listitem>\r
  62                                                 <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>\r
  63                                         </listitem>\r
  64                                         <listitem>\r
  65                                         <para><emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron (8.04)<indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>\r
  66                                         </listitem>\r
  67                                         <listitem>\r
  68                                                 <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex \r
  69                                                 (8.10)</para>\r
  70                                         </listitem>\r
  71                                         <listitem>\r
  72                                                 <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope \r
  73                                                 (9.04)</para>\r
  74                                         </listitem>\r
  75                                         <listitem>\r
  76                                                 <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala \r
  77                                                 (9.10)</para>\r
  78                                         </listitem>\r
  79                                 </itemizedlist>\r
  80                                 <screen>make -f src/extras/Makefile.install <emphasis>[distribution]</emphasis></screen>\r
  81                                 <para>This will install a number of packages required by OpenSRF on your system, \r
  82                                 including some Perl modules from CPAN<indexterm><primary>programming language</primary><secondary>Perl</secondary>\r
  83                                 <tertiary>CPAN</tertiary>\r
  84                                 </indexterm>. You can say <quote>no</quote> to the initial CPAN \r
  85                                 configuration prompt to allow it to automatically configure itself to download \r
  86                                 and install Perl modules from CPAN. The CPAN installer will ask you a number of \r
  87                                 times whether it should install prerequisite modules - say <quote>yes</quote>.</para>\r
  88                         </step>\r
  89                         <step>  \r
  90                                 <para>As the opensrf user, configure and compile OpenSRF:</para> \r
  91                                 <note>You can include the –enable-python and –enable-java configure options if \r
  92                                 you want to include support for Python<indexterm><primary>programming language</primary><secondary>Python</secondary>\r
  93                                 </indexterm> and Java<indexterm><primary>programming language</primary><secondary>Java</secondary>\r
  94                                 </indexterm>, respectively.</note>\r
  95                                 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
  96                                 <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>\r
  97                                 <screen>make</screen>\r
  98                                 \r
  99                         </step>\r
 100                         <step>  \r
 101                                 <para>As the root user, return to your OpenSRF build directory and install \r
 102                                 OpenSRF:</para>\r
 103                                 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
 104                                 <screen>make install</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>chown -R opensrf:opensrf /openils</screen>\r
 110                         </step>\r
 111                         <step>\r
 112                                 <para>Restart and Test OpenSRF</para>\r
 113                                 <screen>osrf_ctl.sh -l -a start_all</screen>\r
 114                                 <screen>/openils/bin/srfsh</screen>\r
 115                                 <screen>srfsh#  request opensrf.math add 2 2</screen>\r
 116                                 <para>You should see output like:</para>\r
 117                                 <screen>Received Data: 4</screen>\r
 118                                 <screen></screen>\r
 119                                 <screen>------------------------------------</screen>\r
 120                                 <screen>Request Completed Successfully</screen>\r
 121                                 <screen>Request Time in seconds: 0.007519</screen>\r
 122                                 <screen>------------------------------------</screen>\r
 123                                 <screen></screen>\r
 124                                 <screen>srfsh#</screen> \r
 125                                 <para>If test <emphasis>Completed Successfully</emphasis> move onto next section. \r
 126                                 If not, refer to <link linkend="troubleshooting">troubleshooting</link> section \r
 127                                 of this documentation.</para> \r
 128                         </step> \r
 129                 </procedure>    \r
 130         </simplesect>\r
 131         <simplesect>\r
 132                 <title>Upgrade <application>Evergreen</application> to 1.6</title>\r
 133                 <procedure>\r
 134                         <step>\r
 135                                 <para>As the <emphasis>opensrf</emphasis> user, download and extract Evergreen 1.6\r
 136                                 </para>\r
 137                                 <screen>wget http://open-ils.org/downloads/Evergreen-ILS-1.6.0.8.tar.gz</screen>\r
 138                                 <screen>tar xzf Evergreen-ILS-1.6.0.8.tar.gz</screen>\r
 139                                 <note><para>For the latest edition of Evergreen check the Evergreen download page at\r
 140                                 <ulink url="http://www.open-ils.org/downloads.php" /> and adjust upgrading instructions accordingly.</para></note>\r
 141                         </step>\r
 142                         <step>\r
 143                                 <para>As the <emphasis>root</emphasis> user, install the prerequisites:</para> \r
 144                                 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen> \r
 145                                 <para>On the next command, replace <emphasis>[distribution]</emphasis> with one of \r
 146                                 these values for your distribution of Debian or Ubuntu:</para>\r
 147                                 <itemizedlist>\r
 148                                         <listitem>\r
 149                                                 <para><emphasis>debian-etch</emphasis> for Debian Etch (4.0)</para>\r
 150                                         </listitem>\r
 151                                         <listitem>\r
 152                                                 <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>\r
 153                                         </listitem>\r
 154                                         <listitem>\r
 155                                                 <para><emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron \r
 156                                                 (8.04)</para>\r
 157                                         </listitem>\r
 158                                         <listitem>\r
 159                                                 <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex \r
 160                                                 (8.10)</para>\r
 161                                         </listitem>\r
 162                                         <listitem>\r
 163                                                 <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope \r
 164                                                 (9.04)</para>\r
 165                                         </listitem>\r
 166                                         <listitem>\r
 167                                                 <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala \r
 168                                                 (9.10)</para>\r
 169                                         </listitem>\r
 170                                 </itemizedlist>\r
 171                                 <screen>make -f Open-ILS/src/extras/Makefile.install <emphasis>[distribution]</emphasis></screen>\r
 172                         </step>\r
 173                         <step>\r
 174                                 <para>As the <emphasis>opensrf</emphasis> user, configure and compile \r
 175                                 <application>Evergreen</application>:</para>\r
 176                                 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen>\r
 177                                 <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>\r
 178                                 <screen>make</screen>\r
 179                         </step>\r
 180                         <step>\r
 181                                 <para>As the <emphasis>root</emphasis> user, install \r
 182                                 <application>Evergreen</application>:</para>\r
 183                                 <screen>make STAFF_CLIENT_BUILD_ID=rel_1_6_0_8 install</screen>\r
 184                         </step>\r
 185                         <step>\r
 186                                 <para>Change to the <application>Evergreen</application> installation \r
 187                                 directory:</para>\r
 188                                 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen>\r
 189                         </step>\r
 190                         <step>\r
 191                                 <para>As the <emphasis>root</emphasis> user, change all files to be owned by the \r
 192                                 <emphasis>opensrf</emphasis> user and group:</para>\r
 193                                 <screen>chown -R opensrf:opensrf /openils</screen>\r
 194                         </step>                 \r
 195                         <step>\r
 196                                 <para>As the <emphasis>root</emphasis> user, build live-db-setup.pl for the cgi-bin \r
 197                                 bootstrapping scripts and offline-config.pl for the offline staff client data \r
 198                                 uploader:</para>\r
 199                                 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen>                         \r
 200                                 <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl --create-bootstrap --create-offline --user evergreen \</screen>\r
 201                                 <screen>--password evergreen --hostname localhost --port 5432 --database evergreen</screen>\r
 202                         </step>\r
 203                         <step>\r
 204                                 <para>As the opensrf user, update server symlink in <filename class="directory">/openils/var/web/xul/</filename>:</para>\r
 205                                 <screen>cd /openils/var/web/xul/</screen>\r
 206                                 <screen>rm server</screen>\r
 207                                 <screen>ln -s rel_1_6_0_8/server</screen>\r
 208                         </step>\r
 209                         \r
 210                         <step>\r
 211                                 <para>Update the Evergreen database:</para>\r
 212                                 <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
 213                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.4.0.5-1.6.0.0-upgrade-db.sql evergreen</screen> \r
 214                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.0-1.6.0.1-upgrade-db.sql evergreen</screen> \r
 215                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.1-1.6.0.2-upgrade-db.sql evergreen</screen> \r
 216                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.2-1.6.0.3-upgrade-db.sql evergreen</screen> \r
 217                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.3-1.6.0.4-upgrade-db.sql evergreen</screen> \r
 218                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.4-1.6.0.5-upgrade-db.sql evergreen</screen>  \r
 219                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.5-1.6.0.6-upgrade-db.sql evergreen</screen> \r
 220                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.6-1.6.0.7-upgrade-db.sql evergreen</screen> \r
 221                                 <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.7-1.6.0.8-upgrade-db.sql evergreen</screen> \r
 222                                 <para>Download and run the the billing view hot-fix script</para>                               \r
 223                                 <screen>wget http://www.open-ils.org/downloads/1.6.0-mmbxs-cleanup.sql</screen>\r
 224                                 <screen>psql -U evergreen -h localhost -f 1.6.0-mmbxs-cleanup.sql</screen>      \r
 225                         </step>\r
 226                         <step>\r
 227                                 <para>As the <emphasis>opensrf</emphasis> user, \r
 228                                 copy /openils/conf/oils_web.xml.example to /openils/conf/oils_web.xml \r
 229                                 (needed for acquisitions templates).</para>\r
 230                                 <screen>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</screen>\r
 231                         </step>\r
 232                         <step>\r
 233                                 <para>Update opensrf_core.xml and opensrf.xml by copying the new example files (/\r
 234                                 openils/conf/opensrf_core.xml.example and /openils/conf/opensrf.xml).</para>\r
 235                                 <screen>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</screen>\r
 236                                 <screen>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</screen>\r
 237                         </step>\r
 238                         <step>\r
 239                                 <para>Update opensrf.xml with the database connection info:</para>\r
 240                                 <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config --service all --user evergreen \</screen>\r
 241                                 <screen>--password evergreen --hostname localhost --port 5432 --database evergreen</screen>\r
 242                         </step>\r
 243                         <step>\r
 244                                 <para>Update /etc/apache2/startup.pl by copying the example from \r
 245                                 Open-ILS/examples/apache/startup.pl.</para>\r
 246                         </step>\r
 247                         <step>\r
 248                                 <para>Update /etc/apache2/eg_vhost.conf by copying the example from \r
 249                                 Open-ILS/examples/apache/eg_vhost.conf.</para>\r
 250                         </step>\r
 251                         <step>\r
 252                         <para>Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/\r
 253                         examples/apache/eg.conf.</para>\r
 254                         </step>\r
 255                         <step>\r
 256                                 <para>Recover customizations you have made to the <application>Apache</application><indexterm><primary>Apache</primary></indexterm> \r
 257                                 configuration files. For example, if you purchased an SSL certificate<indexterm><primary>SSL certificate</primary></indexterm>, you \r
 258                                 will need to edit eg.conf to point to the appropriate SSL certificate files.</para>\r
 259                         </step> \r
 260                 </procedure>    \r
 261         </simplesect>\r
 262         <simplesect>\r
 263                 <para>Restart Evergreen and Test</para>\r
 264                 <procedure>\r
 265                         <step>\r
 266                                 <para>As the <emphasis>opensrf</emphasis> user, start all \r
 267                                 <application>Evergreen</application> and <application>OpenSRF</application> \r
 268                                 services:</para>\r
 269                                 <screen>osrf_ctl.sh -l -a start_all</screen>\r
 270                         </step>\r
 271                         <step>\r
 272                                 <para>As the <emphasis>opensrf</emphasis> user, run autogen to refresh the static \r
 273                                 organizational data files:</para>\r
 274                                 <screen>cd /openils/bin</screen>\r
 275                                 <screen>./autogen.sh -c /openils/conf/opensrf_core.xml -u</screen>\r
 276                                         \r
 277                         </step>\r
 278                         <step>\r
 279                                 <para>Start srfsh and try logging in  using your <application>Evergreen</application>\r
 280                                 username and password:</para>\r
 281                                 <screen>/openils/bin/srfsh</screen> \r
 282                                 <screen>srfsh% login <emphasis>username password</emphasis></screen> \r
 283                         </step> \r
 284                         <step>\r
 285                                 <para>Start the <application>Apache</application> web server.</para>\r
 286                         </step>\r
 287                 </procedure>\r
 288         </simplesect>\r
 289         <note>\r
 290                 <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting \r
 291                 section</link> of this documentation for tips \r
 292                 on finding solutions and seeking further assistance from the Evergreen community.</para>  \r
 293         </note>\r
 294 </chapter>\r