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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: installation_upgrade.xml 3350 2007-05-19 07:56:35Z jari $

  Copyright (C) Authors contributing to this file.

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="installation_upgrade">
  <?dbhtml dir="installation_upgrade"?>

  <title>Installation, migration, and upgrade instructions</title>

  <note>
    These instructions apply only to the BASE release which this
    document is a part of.
  </note>

  <para>
    This chapter is divided into three parts. First, the process of
    upgrading a BASE 2 server is described. It is assumed that there
    is a running server. Then, the first time installation
    instructions follows, and the chapter is concluded with
    information on how to migrate data from a BASE 1.2.17 server to a
    BASE 2 server.
  </para>

  <para>
    The first time installation is expected to be performed only once,
    and optionally followed by a migration. The migration can only be
    done to a pristine (empty) BASE 2 server, and migration from
    several BASE 1 installations to one BASE 2 server is not
    supported.
  </para>

  <para>
    The instructions here assume
    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
    on the server side. Other servlet engines may work but we only
    test tomcat.
  </para>


  <sect1 id="installation_upgrade.upgrade">
    <title>Upgrade instructions</title>

    <important>
      Note to PostgreSQL users: Upgrading BASE to versions earlier
      than v2.2 is not be safe with an PostgreSQL database engine due
      to a bug in Hibernate. The problem is reported to Hibernate
      developers. There now exists a workaround for this problem. Read
      more about the workaround on
      the <ulink
      url="http://base.thep.lu.se/wiki/UpgradePostgres">Upgrading a
      Postgres database prior to BASE 2.2</ulink> page. This fix is
      not needed for the release which this document is a part of.
    </important>

    <para>
      As always, backup your database before attempting an
      upgrade. The BASE team performs extensive testing before
      releasing a new version of BASE but there are always a
      possibility for unexpected events during upgrades. In upgrades
      requiring a change in the underlying database there is no
      (supported) way to revert to a previous version of BASE using
      BASE tools, you need to use your backup for this use case.
    </para>

    <para>
      The strategy here is to install the new BASE release to another
      directory than the one in use. This requires transfer of
      configuration settings to the new install but more on that
      below.
    </para>

    <variablelist>
      <varlistentry>
        <term>Shut down the tomcat server</term>
        <listitem>
          <para>
            If the BASE application is not shut down already, it is
            time to do it now. Do something like <command>sudo
            /etc/init.d/tomcat5.5 stop</command>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Rename your current server</term>
        <listitem>
          <para>
            Rename your current BASE 2 installation <command>mv
              /path/to/base /path/to/base_old</command>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Download and unpack BASE</term>
        <listitem>
          <para>
            There are several ways to download BASE. Please refer to
            section <xref linkend="resources.home_page.download"/> for
            information on downloading BASE, and select the item
            matching your download option:
          </para>

          <variablelist>
            <varlistentry>
              <term><emphasis>Pre-compiled package</emphasis></term>
              <listitem>
                <para>
                  If you selected to download a pre-compiled package,
                  unpack the downloaded file with <command>tar zxpf
                  base-...tar.gz</command>.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis>Source package</emphasis></term>
              <listitem>
                <para>
                  If you selected to download a source package, unpack
                  the downloaded file with <command>tar zxpf
                  base-...src.tar.gz</command>. Change to the new
                  directory, and issue <command>ant
                  package.bin</command>. This will create a binary
                  package in the current directory. Unpack this new
                  package (outside of the source file hierarchy).
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis>Subversion checkout</emphasis></term>
              <listitem>
                <para>
                  This option is for advanced users only and is not
                  covered here. Please refer
                  to <ulink
                  url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
                  building BASE document</ulink> for information on
                  this download option.
                </para>
              </listitem>
            </varlistentry>

          </variablelist>
        </listitem>

      </varlistentry>

      <varlistentry>
        <term>Transfer files and settings</term>
        <listitem>
          <para>
            Settings from the previous installation must be
            transferred to the new installation. This is most easily
            done by comparing the configuration files from the
            previous install with the new files. Do not just copy the
            old files to the new install since new options may have
            appeared.
          </para>
          <para>
            In the main BASE configuration file,
            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
            fields that needs to be transferred are usually
            <emphasis>db.username</emphasis>,
            <emphasis>db.password</emphasis>,
            and <emphasis>userfiles</emphasis>.
          </para>
          <para>
            Local settings in the raw data
            tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
            may need to be transferred.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Updating database schema</term>
        <listitem>
          <para>
            It is recommended that you also perform an update of your
            database schema.  Running the update scripts are not
            always necessary when upgrading BASE, but the running the
            update scripts are safe even in cases when there is no
            need to run them. Change directory
            to <filename
            class="direcotry">/path/to/base/bin/</filename> and issue
            <programlisting>
