source: trunk/doc/src/docbook/admindoc/installation_upgrade.xml @ 3292

Last change on this file since 3292 was 3292, checked in by Jari Häkkinen, 14 years ago

Addresses #516. Upgrade instructions writing done.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 8.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: installation_upgrade.xml 3292 2007-05-07 07:18:54Z jari $
7
8  Copyright (C) Authors contributing to this file.
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="installation_upgrade">
30  <?dbhtml dir="installation_upgrade"?>
31
32  <title>Installation, migration, and upgrade instructions</title>
33
34  <para>
35    This chapter is divided into three parts. First, the process of
36    upgrading a BASE 2 server is described. It is assumed that there
37    is a running server. Then, the first time installation
38    instructions follows, and the chapter is concluded with
39    information on how to migrate data from a BASE 1.2.17 server to a
40    BASE 2 server.
41  </para>
42
43  <para>
44    The first time installation is expected to be performed only once,
45    and optionally followed by a migration. The migration can only be
46    done to a pristine (empty) BASE 2 server, and migration from
47    several BASE 1 installations to one BASE 2 server is not
48    supported.
49  </para>
50
51  <note>
52    These instructions apply only to the BASE release which this
53    document is a part of.
54  </note>
55
56    <sect1 id="installation_upgrade.upgrade">
57      <title>Upgrade instructions</title>
58
59      <important>
60        Note to PostgreSQL users: Upgrading BASE to versions earlier
61        than v2.2 is not be safe with an PostgreSQL database engine
62        due to a bug in Hibernate. The problem is reported to
63        Hibernate developers. There now exists a workaround for this
64        problem. Read more about the workaround on
65        the <ulink
66        url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
67        Postgres database prior to BASE 2.2</ulink> page. This fix is
68        not needed for the release which this document is a part of.
69      </important>
70
71      <para>
72        As always, backup your database before attempting an
73        upgrade. The BASE team performs extensive testing before
74        releasing a new version of BASE but there are always a
75        possibility for unexpected events during upgrades. In upgrades
76        requiring a change in the underlying database there is no
77        (supported) way to revert to a previous version of BASE using
78        BASE tools, you need to use your backup for this use case.
79      </para>
80
81      <para>
82        The strategy here is to install the new BASE release to
83        another directory than the one in use. This requires transfer
84        of configuration settings to the new install but more on that
85        below.
86      </para>
87
88      <variablelist>
89        <varlistentry>
90          <term>Shut down the tomcat server</term>
91          <listitem>
92            <para>
93              If the BASE application is not shut down already, it is
94              time to do it now. Do something like <command>sudo
95              /etc/init.d/tomcat5.5 stop</command>
96            </para>
97          </listitem>
98        </varlistentry>
99
100        <varlistentry>
101          <term>Rename your current server</term>
102          <listitem>
103            <para>
104              Rename your current BASE 2 installation <command>mv
105                /path/to/base /path/to/base_old</command>.
106            </para>
107          </listitem>
108        </varlistentry>
109
110        <varlistentry>
111          <term>Download and unpack BASE</term>
112          <listitem>
113            <para>
114              There are severeal ways to download BASE. Please refer
115              to section
116              <xref linkend="resources.home_page.download"/> for
117              information on downloading BASE, and select the item
118              matching your download option:
119            </para>
120
121            <variablelist>
122              <varlistentry>
123                <term><emphasis>Pre-compiled package</emphasis></term>
124                <listitem>
125                  <para>
126                    If you selected to download a pre-compiled
127                    package, unpack the downloaded file
128                    with <command>tar zxpf base-...tar.gz</command>.
129                  </para>
130                </listitem>
131              </varlistentry>
132
133              <varlistentry>
134                <term><emphasis>Source package</emphasis></term>
135                <listitem>
136                  <para>
137                    If you selected to download a source package,
138                    unpack the downloaded file with <command>tar zxpf
139                    base-...src.tar.gz</command>. Change to the new
140                    direcotry, and issue <command>ant
141                    package.bin</command>. This will create a binary
142                    package in the current directory. Unpack this new
143                    package (outside of the source file hierarchy).
144                  </para>
145                </listitem>
146              </varlistentry>
147
148              <varlistentry>
149                <term><emphasis>Subversion checkout</emphasis></term>
150                <listitem>
151                  <para>
152                    This option is for advanced users only and is not
153                    covered here. Please refer
154                    to <ulink
155                    url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
156                    builing BASE document</ulink> for information on
157                    this download option.
158                  </para>
159                </listitem>
160              </varlistentry>
161
162            </variablelist>
163          </listitem>
164
165        </varlistentry>
166
167        <varlistentry>
168          <term>Transfer files and settings</term>
169          <listitem>
170            <para>
171              Settings from the previous installation must be
172              transferred to the new installation. This is most easily
173              done by comparing the configuration files from the
174              previous install with the new files. Do not just copy
175              the old files to the new install since new options may
176              have appeared.
177            </para>
178            <para>
179              In the main BASE configuration file,
180              <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
181              fields that needs to be transferred are usually
182              <emphasis>db.username</emphasis>,
183              <emphasis>db.password</emphasis>,
184              and <emphasis>userfiles</emphasis>.
185            </para>
186            <para>
187              Local settings in the raw data
188              tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
189              may need to be transferred.
190            </para>
191          </listitem>
192        </varlistentry>
193
194        <varlistentry>
195          <term>Updating database schema</term>
196          <listitem>
197            <para>
198              It is recommended that you also perform an update of
199              your database schema.  Running the update scripts are
200              not always necessary when upgrading BASE, but the
201              running the update scripts are safe even in cases when
202              there is no need to run them. Change directory
203              to <filename
204              class="direcotry">/path/to/base/bin/</filename> and
205              issue
206              <command>
207                <literallayout>sh ./updatedb.sh <emphasis>base_root_password</emphasis>
208                sh ./updateindexes.sh <emphasis>base_root_password</emphasis></literallayout>
209              </command>
210              where <emphasis>base_root_password</emphasis> is the
211              password for the root user account within the BASE
212              application.
213            </para>
214          </listitem>
215        </varlistentry>
216
217        <varlistentry>
218          <term>Remove tomcat cache</term>
219          <listitem>
220            <para>
221              As tomcat user, remove cached files and directories. Do
222              something like
223              <command>
224                <literallayout>cd /usr/share/apache-tomcat-5.5.15/
225                rm -rf work/Catalina</literallayout>
226              </command>
227            </para>
228          </listitem>
229        </varlistentry>
230
231        <varlistentry>
232          <term>Start tomcat</term>
233          <listitem>
234            <para>
235              Start the tomcat server:
236              <command>
237                <literallayout>sudo /etc/init.d/tomcat5.5 start</literallayout>
238              </command>
239            </para>
240          </listitem>
241        </varlistentry>
242
243      </variablelist>
244
245      <para>
246        Done! Upgrade of BASE is finished.
247      </para>
248
249    </sect1>      <!-- Upgrade instructions -->
250
251
252    <sect1 id="installation_upgrade.isntallation">
253      <title>Installation instructions</title>
254      <para></para>
255    </sect1>
256
257
258    <sect1 id="installation_upgrade.migration">
259      <title>Migration instructions</title>
260      <para></para>
261    </sect1>
262
263</chapter>
Note: See TracBrowser for help on using the repository browser.