source: trunk/doc/src/docbook/admin/installation.xml @ 7548

<?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.xml 7548 2018-12-10 11:53:32Z nicklas $

  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
  Copyright (C) 2010, 2011, 2012 Nicklas Nordborg
  Copyright (C) 2013 Jari Häkkinen, Nicklas Nordborg

  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 3
  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 BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="installation">

  <title>Installation and upgrade instructions</title>

  <note>
    <para>
    These instructions apply only to the BASE release which this
    document is a part of. The instructions here assume
    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 8</ulink> is used
    on the server side. Other servlet engines may work but we only
    test with Tomcat.
    </para>
  </note>

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

    <important id="installation.upgrade.important">
      <title>Important information for upgrading to BASE 3.14</title>
      <para>
        This section list some important information that may or may not
        apply when upgrading from the <emphasis>previous</emphasis> BASE
        release to the current release (eg. 3.13 to 3.14). If you are 
        upgrading from a BASE installation that is older (3.0-3.12) 
        you should also read <xref linkend="appendix.update_warnings" />.
      </para>

      <bridgehead>The db.driver setting is no longer used</bridgehead>
      <para>
        The JDBC driver to use is now found automatically based on
        the <constant>db.url</constant> setting in the <filename>base.config</filename>
        file. The <constant>db.driver</constant> setting can be removed.
      </para>
      
      <bridgehead>The (very) old Authenticator API has been removed</bridgehead>
      <para>
        The <code>net.sf.basedb.core.authentication.Authenticator</code>
        interface and other related code that was deprecated in BASE 3.3
        has been removed. Systems that still use old authentication code 
        need to replace this with a newer version before updating.
      </para>
      
      <bridgehead>Changes to the authentication system</bridgehead>
      <para>
        The authentication system has been updated to make it easier to
        install more than one external authentication manager. The changes
        are backwards compatible and existing authentication managers should
        still work as before as long as they are the only ones installed.
        However, the existing authentication managers will probably not work
        well if more than one is installed since they lack some features that
        are neccessary in order to cooperate with other managers. Before installing
        more than one authentication manager it is recommended that they are
        updated to newer versions.
      </para>
      
      <para>
        Newer authentication managers typically no longer provide support for
        password authentication. If the intention is that some users still should be 
        able to login with username+password, it is recommended that the 
        <guilabel>Password login form</guilabel> is enabled. Go to
        <menuchoice>
          <guimenu>Administrate</guimenu>
          <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
          <guimenuitem>Overview</guimenuitem>
        </menuchoice> and locate the <guilabel>Login form customization</guilabel>
        extension point to find it.
      </para>
      
      <bridgehead>Java 11</bridgehead>
      <para>
        Java 8 is still the only officially supported version, but our intention
        is to switch to Java 11 (or later) some time in the near future (2019). 
        We have made some initial tests with Java 11 and believe that BASE should
        work. However, it requires an extra installation step:
      </para>
      <para>
        Copy the JAR-files located in <filename>&lt;base-dir&gt;/misc/java11/</filename>
        to the <filename>&lt;base-dir&gt;/www/WEB-INF/lib/</filename> directory. 
        If you are running a BASE server today it might be a good idea to
        be prepared by setting up a test environment that is running a clone of
        the main server under Java 11.
      </para>
      
      <bridgehead>Secondary storage</bridgehead>
      <para>
        The <guilabel>Secondary storage</guilabel> feature has been deprecated 
        and will be removed in a future release. The recommendation is to replace 
        this feature with an external files solution instead.
      </para>
      
    </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/tomcat8.0 stop</command>
          </para>
          
          <tip>
            <title>Notify logged in users!</title>
            <para>
              If there are users logged in to your BASE server, it may
              be nice of you to notify them a few minutes prior to shutting
              down the BASE server. See <xref linkend="installation.broadcast" />.
            </para>
          </tip>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Rename your current server</term>
        <listitem>
          <para>
            Rename your current BASE 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/wiki/BuildingBase" /> 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>&lt;base-dir&gt;/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>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
            may need to be transferred. This also includes all files in
            the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types</filename> and
            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties</filename>
            directories.
          </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="directory">&lt;base-dir&gt;/bin/</filename> and issue