sh ./updatedb.sh <emphasis>base_root_password</emphasis>
sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
</programlisting>
            where <emphasis>base_root_password</emphasis> is the
            password for the root user account within the BASE
            application.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Remove tomcat cache</term>
        <listitem>
          <para>
            As tomcat user, remove cached files and directories. Do
            something like
            <programlisting>
cd /usr/share/apache-tomcat-5.5.15/
rm -rf work/Catalina
</programlisting>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Start tomcat</term>
        <listitem>
          <para>
            Start the tomcat server: <command>sudo
              /etc/init.d/tomcat5.5 start</command>
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>
      Done! Upgrade of BASE is finished.
    </para>

  </sect1>      <!-- Upgrade instructions -->




  <sect1 id="installation_upgrade.installation">
    <title>Installation instructions</title>

    <variablelist>

      <varlistentry>
        <term>Java</term>
        <listitem>
          <para>
            Download and install Java SDK 1.5, available from
            <ulink url="http://java.sun.com/" />. Make sure that you
            download the JDK version (<emphasis>not</emphasis> the JRE
            version). <command>Java 6 is currently not
            supported</command>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Tomcat</term>
        <listitem>
          <para>
            Download and install tomcat 5.5.16 or later, available
            from <ulink
            url="http://jakarta.apache.org/tomcat/" />
            <important>
              You MUST make sure that Tomcat uses the SERVER mode of
              the Java run time engine
              (see <ulink
              url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
            </important>
            On Linux you do this by setting the environment variable:
            <code>CATALINA_OPTS</code> to <code>-server</code>. It is
            also a good idea to specify the maximum allowed memory to
            use: <code>-server -Xmx500m</code> sets it to 500
            megabytes. Basically add the next line close to the top of
            the <filename>catalina.sh</filename> script that comes
            with tomcat
            (directory <filename
            class="direcotry">bin</filename>): <programlisting>
CATALINA_OPTS="-server -Xmx500m"
</programlisting>
          </para>
          <para>
            For more information about Tomcat options see
            <ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Set up SQL database</term>
        <listitem>
          <para>
            BASE 2
            utilize <ulink
            url="http://www.hibernate.org/">Hibernate</ulink> for
            object persistence to a relational database. Hibernate
            supports many database engines, but so far we only work
            with <ulink url="http://www.mysql.com">MySQL</ulink>
            and <ulink
            url="http://www.postgresql.org/">PostgreSQL</ulink>.
          </para>

          <variablelist>
            <varlistentry>
              <term>MySQL</term>
              <listitem>
                <para>
                  Download and install MySQL (tested with version
                  5.0), available from
                  <ulink url="http://www.mysql.com/" />. You need to
                  be able to connect to the server over TCP, so
                  the <emphasis>skip-networking</emphasis> option
                  must <command>not</command> be used. The InnoDB
                  table engine is also needed, so don't disable them
                  (not that you would) but you may want to tune the
                  InnoDB behaviour before creating BASE
                  databases. BASE comes pre-configured for MySQL so
                  there is no need to change database settings in the
                  BASE configuration files.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>PostgreSQL</term>
              <listitem>
                <para>
                  PostgreSQL 8.0 seems to be working very well with
                  BASE and Hibernate. Download and install PostgreSQL,
                  available from
                  <ulink url="http://www.postgresql.org/" />. you must
                  edit
                  your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
                  file. Uncomment the settings for Postgres and
                  comment out the settings for MySQL.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (download and unpacking)</term>
        <listitem>
          <para>
            <ulink
            url="http://base.thep.lu.se/wiki/DownloadPage">Download
            BASE</ulink> and unpack the downloaded file,
            i.e. <command>tar zxpf base-...tar.gz</command>. If you
            prefer to have the bleeding edge version of BASE, perform
            a checkout of the source from the subversion repository
            (subversion checkout instructions at
            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
            trac site</ulink>).
          </para>
          <para>
            If you choose to download the binary package, skip to the
            next item. The rest of us, read on and compile BASE 2. If
            you downloaded a source distribution, unpack the
            downloaded file <command>tar zxpf
            base-...src.tar.gz</command>, or you may have performed a
            subversion checkout.  Change to the 'root' base2
            directory, and issue <command>ant
            package.bin</command>. This will create a binary package
            in the base2 'root' directory. Unpack this new package
            (outside of the source file hierarchy), and from now on
            the instructions are the same irrespective where you got
            the binary package.
          </para>
          <para>
            <emphasis>This section is intended for advanced users and
              programmers only. In cases when you want to change the
              BASE code and try out personalized features it may be
              advantageous to run the tweaked BASE server against the
              development tree. Instructions on how to accomplish this
              is available in the
              <ulink
              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
              BASE document</ulink>. When you return back after
              compiling in the subversion tree you can follow the
              instruction here (with obvious changes to
              paths).</emphasis>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (database engine)</term>
        <listitem>
          <para>
            Instructions for MySQL and PostgreSQL are available
            below. The database names (base2 and base2dynamic is used
            here), the <emphasis>db_user</emphasis>, and
            the <emphasis>db_password</emphasis> can be changed during
            the creation of the databases. It is recommended to change
            the <emphasis>db_password</emphasis>, the other changes
            can be made if desired. The database names,
            the <emphasis>db_user</emphasis>, and
            the <emphasis>db_password</emphasis> are needed in a later
            step below when configuring BASE.
          </para>
          <note>
            Note that the <emphasis>db_user</emphasis> name
            and <emphasis>db_password</emphasis> set here is used
            internally by BASE in communication with the database and
            is never used to log on to the BASE application.
          </note>
          <variablelist>
            <varlistentry>
              <term>MySQL</term>
              <listitem>
                <para>
                  Create a new database for BASE, and add a
                  <emphasis>db_user</emphasis> with at least
                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
                  <emphasis>INDEX</emphasis>,
                  and <emphasis>ALTER</emphasis> permission for the
                  new database. To do this, connect to your MySQL
                  server and issue the next lines:
                  <programlisting>
CREATE DATABASE base2;
CREATE DATABASE base2dynamic;
GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
GRANT ALL ON base2dynamic.* TO db_user@localhost;
</programlisting>
                </para>
                <para>
                  The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
                  file contains the above statements and can be used
                  by the <filename>mysql</filename> command-line tool
                  (remember to edit
                  the <emphasis>db_user</emphasis>,
                  <emphasis>db_password</emphasis>,
                  and the database names in the script file before
                  executing the command): <command>mysql -uroot -p
                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
                  header in the script file contains further
                  information about the script.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>PostgreSQL</term>
              <listitem>
                <para>
                  Create a new database for BASE, and add a
                  <emphasis>db_user</emphasis> with the proper
                  privileges. To do this, log in as your PostgreSQL
                  user and issue these lines (omit comments):
                  <programlisting>
createuser db_user -P
  # this will prompt for an password for the new user, and issue two
  # more question that should be answered with character 'n' for no.
createdb --owner db_user --encoding UNICODE base2
psql base2
  # this will start the psql command line tool. Issue the next line
  # within the tool and quit with a '\q'.
CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";
</programlisting>
                  The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
                  file contains the above statements and can be used
                  by the <filename>psql</filename> command-line tool:
                  <command>psql -f ./misc/sql/createdb.posgres.sql
                    template1</command> The header in the script file
                  contains further information about the script.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (file storage setup)</term>
        <listitem>
          <para>
            An area for file storage must be setup. Create an empty
            directory in a proper location in your file system, and
            set the owner to be the same as the one that the tomcat
            server will be running as. Remember this location for
            later use.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (configuration)</term>
        <listitem>
          <para>
            Basic BASE configuration is done in
            <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>:
            <itemizedlist>
              <listitem>
                Uncomment the database engine section that match your setup.
              </listitem>
              <listitem>
                Modify the <emphasis>db.url</emphasis>,
                <emphasis>db.dynamic.catalog</emphasis>,
                <emphasis>db.username</emphasis>,
                and <emphasis>db.password</emphasis> settings to match
                your choice above. (<emphasis>database host and
                database name (e.g. base2)</emphasis>,
                <emphasis>e.g. base2dynamic</emphasis>,
                <emphasis>db_user</emphasis>, and
                and <emphasis>db_password</emphasis>, respectively.)
              </listitem>
              <listitem>
                Modify the <emphasis>userfiles</emphasis> setting to
                match your choice above.
              </listitem>
            </itemizedlist>
          </para>
          <para>
            <emphasis>Optional but recommended.</emphasis> You may want
            to modify extended properties to fit your needs. Extended
            properties are defined in
            <filename>/path/to/base/www/WEB-INF/classes/extended-properties.xml</filename>.
            There is an administrator <ulink
            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
              discussing extended properties</ulink> available.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (database initialization)</term>
        <listitem>
          <para>
            Change directory to
            <filename class="directory">/path/to/base/bin</filename>
            and run <filename>initdb.sh</filename> as <programlisting>
./initdb.sh base_root_password password
</programlisting>
            <important>
            The <emphasis>base_root_password</emphasis> you use here
            is given to the BASE web application
            user <emphasis>root</emphasis>. There is no supported way
            to change the <emphasis>root</emphasis> account name.
            </important>
            If the initialisation script fail, it is most probably a
            problem related to the underlying database. Make sure that
            the database accepts network connection and make sure that
            <emphasis>db_user</emphasis> has proper credentials.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE and tomcat</term>
        <listitem>
          <para>
            Either move the <filename
            class="directory">/path/to/base/www</filename> directory
            to the tomcat <filename class="directory">webapps</filename>
            directory or create a symbolic link from the tomcat
            <filename class="directory">webapps</filename> directory to
            the <filename class="directory">/path/to/base/www</filename>
            directory <programlisting>
cd /path/to/tomcat/webapps
ln -s /path_to_base/www base2
</programlisting>
            Start/restart tomcat, and try http://hostname:8080/base2
            (change <emphasis>hostname</emphasis> to your hostname) in
            your favourite browser. BASE log-in page should appear
            after a few seconds.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE, apache, and apache/tomcat connector</term>
        <listitem>
          <para>
            <emphasis>This step is optional</emphasis>.
          </para>
          <para>
            If you want run the tomcat server through the apache web
            server, you need to install the apache version 2 web
            server, available
            from <ulink
            url="http://www.apache.org/">http://www.apache.org/</ulink>,
            and a apache-tomcat connector, available
            from <ulink
            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
            So, we got you there;-) To be honest, this step is not
            really well documented since we previously used SuSE 9.3
            on our demo/test server, and apache/tomcat/mod_jk comes
            pre-installed. The current server does not use the
            apache/tomcat connector. What you need to do is something
            like this
            <itemizedlist>
              <listitem>
                Get that tomcat server running in stand-alone
                mode.
              </listitem>
              <listitem>
                Get the apache 2 server running.
              </listitem>
              <listitem>
                Install mod_jk. Note, different version are used for
                apache 1.3 and 2. In SuSE 9.3 this step is done by
                installing <filename>mod_jk-ap20</filename>.
              </listitem>
              <listitem>
                Create a <filename>workers.properties</filename> file
                in the
                tomcat <filename class="directory">base</filename>
                directory (commonly copied from a template).
              </listitem>
              <listitem>
                Create a <filename>jk.conf</filename> file in the
                apache <filename class="directory">conf</filename>
                directory (commonly copied from a template), and make
                sure that <emphasis>jk</emphasis> is added to the
                modules to be loaded when apache starts.
              </listitem>
              <listitem>
                In <filename>jk.conf</filename> add the lines below
                and change paths appropriately. <programlisting>
