Changeset 3292


Ignore:
Timestamp:
May 7, 2007, 9:18:54 AM (14 years ago)
Author:
Jari Häkkinen
Message:

Addresses #516. Upgrade instructions writing done.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/admindoc/installation_upgrade.xml

    r3246 r3292  
    4444    The first time installation is expected to be performed only once,
    4545    and optionally followed by a migration. The migration can only be
    46     done on a pristine (empty) BASE 2 server, and migration from
     46    done to a pristine (empty) BASE 2 server, and migration from
    4747    several BASE 1 installations to one BASE 2 server is not
    4848    supported.
     
    5050
    5151  <note>
    52     <para>
    53       These instructions apply only to the version of BASE 2 that this
    54       document is shipped with.
    55     </para>
     52    These instructions apply only to the BASE release which this
     53    document is a part of.
    5654  </note>
    5755
    58     <sect1>
     56    <sect1 id="installation_upgrade.upgrade">
    5957      <title>Upgrade instructions</title>
    60       <para></para>
    61     </sect1>
    62 
    63     <sect1>
     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">
    64253      <title>Installation instructions</title>
    65254      <para></para>
    66255    </sect1>
    67256
    68     <sect1>
     257
     258    <sect1 id="installation_upgrade.migration">
    69259      <title>Migration instructions</title>
    70260      <para></para>
Note: See TracChangeset for help on using the changeset viewer.