<programlisting>
sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
</programlisting>
            where <emphasis>base_root_login</emphasis> is the login
            for the root user and <emphasis>base_root_password</emphasis> is the
            password. The login is optional. If not specified, 
            <constant>root</constant> is used as the login.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Start Tomcat</term>
        <listitem>
          <para>
            Start the Tomcat server: <command>sudo
              /etc/init.d/tomcat8.0 start</command>
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

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

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

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

    <variablelist>

      <varlistentry>
        <term>Java</term>
        <listitem>
          <para>
            Download and install Java SE 8, available from 
            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
            You can select either the JDK or the JRE version.
          </para>
          
          <note>
            <title>What about Java 11 (or later)?</title>
            <para>
            Java SE 8 is the officially supported version since BASE 3.6. 
            We have made some initial tests with Java 11 and we believe it to
            be working. The plan is to switch to Java 11 (or later)
            some time in the near future (2019). If you are setting up a new 
            BASE installation, you might as well try that with Java 11 
            already now. It requires an extra installation step:
            </para>
            <para>
            Copy the JAR-files located in <filename>&lt;base-dir&gt;/misc/java11/</filename>
            to the <filename>&lt;base-dir&gt;/www/WEB-INF/lib/</filename> directory. 
            </para>
          </note>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Set up an SQL database</term>
        <listitem>
          <para>
            BASE
            utilise <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.5), 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 do not 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 9.3 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>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
                  file. Uncomment the settings for PostgreSQL and
                  comment out the settings for MySQL.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>

        </listitem>
      </varlistentry>

      <varlistentry id="installation.main.database">
        <term>BASE (database engine)</term>
        <listitem>
          <para>
            The database names (base2 and base2dynamic are 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 are
            optional and can be made if desired. The database names,
            the <emphasis>db_user</emphasis>, and the
            <emphasis>db_password</emphasis> are needed 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>
          <important>
            <title>The database must use the UTF-8 character set</title>
            <para>
              Otherwise there will be a problem with storing values
              that uses characters outside the normal Latin1 range,
              for example unit-related such as µ (micro) and Ω (ohm).
            </para>
          </important>
          <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 DEFAULT CHARACTER SET utf8;
CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
                </para>             
                <para>
                  If you download BASE (instructions below) you find a file
                  <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
                  that 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;
                  &lt;base-dir&gt;/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 UTF8 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>

                  If you download BASE (instructions below) you find a file
                  <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
                  that contains the above statements and can be used
                  by the <filename>psql</filename> command-line tool:
                  <command>psql -f
                  &lt;base-dir&gt;/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 (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. 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 personalised 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/wiki/BuildingBase">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 (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. Set
            the owner of the created directory to the user the Tomcat
            server will be running as. Tomcat server set up
            instructions will follow below. Remember this location for
            later use. The default location is <filename>/usr/local/base2/files</filename>.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>BASE (plug-in setup)</term>
        <listitem>
          <para>
            An area for plug-in and extensions installation must be setup. 
            Create an empty directory in a proper location in your file system, 
            and make sure that the user that the Tomcat
            server will be running as has read permission in this
            directory. Tomcat server set up instructions will follow
            below. Remember this location for
            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry id="installation.main.configuration">
        <term>BASE (configuration)</term>
        <listitem>
          <para>
            Basic BASE configuration is done in
            <filename>&lt;base-dir&gt;/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
                <emphasis>db_password</emphasis>, respectively.)
              </listitem>
              <listitem>
                Modify the <emphasis>userfiles</emphasis> setting to
                match your choice in file storage setup above.
              </listitem>
              <listitem>
                Modify the <emphasis>plugins.dir</emphasis> setting to
                match your choice in plug-in setup above.
              </listitem>
            </itemizedlist>
            See the <xref linkend="appendix.base.config"/> for more
            information about the settings in
            the <filename>base.config</filename> file.
          </para>
          <para>
            <emphasis>Optional but recommended.</emphasis> You may want
            to modify extended properties to fit your needs. Extended
            properties are defined in
            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
            There is an
            administrator <ulink
            url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document
            discussing extended properties</ulink> available. If you
            plan to perform a migration of a BASE version 1.2 database you
            should probably not remove any extended properties
            columns (this is not tested so the outcome is currently
            undefined). However, adding columns does not affect
            migration.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE (database initialisation)</term>
        <listitem>
          <para>
            Change directory to
            <filename class="directory">&lt;base-dir&gt;/bin</filename>
            and execute the following commands: 
        <programlisting>
sudo ./initdb.sh [base_root_login] base_root_password
</programlisting>
          </para>

          <para>
            In the first command sudo is required because a file will
            be created in the directory defined by
            <emphasis>userfiles</emphasis> above. If the directory is
            writable by you then sudo is not needed.
          </para>

          <important>
            <para>
            The <emphasis>base_root_login</emphasis> and
            <emphasis>base_root_password</emphasis> you use here
            is given to the BASE web application root user account.
            The <emphasis>base_root_login</emphasis> is optional. If
            not specified, <constant>root</constant> is used for
            the login.
            </para>
          </important>

          <para>
            If the initialisation script fails, it is 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. You
            may also get a <emphasis>Permission denied</emphasis> on
            file <filename>extension-settings.xml</filename> if you do
            not have write permission to the directory defined by
            variable <emphasis>userfiles</emphasis> in file
            <filename>base.config</filename>. If the initialisation
            fails on <filename>extension-settings.xml</filename> you
            must drop the database and recreate the database as
            described in <xref linkend="installation.main.database"/>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Tomcat</term>
        <listitem>
          <para>
            Download and install Apache Tomcat 8 
            available from <ulink url="http://tomcat.apache.org" />.
          </para>

          <important>
            <para>
              As of BASE 3.6 we are only supporting Tomcat 8. 
              Tomcat 7 may work, but there is no guarantee.
            </para>
          </important>

          <para>
            There are a few configuration options that are needed to
            make Tomcat work properly with BASE. The options are set in the
            <code>CATALINA_OPTS</code> environment variable. 
          </para>
          
          <itemizedlist>
            <listitem>
              <para>
                Increase the amount of memory that Tomcat is allowed to use. The default setting is
                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
              </para>
            </listitem>
            <listitem>
              <para>
                Disable strict parsing of JSP files.
                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
              </para>
            </listitem>
            <listitem>
              <para>
                Unless you have manually downloaded and installed JAI (Java Advanced
                Imaging) native acceleration libraries (see <ulink 
                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
                it is a good idea to disable the native acceleration of JAI. 
                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
              </para>
            </listitem>
            <listitem>
              <para>
                Enable headless mode if your are setting up a server which doesn't have
                a display device connected to it. <code>-Djava.awt.headless=true</code>. 
              </para>
            </listitem>
          </itemizedlist>
          
          <para>
            Depending on your system there are probably several ways to set the
            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following 
            line (as a single line) close to the top of the <filename>catalina.sh</filename> 
            script that comes with Tomcat (directory <filename
            class="directory">bin</filename>): 
<programlisting>CATALINA_OPTS="-Xmx1G 
-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
-Dcom.sun.media.jai.disableMediaLib=true
-Djava.awt.headless=true"</programlisting>
          </para>
          <para>
            For more information about Tomcat options see
            <ulink url="http://tomcat.apache.org/tomcat-8.0-doc/index.html" />.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BASE and Tomcat</term>
        <listitem>
          <para>
            Do the following:
            <itemizedlist>
              <listitem>
                <para>
                  Either move the <filename
                  class="directory">&lt;base-dir&gt;/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">&lt;base-dir&gt;/www</filename>
                  directory
<programlisting>cd /path/to/tomcat/webapps
ln -s /path_to_base/www base2</programlisting>
                </para>
              </listitem>
              <listitem>
                <para>
                  Make sure that user Tomcat is running as can read
                  all objects in the directory defined by
                  <emphasis>plugins.dir</emphasis> in file
                  <filename>base.config</filename>.
                </para>
              </listitem>
              <listitem>
                <para>
                  Make sure that user Tomcat is running as owns (i.e.,
                  can read, write, delete and create) all objects in
                  the directory, as well as the directory itself,
                  defined by <emphasis>userfiles</emphasis> in file
                  <filename>base.config</filename>.
                </para>
              </listitem>
              <listitem>
                <para>
                  If you plan to install extensions you should make
                  sure that the <filename
                  class="directory">&lt;base-dir&gt;/www/extensions</filename>
                  directory is writable by the user account Tomcat is
                  running as.
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            and finalise with start, or restart, Tomcat, and try
            http://hostname:8080/base2 (change
            <emphasis>hostname</emphasis> to your hostname and
            <emphasis>base2</emphasis> if you selected another name
            for the BASE Tomcat application) in your favourite
            browser. The 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://httpd.apache.org/" />,
            and a apache-tomcat connector, available
            from <ulink
            url="http://tomcat.apache.org/connectors-doc/index.html" />
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Setup done!</term>
        <listitem>
          <para>
            Happy BASEing. Now you can log on to your BASE server as
            user <emphasis>root</emphasis> (use
            the <emphasis>base_root_password</emphasis> from the
            database initialisation 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="accounts"/>.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

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

  <sect1 id="installation.jobagents">
    <title>Installing job agents</title>

    <para>
      It is important to understand that the BASE application can be
      spread on to several computers. The main BASE application is
      serving HTTP requests, the underlying database engine is
      providing storage and persistence of data, and job agents can be
      installed on computers that will serve the BASE installation
      with computing power and perform analysis and run plug-ins. In a
      straight forward setup one computer provides all services needed
      for running BASE. From this starting point it is easy to add
      computers to shares load from the BASE server by installing job
      agents on these additional computers.
    </para>

    <para>
      A job agent is a program running on a computer regularly
      checking the BASE job queue for jobs awaiting execution. When
      the job agent finds a job that it is enabled to execute, it
      loads the plug-in and executes it. Job agents will in this way
      free up resources on the BASE application server, and thus allow
      the BASE server to concentrate on serving web pages. Job agents
      are optional and must be installed and setup
      separately. However, BASE is prepared for job agent setup and to
      utilise the agents, but the agent are not required.
    </para>

    <para>
      A job agent supports many configuration options that are not
      supported by the internal job queue. For example, you can
      <itemizedlist>
        <listitem>
          <para>
            Specify exactly which plug-ins each job agent should be
            able to execute.
          </para>
        </listitem>
        <listitem>
          <para>
            Give some plug-ins higher priority than other plug-ins.
          </para>
        </listitem>
        <listitem>
          <para>
            Specify which users/groups/projects should be able to use
            a specific job agent.
          </para>
        </listitem>
        <listitem>
          <para>
            Override memory settings and more for each plug-in.
          </para>
        </listitem>
        <listitem>
          <para>
            Execute plug-ins in separate processes. Thus, a misbehaving
            plug-in cannot bring the main application server down.
          </para>
        </listitem>
        <listitem>
          <para>
            Add more computers with job agents as needed.
          </para>
        </listitem>
      </itemizedlist>
      All these options make it possible to create a very flexible
      setup. For example one job agent can be assigned for importing
      data only, another job agent can be assigned for running
      analysis plug-ins for specific project only, and a third may be a
      catch-all job agent that performs all low-priority jobs.
    </para>

    <sect2 id="installation.jobagents.serverside">
      <title>BASE application server side setup</title>
      <para>
        <variablelist>
          <varlistentry>
            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
            <listitem>
              <para>
                The setting <command>jobqueue.internal.runallplugins</command>
                should be set to <command>false</command> for the
                BASE server. This setting is found in
                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
                file. The changes will not take effect until the
                application server is restarted.
              </para>

            </listitem>
          </varlistentry>
          <varlistentry id="installation.jobagent.user_account">
            <term>Enable the job agent user account</term>
            <listitem>
              <para>
                During installation of BASE a user account is created
                for the job agent. This account is used by the job
                agents to log on to BASE. The account is disabled by
                default and must be enabled. Enable the account and
                set a password using the BASE web interface. 
                The same password must also be set in the
                <filename>jobagent.properties</filename> file, see
                item
                <xref linkend="installation.jobagent.client.properties"/>
                below.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>

    <sect2 id="installation.jobagents.database">
      <title>Database server setup</title>
      <para>
        <variablelist>
          <varlistentry id="installation.jobagent.database">
            <term>Create a user account on the database</term>
            <listitem>
              <para>
                This is the similar to granting database access for
                the BASE server user in the in the regular BASE
                installation, cf.
                <xref
                linkend="installation.main.database"/>.
                You must create an account in the database that is
                allowed to connect from the job agent server. MySQL
                example:
<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>

                Replace <command>job.agent.host</command> with the
                host name of the server that is going to run the job
                agent. You should also set password. This password is
                used in item
                <xref linkend="installation.jobagent.client.config"/>
                below in job agent server setup. You can use the same
                database user and password as in the regular database
                setup.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>

    <sect2 id="installation.jobagents.client">
      <title>Job agent client setup</title>
      <para>
        <variablelist>
          <varlistentry>
            <term>Download and unpack a regular BASE distribution</term>
            <listitem>
              <para>
                You <emphasis>must</emphasis> use the same version on
                the web server and all job agents. You find the
                downloads at
                <ulink
                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="installation.jobagent.client.config">
            <term>Edit the <filename>base.config</filename> file</term>
            <listitem>
              <para>
                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
                file must be configured as in regular BASE
                installation, cf.
                <xref
                linkend="installation.main.configuration"/>,
                to use the same database as the web server
                application. The most important settings are
                <itemizedlist>
                  <listitem>
                    <para>
                      <command>db.username</command>: The database
                      user you created in item
                      <xref
                      linkend="installation.jobagent.database"/>
                      above.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>db.password</command>: The password for
                      the user.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>db.url</command>: The connection url to
                      the database.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>userfiles</command>: The path to the
                      directory where user files are located. This
                      directory must be accessible from all job
                      agents, i.e., by nfs or other file system
                      sharing method.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>plugins.dir</command>: The path to the
                      directory where plug-ins are located. This
                      directory must be accessible from all job
                      agents, i.e., by nfs or other file system
                      sharing method.
                    </para>
                  </listitem>
                </itemizedlist>
                See the <xref linkend="appendix.base.config"/> for
                more information about the settings in
                the <filename>base.config</filename> file.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry id="installation.jobagent.client.properties">
            <term>Edit
            the <filename>jobagent.properties</filename> file</term>
            <listitem>
              <para>
                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
                file contains settings for the job agent. The most
                important ones to specify value for are
                <itemizedlist>
                  <listitem>
                    <para>
                      <command>agent.password</command>: The password
                      you set for the job agent user account in item
                      <xref
                      linkend="installation.jobagent.user_account"/>
                      above.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>agent.id</command>: An ID that must be
                      unique for each job agent accessing the BASE application.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <command>agent.remotecontrol</command>: The
                      name or ip address of the web server if you want it
                      to be able to display info about running
                      jobs. The job agent will only allow connections
                      from computers specified in this setting.
                    </para>
                  </listitem>
                </itemizedlist>
              </para>
              <para>
                The <filename>jobagent.properties</filename> file
                contains many more configuration options. See
                the <xref linkend="appendix.jobagent.properties"/> for
                more information.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Register the job agent</term>
            <listitem>
              <para>
                From the <filename>bin</filename> directory, register
                the job agent with
                <programlisting>./jobagent.sh register</programlisting>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Start the job agent</term>
            <listitem>
              <para>
                From the <filename>bin</filename> directory, start the
                job agent with
                <programlisting>./jobagent.sh start &amp;</programlisting>
              </para>
              <para>
                See the <xref linkend="appendix.jobagent.sh"/>
                for more information about what you can do
                with the job agent command line interface.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>


    <sect2 id="installation.jobagents.configuration">
      <title>Configuring the job agent</title>
    
      <para>
        A job agent will not execute a plug-in unless the administrator
        has configured the job agent to do so. There are two things that
        must be done:
      </para>
      
      <itemizedlist>
        <listitem>
        <para>
          Share the job agent to the users, groups and project that should be
          able to use it. If the job agent is not shared, only the owner of
          job agent is allowed to use it. Use the regular <guilabel>Share</guilabel>
          functionality to specify which users/groups/projects
          should be able to use the job agent. You must give
          them at least <command>USE</command> permission.
          To give all users permission to the job agent share it
          to the <command>EVERYONE</command> group.
        </para>
        </listitem>
        
        <listitem>
        <para>
          Selecting plug-ins that the job agent should handle. This can be 
          done either from the plug-in pages or from the job agent pages. To register
          a plug-in with one or more job agents from the plug-in pages, go
          to the edit view of the plug-in and select the <guilabel>Job
          agents</guilabel> tab. To do the same from the job agent pages,
          go to the edit view of the job agent and select
          the <guilabel>Plugins</guilabel> tab. The registration dialogues
          are very similar but only the plug-in side of registration is
          described here. The major difference is that it is not possible
          to enable/disable the internal job queue for plug-in when using
          the jobagent side of the registration.
        </para>
        </listitem>
      </itemizedlist>
    
      <figure id="plugins.figures.jobagents">
        <title>Select job agents for a plug-in</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              scalefit="1" width="100%"
              fileref="figures/plugin_jobagents.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    
      <helptext external_id="plugindefinition.jobagents" 
        title="Job agents">
        
        <para>
          Use this tab to specify which job agents the plug-in is
          installed and allowed to be executed on.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Run this plugin on</guilabel></term>
          <listitem>
            <para>
              You may select if the internal job queue should execute the 
              plug-in or not. 
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Job agents</guilabel></term>
          <listitem>
            <para>
              A list with the job agents where the plug-in is installed and 
              allowed to be executed. Select a job agent in this list to display 
              more configuration options for the plug-in.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Add job agents</guilabel></term>
          <listitem>
            <para>
              Use this button to open a pop-up window for selecting
              job agents.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Remove</guilabel></term>
          <listitem>
            <para>
              Remove the selected plug-in from the list.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <para>
          The following properties are only displayed when a
          job agent has been selected in the list. Each job agent may have it's
          own settings of these properties. If you leave the values unspecified 
          the job agent will use the default values specified on the
          <guilabel>Plugin</guilabel> tab.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Max memory</guilabel></term>
          <listitem>
            <para>
              The maximum amount of memory the plug-in is allowed to use.
              Add around 40MB for the Java run-time environment and BASE. 
              If not specified Java will choose it's default value which is 64MB.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Trusted</guilabel></term>
          <listitem>
            <para>
              If the plug-in should be executed in a protected or 
              unprotected environment. Currently, BASE only supports
              running plug-ins in an unprotected environment.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Priority boost</guilabel></term>
          <listitem>
            <para>
              Used to give a plug-in higher priority in the job queue.
              Values between 0 and 10 are allowed. A higher value will 
              give the plug-in higher priority. The priority boost is useful 
              if we, for example, want to use one server mainly for importing 
              data. By giving all import plugins a priority boost they will 
              be executed before all other jobs, which will have to wait 
              until there are no more waiting imports.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <seeother>
          <other external_id="plugindefinition.edit">Plug-in properties</other>
          <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
        </seeother>
      </helptext>
    </sect2>

  </sect1>      <!-- job agent setup -->

  <sect1 id="installation.serverconfigurations">
    <title>Server configurations</title>
    <para>
      Some server configurations can be done when the installation process is finished and
      BASE is up and running. Log into BASE with administration rights and then
      open the configuration dialog from menu 
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Server settings</guimenuitem>
      </menuchoice>.
      Each tab in the configuration dialog-window is described below.
    </para>
    
      <figure id="installation.figures.serverconfiguration">
        <title>Server configuration</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              fileref="figures/server_configuration.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
    <variablelist>
      <varlistentry>
        <term>
          <guilabel>File transfer</guilabel>
        </term>
        <listitem>
          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
            <variablelist>
              <varlistentry>
                <term><guilabel>Max upload rate</guilabel></term>
                <listitem>
                  <para>
                    This is a limit of how many bytes of data that should be
                    transferred per second when uploading files to BASE. Prefixes
                    like k, M or G can be used for larger values, just like
                    described in the tab. The limit is per ongoing upload
                    and the default value is 100MB/s.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>Max download rate</guilabel></term>
                <listitem>
                  <para>
                    This is a limit of how many bytes of data that should be
                    transferred per second when downloading files from BASE. Prefixes
                    like k, M or G can be used for larger values. The limit is per ongoing
                    download and the default value is unlimited.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>Unlimited</guilabel></term>
                <listitem>
                  <para>
                    Check one or both to not limit the upload/download transfer rate.
                    In this case, the Internet connection of the server is the limit.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </helptext>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>About</guilabel>
        </term>
        <listitem>
          <helptext external_id="serverconfig.about"
            title="Information about the server">
            <variablelist>
              <varlistentry>
                <term><guilabel>Administrator name</guilabel></term>
                <listitem>
                  <para>
                    Name of the responsible administrator. The name is displayed
                    at the bottom of each page in BASE and in the about-dialog.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>Administrator email</guilabel></term>
                <listitem>
                  <para>
                    An email which the administrator can be contacted on. The
                    administrator name, visible at the bottom of each page, will
                    be linked to this email address.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>About</guilabel></term>
                <listitem>
                  <para>
                    Text written in this field is displayed in the
                    <guilabel>About this server</guilabel> section on the login
                    page and in the about-dialog window. We recommend changing the
                    default Latin text to something meaningful, or remove it
                    to hide the section completely.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </helptext>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Get account</guilabel>
        </term>
        <listitem>
          <helptext external_id="serverconfig.getaccount"
            title="Instructions to get an account">
            <para>
              A description what a user should do to get
              an account on the particular BASE server. This text is linked
              to the <guilabel>Get an account!</guilabel> link on the login
              page. We recommend that the Latin text is replaced with some useful
              information, or that it is removed to hide the link.
            </para>
          </helptext>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Forgotten password</guilabel>
        </term>
        <listitem>
          <helptext external_id="serverconfig.password"
            title="Instructions when password is forgotten.">
            <para>
              A description what a user should do if the password is forgotten.
              This text is linked
              to the <guilabel>Forgot your password?</guilabel> link on the login
              page. We recommend that the Latin text is replaced with some useful
              information, or that it is removed to hide the link.
            </para>
          </helptext>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Links</guilabel>
        </term>
        <listitem>
          <helptext external_id="serverconfig.links" title="Configurable links">
            <para>
              External configurable link-types inside BASE.
              <note>
                <para>
                  Only link-types that have been set will be visible in the web
                  client.
                </para>
              </note>
            </para>
            <variablelist>
              <varlistentry>
                <term><guilabel>Help</guilabel></term>
                <listitem>
                  <para>
                    Links to where the help text is located. By default
                    this is set to the documentation for the latest released
                    BASE version on the BASE web site,
                    <ulink
                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
                    
                    If you want the documentation for a specific version you will 
                    have to setup a site for that yourself and then change the link
                    to that site. The documentation is included in the downloaded package 
                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>FAQ</guilabel>
                </term>
                <listitem>
                  <para>Where frequently asked questions can be found. Empty by default.</para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Report a bug</guilabel>
                </term>
                <listitem>
                  <para>
                    Where the user could report bugs, feature request or
                    perhaps other feedback that concerns the program. As default
                    this is set to the feedback section on BASE web site,
                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
                    Note that users must login in order to submit information.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </helptext>
        </listitem>
      </varlistentry>
    </variablelist>
    
    <sect2 id="installation.broadcast">
      <title>Sending a broadcast message to logged in users</title>

      <para>
        It is possible to send a message to all logged in user.
        Open the 
        <menuchoice>
          <guimenu>Administrate</guimenu>
          <guimenuitem>Broadcast message</guimenuitem>
        </menuchoice> dialog box.
      </para>
      
      <figure id="installation.figures.broadcast">
        <title>Broadcast message</title>
        <screenshot>
          <mediaobject>
            <imageobject><imagedata 
              fileref="figures/broadcast_message.png" format="PNG"
              /></imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <helptext external_id="broadcast.message" title="Broadcast message">
        <para>
        This dialog allows you to specify a message that is sent to all
        logged in users as well as on the login form. It is also possible 
        to "disable" login.
        </para>
        <variablelist>
        <varlistentry>
          <term><guilabel>Title</guilabel></term>
          <listitem>
            <para>
            The title of the message. It should be a short and concise to
            avoid confusion. The title will be displayed on a lot of places
            and a user may have to click on it to read the more detailed
            message.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Disable login</guilabel></term>
          <listitem>
            <para>
            Mark this check-box to try to prevent new users from logging in. To
            avoid problems that can be caused by blocking the server admin out,
            the login is not completely disabled. Any user can still login but
            only after by-passing several warnings.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Message</guilabel></term>
          <listitem>
            <para>
            If needed, a longer message giving more information. Users may
            have to click on a link to be able to see the complete message.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <note>
          The message will be enabled until it is manually removed by saving
          an empty form, or until the Tomcat server is restarted. Since the
          message is only kept in memory, a restart will always remove it.
        </note>
      
      </helptext>
      
    </sect2>
    
  </sect1>

  <sect1 id="installation.migrate">
    <title>Migrating from MySQL to PostgreSQL</title>
    
    <para>
      It is possible to migrate a BASE installation on a MySQL database to a
      PostgreSQL database. In a real-world scenario a migration is probably coupled
      with a hardware upgrade, i.e. the MySQL installation is on one (the old) server
      and the PostgreSQL installation is on another (the new) server. While 
      this is not any problem per se, it requires a few extra steps to ensure that
      everything has been moved to the new server. There are three main steps involved:
    </para>
    
    <variablelist>
      <varlistentry>
        <term>Export</term>
        <listitem>
          <para>
          The first step is to export all data in the existing database. Use
          the following procedure:
          </para>
          
          <orderedlist>
            <listitem>
              <para>
              Upgrade to the latest BASE release. This is recommended since
              it probably has fewer bugs.
              </para>
            </listitem>

            <listitem>
              <para>
              Make sure that no other processes are writing to the database
              when the export is running. Shut down Tomcat and all job agents.
              It may also be a good idea to ensure that no backup scripts or 
              other external programs are reading from the database at the same
              time. If the database is large, this may affect performance due to
              increased disk I/O.
              </para>
            </listitem>
            
            <listitem>
              <para>
              Create a temporary working directory in a suitable
              location. This directory will be used for storing the
              exported data. Disk I/O performance may be better if 
              this directory is on a different disk than what the
              database is using. Ensure that the location has enough
              free space to hold all data from the BASE database. The dump
              typically uses less than 10% of the disk space used by the 
              MySQL tables.
              </para>
            </listitem>

            <listitem>
              <para>
              Make sure that you have configured migration-specific settings
              in the <filename>base.config</filename> file. In most cases the
              default settings should be good, but if you are experiencing
              performance problems it may be necessary to change some settings.
              See <xref linkend="appendix.base.config.migrate" /> for more 
              information.
              </para>
            </listitem>

            <listitem>            
              <para>
                Start the export by changing to the <filename
                class="directory">&lt;base-dir&gt;/bin/</filename>
                directory and execute:
              </para>
<programlisting>
./migrate.sh export <replaceable>/path/to/migration/dir</replaceable>
</programlisting>
              <para>
                where <replaceable>/path/to/migration/dir</replaceable>
                is replaced with the path to the working directory created above.
                Depending on the size of the BASE installation the export may 
                take a long time.
              </para>
            </listitem>
          </orderedlist>
          
          <note>
            <para>
              Make sure that the migration working directory is empty to perform
              a full export. Existing files in the directory causes the corresponding
              tables to be skipped. This can be useful when debugging and after a
              server crash, since the export will resume where it stopped. Just make
              sure that the database hasn't been modified in the meantime.
            </para>
          </note>
          <warning>
            <para>
            When exporting, make sure that no other process is updating the 
            database since that may create an inconsistent snapshot. The
            export process does not lock the database or take any other means
            to protect it against concurrent modifications.
            </para>
          </warning>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Moving data</term>
        <listitem>
          <para>
          This step is about moving the data from the old BASE server to the
          new BASE server. If the migration is taking place on a single server,
          this step can probably be skipped.
          </para>
          
          <orderedlist>
            <listitem>
              <para>
              Download and unpack the BASE software on the new server. Make sure that you are 
              using the same version as on the old server. It is also important that 
              the database is identically configured. Pay special attention
              to the <filename>extended-properties.xml</filename> and
              <filename>raw-data-types.xml</filename> files and any files
              in the <filename
              class="directory">&lt;base-dir&gt;/WEB-INF/classes/extended-properties</filename>
              and <filename
              class="directory">&lt;base-dir&gt;/WEB-INF/classes/raw-data-types</filename>
              directories. 
              The import program protects against some mistakes by comparing 
              the column names from the export with the column names in the new 
              database, but it will, for example, not check that data types match.
              </para>
              
              <tip>
                The easiest way to do this is to simply copy the BASE installation
                from the old server to the new server. Then, go through the 
                configuration files and make sure that paths are correct.
              </tip>
              
            </listitem>
          
            <listitem>
              <para>
              Move user files from the old server to the new server. Make sure that
              the <property>userfiles</property> setting in <filename>base.config</filename>
              is correct.
              </para>
            </listitem>
            
            <listitem>
              <para>
              Move plug-ins from the old server to the new server. Make sure that
              the <property>plugins.dir</property> setting in <filename>base.config</filename>
              is correct.
              </para>
            </listitem>

            <listitem>
              <para>
              Check other settings in <filename>base.config</filename> and
              other configuration files for settings that may be affected by
              the move.
              </para>
            </listitem>
          
          </orderedlist>
          
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Import</term>
        <listitem>
          <para>
            When everything has been moved and is properly configured it is
            time to start with the import.
          </para>
          
          <orderedlist>
            <listitem>
              <para>
              Create a new empty database following the
              instructions in <xref linkend="installation.main.database" />. 
              Make the corresponding changes in <filename>base.config</filename>
              so that the BASE installation points to the new database.
              Also, make sure that you have configured migration-specific settings
              in the <filename>base.config</filename> file. In most cases the
              default settings should be good, but if you are experiencing
              performance problems it may be necessary to change some settings.
              See <xref linkend="appendix.base.config.migrate" /> for more 
              information.
              </para>
            </listitem>
          
            <listitem>
              <para>
              Read the 
              <ulink url="http://www.postgresql.org/docs/9.1/interactive/populate.html">http://www.postgresql.org/docs/9.1/interactive/populate.html</ulink>
              document from the PostgreSQL documentation and consider implementing some
              of the tips. The migration script makes sure that no indexes or foreign 
              key constraints are active during the data import, but the tips about memory, 
              checkpoint intervals, WAL archiving, etc. (section 14.4.5 and on) can be useful. 
              It may also be a good idea to turn off the auto-vacuum daemon during the import.
              </para>
            </listitem>
            
            <listitem>
              <para>
                Start the import by changing to the <filename
                class="directory">&lt;base-dir&gt;/bin/</filename>
                directory and execute:
              </para>
<programlisting>
./migrate.sh import <replaceable>/path/to/migration/dir</replaceable>
</programlisting>
              <para>
                where <replaceable>/path/to/migration/dir</replaceable>
                is replaced with the path to the directory where
                the exported data is stored. Depending on
                the size of the BASE installation this may take a long time.
              </para>
              
              <note>
                <title>Installations with separate web and database servers</title>
                <para>
                Both export and import may be executed against remote MySQL/PostgreSQL
                servers without limitation. The migration working directory need only
                to be accessible by the BASE migration program.
                </para>
              </note>
              
            </listitem>
            
            <listitem>
              <para>
              Restart Tomcat and verify that the migration was successful. Eg.
              check that you can log in to BASE, that you can access files,
              that plug-ins are working, etc. Then, shut everything down again.
              </para>
            </listitem>

            <listitem>
              <para>
              Setup backup procedures for the new server. Verify that the 
              backup is working before starting up Tomcat again.          
              Restart any job agents (make sure that the are configured to use
              the new server). When everything is up and running again, the
              <replaceable>/path/to/migration/dir</replaceable> directory
              and all files can be deleted.
              </para>
            </listitem>
          </orderedlist>
        
        </listitem>
      </varlistentry>
    </variablelist>
    
  </sect1>

</chapter>