# The following lines makes apache aware of the location of
# the /base2 context
Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
&lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
Options Indexes FollowSymLinks
allow from all
&lt;/Directory&gt;
# The following lines mounts all base2 jsp files to tomcat
JkMount /base2 ajp13
JkMount /base2/* ajp13
# The following lines prohibits users from directly accessing WEB-INF
&lt;Location "/base2/WEB-INF/"&gt;
AllowOverride None
deny from all
&lt;/Location&gt;
</programlisting>
              </listitem>
            </itemizedlist>
            You must restart the apache and the tomcat server after above steps.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Setup done!</term>
        <listitem>
          <para>
            Happy BASEing. Now you can log on to your BASE 2 server as
            user <emphasis>root</emphasis> (use
            the <emphasis>base_root_password</emphasis> from the
            database initialization step above). You should begin with
            creating a couple user accounts, for more information on
            how to create user accounts please refer to
            <xref linkend="user_administration"/>.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect1>      <!-- Installation instructions -->


  <sect1 id="installation_upgrade.migration">
    <title>Migration instructions</title>
    <para></para>
  </sect1>      <!-- Migration instructions -->

  <sect1 id="installation_upgrade.jobagents">
    <title>Installing job agents</title>
    <para>TODO</para>
  </sect1>

</chapter>