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