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">
5 <title>Upgrading Evergreen from 1.4 to 1.6</title>
7 <para>This Chapter will explain the step-by-step process of upgrading <application>Evergreen
8 </application> from version 1.4 to 1.6, including steps to upgrade <application>OpenSRF</application>. Before
9 upgrading, it is important to carefully plan an upgrade strategy to minimise system downtime and
10 service interruptions. All of the steps in this chapter are to be completed from the command line.</para>
15 <para>Stop Evergreen and back up data.</para>
18 <para>As <emphasis>root</emphasis>, stop the <application>Apache</application>
19 web server<indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm>.</para>
22 <para>As the <emphasis>opensrf</emphasis> user, stop all
23 <application>Evergreen</application>
24 and <application>OpenSRF</application> services:</para>
25 <screen>osrf_ctl.sh -l -a stop_all</screen>
28 <para>Back up of the <filename class='directory'>/openils</filename>
32 <para><link linkend="backupevergreendatabase">Back up the <application>evergreen
33 </application> database</link>.</para>
38 <para>Upgrade OpenSRF<indexterm><primary>OpenSRF</primary></indexterm> to 1.2</para>
41 <para>As the opensrf user, download and extract the source files for OpenSRF
44 http://open-ils.org/downloads/OpenSRF-1.2.2.tar.gz</screen>
45 <screen>tar xzf OpenSRF-1.2.2.tar.gz</screen>
46 <para>A new directory OpenSRF-1.2.2 will be created</para>
47 <note><para>For the latest edition of OpenSRF, check the Evergreen download page at
48 <ulink url="http://www.open-ils.org/downloads.php" />.
52 <para>As the root user, install the software prerequisites using the automatic
53 prerequisite installer.</para>
54 <screen>aptitude install make</screen>
55 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>
56 <para>Replace <emphasis>[distribution]</emphasis> below with the following value
57 for your distribution:</para>
60 <para><emphasis>debian-etch</emphasis> for Debian Etch (4.0)<indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>
63 <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>
66 <para><emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron (8.04)<indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>
69 <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex
73 <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope
77 <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala
81 <screen>make -f src/extras/Makefile.install <emphasis>[distribution]</emphasis>
83 <para>This will install a number of packages required by OpenSRF on your system,
84 including some Perl modules from CPAN<indexterm><primary>programming language</primary><secondary>Perl</secondary><tertiary>CPAN</tertiary>
85 </indexterm>. You can say “no” to the initial CPAN
86 configuration prompt to allow it to automatically configure itself to download
87 and install Perl modules from CPAN. The CPAN installer will ask you a number of
88 times whether it should install prerequisite modules - say “yes”.</para>
91 <para>As the opensrf user, configure and compile OpenSRF:</para>
92 <note>You can include the –enable-python and –enable-java configure options if
93 you want to include support for Python<indexterm><primary>programming language</primary><secondary>Python</secondary>
94 </indexterm> and Java<indexterm><primary>programming language</primary><secondary>Java</secondary>
95 </indexterm>, respectively.</note>
96 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>
97 <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>
101 <para>As the root user, return to your OpenSRF build directory and install
103 <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>
104 <screen>make install</screen>
107 <para>As the root user, change the ownership of the installed files to the opensrf
109 <screen>chown -R opensrf:opensrf /openils</screen>
112 <para>Restart and Test OpenSRF</para>
113 <screen>osrf_ctl.sh -l -a start_all</screen>
114 <screen>/openils/bin/srfsh</screen>
115 <screen>srfsh# request opensrf.math add 2 2</screen>
116 <para>You should see output like:</para>
117 <screen>Received Data: 4</screen>
119 <screen>------------------------------------</screen>
120 <screen>Request Completed Successfully</screen>
121 <screen>Request Time in seconds: 0.007519</screen>
122 <screen>------------------------------------</screen>
124 <screen>srfsh#</screen>
125 <para>If test <emphasis>Completed Successfully</emphasis> move onto next section.
126 If not, refer to <link linkend="troubleshooting">troubleshooting</link> section
127 of this documentation.</para>
132 <para>Upgrade <application>Evergreen</application> to 1.6</para>
135 <para>As the <emphasis>opensrf</emphasis> user, download and extract Evergreen 1.6
137 <screen>wget \</screen>
138 <screen>http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.0.3.tar.gz</screen>
139 <screen>tar xzf Evergreen-ILS-1.6.0.3.tar.gz</screen>
140 <note><para>For the latest edition of Evergreen check the Evergreen download page at
141 <ulink url="http://www.open-ils.org/downloads.php" /></para></note>
144 <para>As the <emphasis>root</emphasis> user, install the prerequisites:</para>
145 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.3</screen>
146 <para>On the next command, replace <emphasis>[distribution]</emphasis> with one of
147 these values for your distribution of Debian or Ubuntu:</para>
150 <para><emphasis>debian-etch</emphasis> for Debian Etch (4.0)</para>
153 <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>
156 <para><emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron
160 <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex
164 <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope
168 <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala
172 <screen>make -f Open-ILS/src/extras/Makefile.install <emphasis>[distribution]</emphasis></screen>
175 <para>As the <emphasis>opensrf</emphasis> user, configure and compile
176 <application>Evergreen</application>:</para>
177 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.3</screen>
178 <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>
179 <screen>make</screen>
182 <para>As the <emphasis>root</emphasis> user, install
183 <application>Evergreen</application>:</para>
184 <screen>make STAFF_CLIENT_BUILD_ID=rel_1_6_0_3 install</screen>
187 <para>Change to the <application>Evergreen</application> installation
189 <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.3</screen>
192 <para>As the <emphasis>root</emphasis> user, build live-db-setup.pl for the cgi-bin
193 bootstrapping scripts and offline-config.pl for the offline staff client data
195 <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl \</screen>
196 <screen>--create-bootstrap --create-offline --user evergreen \</screen>
197 <screen>--password evergreen --hostname localhost --port 5432 \</screen>
198 <screen>--database evergreen</screen>
201 <para>As the <emphasis>root</emphasis> user, change all files to be owned by the
202 <emphasis>opensrf</emphasis> user and group:</para>
203 <screen>chown -R opensrf:opensrf /openils</screen>
206 <para>Update the Evergreen database</para>
207 <screen>psql -U evergreen -h localhost \</screen>
208 <screen>-f Open-ILS/src/sql/Pg/1.4.0.5-1.6.0.0-upgrade-db.sql evergreen</screen>
209 <screen>psql -U evergreen -h localhost \</screen>
210 <screen>-f Open-ILS/src/sql/Pg/1.6.0.0-1.6.0.1-upgrade-db.sql evergreen</screen>
211 <screen>psql -U evergreen -h localhost \</screen>
212 <screen>-f Open-ILS/src/sql/Pg/1.6.0.1-1.6.0.2-upgrade-db.sql evergreen</screen>
213 <screen>psql -U evergreen -h localhost \</screen>
214 <screen>-f Open-ILS/src/sql/Pg/1.6.0.2-1.6.0.3-upgrade-db.sql evergreen</screen>
215 <screen>psql -U evergreen -h localhost \</screen>
216 <screen>psql -U evergreen -h localhost -f 1.6.0-mmbxs-cleanup.sql \
220 <para>As the <emphasis>opensrf</emphasis> user,
221 copy /openils/conf/oils_web.xml.example to /openils/conf/oils_web.xml
222 (needed for acquisitions templates).</para>
223 <screen>cp /openils/conf/oils_web.xml.example \
224 /openils/conf/oils_web.xml</screen>
227 <para>Update opensrf_core.xml and opensrf.xml by copying the new example files (/
228 openils/conf/opensrf_core.xml.example and /openils/conf/opensrf.xml).</para>
229 <screen>cp /openils/conf/opensrf_core.xml.example \</screen>
230 <screen>/openils/conf/opensrf_core.xml</screen>
231 <screen>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</screen>
234 <para>Update opensrf.xml with the database connection info:</para>
235 <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl \</screen>
236 <screen>--update-config --service all --user evergreen \</screen>
237 <screen>--password evergreen --hostname localhost --port 5432 \</screen>
238 <screen>--database evergreen</screen>
241 <para>Update /etc/apache2/startup.pl by copying the example from
242 Open-ILS/examples/apache/startup.pl.</para>
245 <para>Update /etc/apache2/eg_vhost.conf by copying the example from
246 Open-ILS/examples/apache/eg_vhost.conf.</para>
249 <para>Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/
250 examples/apache/eg.conf.</para>
253 <para>Recover customizations you have made to the <application>Apache</application>
254 configuration files. For example, if you purchased an SSL certificate, you
255 will need to edit eg.conf to point to the appropriate SSL certificate files.</para>
260 <para>Restart Evergreen and Test</para>
263 <para>As the <emphasis>opensrf</emphasis> user, start all
264 <application>Evergreen</application> and <application>OpenSRF</application>
266 <screen>osrf_ctl.sh -l -a start_all</screen>
269 <para>As the <emphasis>opensrf</emphasis> user, run autogen to refresh the static
270 organizational data files:</para>
271 <screen>cd /openils/bin</screen>
272 <screen>./autogen.sh -c /openils/conf/opensrf_core.xml -u</screen>
275 <para>Start srfsh and try logging in using your <application>Evergreen</application>
276 username and password:</para>
277 <screen>/openils/bin/srfsh</screen>
278 <screen>srfsh% login <emphasis>username password</emphasis></screen>
281 <para>Start the <application>Apache</application> web server.</para>
287 <title>Troubleshooting:</title>
288 <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting
289 section</link> of this documentation for tips
290 on finding solutions and seeking further assistance from the Evergreen community.</para>