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

Last change on this file since 6763 was 6763, checked in by Nicklas Nordborg, 7 years ago

References #1924: Test BASE with Java 8

Updated documentation to recommend Java 8.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 60.6 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: installation.xml 6763 2015-03-09 08:13:04Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
10  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
11  Copyright (C) 2010, 2011, 2012 Nicklas Nordborg
12  Copyright (C) 2013 Jari Häkkinen, Nicklas Nordborg
13
14  This file is part of BASE - BioArray Software Environment.
15  Available at http://base.thep.lu.se/
16
17  BASE is free software; you can redistribute it and/or
18  modify it under the terms of the GNU General Public License
19  as published by the Free Software Foundation; either version 3
20  of the License, or (at your option) any later version.
21
22  BASE is distributed in the hope that it will be useful,
23  but WITHOUT ANY WARRANTY; without even the implied warranty of
24  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25  GNU General Public License for more details.
26
27  You should have received a copy of the GNU General Public License
28  along with BASE. If not, see <http://www.gnu.org/licenses/>.
29-->
30
31<chapter id="installation">
32
33  <title>Installation and upgrade instructions</title>
34
35  <note>
36    <para>
37    These instructions apply only to the BASE release which this
38    document is a part of. The instructions here assume
39    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used
40    on the server side. Other servlet engines may work but we only
41    test with Tomcat.
42    </para>
43  </note>
44
45  <sect1 id="installation.upgrade">
46    <title>Upgrade instructions</title>
47
48    <important id="installation.upgrade.important">
49      <title>Important information for upgrading to the current release</title>
50      <para>
51        This section list some important information that may or may not
52        apply when upgrading from the <emphasis>previous</emphasis> BASE
53        release to the current release (eg. 3.4 to 3.5). If you are
54        upgrading from a BASE installation that is older (3.0-3.3)
55        you should also read <xref linkend="appendix.update_warnings" />.
56      </para>
57     
58      <bridgehead>Consider updating to Java 8</bridgehead>
59      <para>
60        Oracle is no longer supporting Java 1.7. We are recommending Java 8
61        for running BASE. Java 7 is still supported, but will be removed
62        in the next version (BASE 3.6).
63      </para>
64     
65    </important>
66   
67    <para>
68      As always, backup your database before attempting an
69      upgrade. The BASE team performs extensive testing before
70      releasing a new version of BASE but there are always a
71      possibility for unexpected events during upgrades. In upgrades
72      requiring a change in the underlying database there is no
73      (supported) way to revert to a previous version of BASE using
74      BASE tools, you need to use your backup for this use case.
75    </para>
76
77    <para>
78      The strategy here is to install the new BASE release to another
79      directory than the one in use. This requires transfer of
80      configuration settings to the new install but more on that
81      below.
82    </para>
83
84    <variablelist>
85      <varlistentry>
86        <term>Shut down the Tomcat server</term>
87        <listitem>
88          <para>
89            If the BASE application is not shut down already, it is
90            time to do it now. Do something like <command>sudo
91            /etc/init.d/tomcat7.0 stop</command>
92          </para>
93         
94          <tip>
95            <title>Notify logged in users!</title>
96            <para>
97              If there are users logged in to your BASE server, it may
98              be nice of you to notify them a few minutes prior to shutting
99              down the BASE server. See <xref linkend="installation.broadcast" />.
100            </para>
101          </tip>
102        </listitem>
103      </varlistentry>
104
105      <varlistentry>
106        <term>Rename your current server</term>
107        <listitem>
108          <para>
109            Rename your current BASE installation <command>mv
110              /path/to/base /path/to/base_old</command>.
111          </para>
112        </listitem>
113      </varlistentry>
114
115      <varlistentry>
116        <term>Download and unpack BASE</term>
117        <listitem>
118          <para>
119            There are several ways to download BASE. Please refer to
120            section <xref linkend="resources.home_page.download"/> for
121            information on downloading BASE, and select the item
122            matching your download option:
123          </para>
124
125          <variablelist>
126            <varlistentry>
127              <term><emphasis>Pre-compiled package</emphasis></term>
128              <listitem>
129                <para>
130                  If you selected to download a pre-compiled package,
131                  unpack the downloaded file with <command>tar zxpf
132                  base-...tar.gz</command>.
133                </para>
134              </listitem>
135            </varlistentry>
136
137            <varlistentry>
138              <term><emphasis>Source package</emphasis></term>
139              <listitem>
140                <para>
141                  If you selected to download a source package, unpack
142                  the downloaded file with <command>tar zxpf
143                  base-...src.tar.gz</command>. Change to the new
144                  directory, and issue <command>ant
145                  package.bin</command>. This will create a binary
146                  package in the current directory. Unpack this new
147                  package (outside of the source file hierarchy).
148                </para>
149              </listitem>
150            </varlistentry>
151
152            <varlistentry>
153              <term><emphasis>Subversion checkout</emphasis></term>
154              <listitem>
155                <para>
156                  This option is for advanced users only and is not
157                  covered here. Please refer to
158                  <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on
159                  this download option.
160                </para>
161              </listitem>
162            </varlistentry>
163
164          </variablelist>
165        </listitem>
166
167      </varlistentry>
168
169      <varlistentry>
170        <term>Transfer files and settings</term>
171        <listitem>
172          <para>
173            Settings from the previous installation must be
174            transferred to the new installation. This is most easily
175            done by comparing the configuration files from the
176            previous install with the new files. Do not just copy the
177            old files to the new install since new options may have
178            appeared.
179          </para>
180          <para>
181            In the main BASE configuration file,
182            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>,
183            fields that needs to be transferred are usually
184            <emphasis>db.username</emphasis>,
185            <emphasis>db.password</emphasis>,
186            and <emphasis>userfiles</emphasis>.
187          </para>
188          <para>
189            Local settings in the raw data
190            tables, <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
191            may need to be transferred. This also includes all files in
192            the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types</filename> and
193            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties</filename>
194            directories.
195          </para>
196        </listitem>
197      </varlistentry>
198
199      <varlistentry>
200        <term>Updating database schema</term>
201        <listitem>
202          <para>
203            It is recommended that you also perform an update of your
204            database schema.  Running the update scripts are not
205            always necessary when upgrading BASE, but the running the
206            update scripts are safe even in cases when there is no
207            need to run them. Change directory
208            to <filename
209            class="directory">&lt;base-dir&gt;/bin/</filename> and issue
210<programlisting>
211sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
212sh ./updateindexes.sh
213</programlisting>
214            where <emphasis>base_root_login</emphasis> is the login
215            for the root user and <emphasis>base_root_password</emphasis> is the
216            password. The login is optional. If not specified,
217            <constant>root</constant> is used as the login.
218          </para>
219        </listitem>
220      </varlistentry>
221
222      <varlistentry>
223        <term>Start Tomcat</term>
224        <listitem>
225          <para>
226            Start the Tomcat server: <command>sudo
227              /etc/init.d/tomcat7.0 start</command>
228          </para>
229        </listitem>
230      </varlistentry>
231
232    </variablelist>
233
234    <para>
235      Done! Upgrade of BASE is finished.
236    </para>
237
238  </sect1>      <!-- Upgrade instructions -->
239
240  <sect1 id="installation.main">
241    <title>Installation instructions</title>
242
243    <variablelist>
244
245      <varlistentry>
246        <term>Java</term>
247        <listitem>
248          <para>
249            Download and install Java SE 8, available from
250            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
251            You can select either the JDK or the JRE version.
252          </para>
253         
254          <note>
255            <para>
256            As of BASE 3.5 Java SE 8 is recommended. Support for Java SE 7
257            will be dropped in BASE 3.6. Java SE 6 or lower is not supported.
258            </para>
259          </note>
260
261        </listitem>
262      </varlistentry>
263
264      <varlistentry>
265        <term>Set up an SQL database</term>
266        <listitem>
267          <para>
268            BASE
269            utilise <ulink
270            url="http://www.hibernate.org/">Hibernate</ulink> for
271            object persistence to a relational database. Hibernate
272            supports many database engines, but so far we only work
273            with <ulink url="http://www.mysql.com">MySQL</ulink>
274            and <ulink
275            url="http://www.postgresql.org/">PostgreSQL</ulink>.
276          </para>
277
278          <variablelist>
279            <varlistentry>
280              <term>MySQL</term>
281              <listitem>
282                <para>
283                  Download and install MySQL (tested with version
284                  5.5), available from
285                  <ulink url="http://www.mysql.com/" />. You need to
286                  be able to connect to the server over TCP, so
287                  the <emphasis>skip-networking</emphasis> option
288                  must <command>not</command> be used. The InnoDB
289                  table engine is also needed, so do not disable them
290                  (not that you would) but you may want to tune the
291                  InnoDB behaviour before creating BASE
292                  databases. BASE comes pre-configured for MySQL so
293                  there is no need to change database settings in the
294                  BASE configuration files.
295                </para>
296              </listitem>
297            </varlistentry>
298            <varlistentry>
299              <term>PostgreSQL</term>
300              <listitem>
301                <para>
302                  PostgreSQL 9.3 seems to be working very well with
303                  BASE and Hibernate. Download and install PostgreSQL,
304                  available from
305                  <ulink url="http://www.postgresql.org/" />. You must edit
306                  your <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
307                  file. Uncomment the settings for PostgreSQL and
308                  comment out the settings for MySQL.
309                </para>
310              </listitem>
311            </varlistentry>
312          </variablelist>
313
314        </listitem>
315      </varlistentry>
316
317      <varlistentry id="installation.main.database">
318        <term>BASE (database engine)</term>
319        <listitem>
320          <para>
321            The database names (base2 and base2dynamic are used here),
322            the <emphasis>db_user</emphasis>, and the
323            <emphasis>db_password</emphasis> can be changed during the
324            creation of the databases. It is recommended to change the
325            <emphasis>db_password</emphasis>, the other changes are
326            optional and can be made if desired. The database names,
327            the <emphasis>db_user</emphasis>, and the
328            <emphasis>db_password</emphasis> are needed below when
329            configuring BASE.
330          </para>
331          <note>
332            Note that the <emphasis>db_user</emphasis> name and
333            <emphasis>db_password</emphasis> set here is used
334            internally by BASE in communication with the database and
335            is never used to log on to the BASE application.
336          </note>
337          <important>
338            <title>The database must use the UTF-8 character set</title>
339            <para>
340              Otherwise there will be a problem with storing values
341              that uses characters outside the normal Latin1 range,
342              for example unit-related such as µ (micro) and Ω (ohm).
343            </para>
344          </important>
345          <variablelist>
346            <varlistentry>
347              <term>MySQL</term>
348              <listitem>
349                <para>
350                  Create a new database for BASE, and add a
351                  <emphasis>db_user</emphasis> with at least
352                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
353                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
354                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
355                  <emphasis>INDEX</emphasis>,
356                  and <emphasis>ALTER</emphasis> permission for the
357                  new database. To do this, connect to your MySQL
358                  server and issue the next lines:
359<programlisting>CREATE DATABASE base2 DEFAULT CHARACTER SET utf8;
360CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
361GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
362GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
363                </para>             
364                <para>
365                  If you download BASE (instructions below) you find a file
366                  <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
367                  that contains the above statements and can be used
368                  by the <filename>mysql</filename> command-line tool
369                  (remember to edit the <emphasis>db_user</emphasis>,
370                  <emphasis>db_password</emphasis>, and the database
371                  names in the script file before executing the
372                  command): <command>mysql -uroot -p &lt;
373                  &lt;base-dir&gt;/misc/sql/createdb.mysql.sql</command>. The
374                  header in the script file contains further
375                  information about the script.
376                </para>
377              </listitem>
378            </varlistentry>
379            <varlistentry>
380              <term>PostgreSQL</term>
381              <listitem>
382                <para>
383                  Create a new database for BASE, and add a
384                  <emphasis>db_user</emphasis> with the proper
385                  privileges. To do this, log in as your PostgreSQL
386                  user and issue these lines (omit comments):
387<programlisting>createuser db_user -P
388  # this will prompt for an password for the new user, and issue two
389  # more question that should be answered with character 'n' for no.
390createdb --owner db_user --encoding UTF8 base2
391psql base2
392  # this will start the psql command line tool. Issue the next line
393  # within the tool and quit with a '\q'.
394CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
395
396                  If you download BASE (instructions below) you find a file
397                  <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
398                  that contains the above statements and can be used
399                  by the <filename>psql</filename> command-line tool:
400                  <command>psql -f
401                  &lt;base-dir&gt;/misc/sql/createdb.posgres.sql
402                  template1</command> The header in the script file
403                  contains further information about the script.
404                </para>
405              </listitem>
406            </varlistentry>
407          </variablelist>
408        </listitem>
409      </varlistentry>
410
411      <varlistentry>
412        <term>BASE (download and unpacking)</term>
413        <listitem>
414          <para>
415            <ulink
416            url="http://base.thep.lu.se/wiki/DownloadPage">Download
417            BASE</ulink> and unpack the downloaded file,
418            i.e. <command>tar zxpf base-...tar.gz</command>. If you
419            prefer to have the bleeding edge version of BASE, perform
420            a checkout of the source from the subversion repository
421            (subversion checkout instructions at
422            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
423            trac site</ulink>).
424          </para>
425          <para>
426            If you choose to download the binary package, skip to the
427            next item. The rest of us, read on and compile BASE. If
428            you downloaded a source distribution, unpack the
429            downloaded file <command>tar zxpf
430            base-...src.tar.gz</command>, or you may have performed a
431            subversion checkout.  Change to the 'root' base2
432            directory, and issue <command>ant
433            package.bin</command>. This will create a binary package
434            in the base2 'root' directory. Unpack this new package
435            (outside of the source file hierarchy), and from now on
436            the instructions are the same irrespective where you got
437            the binary package.
438          </para>
439          <para>
440            <emphasis>This section is intended for advanced users and
441              programmers only. In cases when you want to change the
442              BASE code and try out personalised features it may be
443              advantageous to run the tweaked BASE server against the
444              development tree. Instructions on how to accomplish this
445              is available in the
446              <ulink
447              url="http://base.thep.lu.se/wiki/BuildingBase">building
448              BASE document</ulink>. When you return back after
449              compiling in the subversion tree you can follow the
450              instruction here (with obvious changes to
451              paths).</emphasis>
452          </para>
453        </listitem>
454      </varlistentry>
455
456      <varlistentry>
457        <term>BASE (file storage setup)</term>
458        <listitem>
459          <para>
460            An area for file storage must be setup. Create an empty
461            directory in a proper location in your file system. Set
462            the owner of the created directory to the user the Tomcat
463            server will be running as. Tomcat server set up
464            instructions will follow below. Remember this location for
465            later use. The default location is <filename>/usr/local/base2/files</filename>.
466          </para>
467        </listitem>
468      </varlistentry>
469     
470      <varlistentry>
471        <term>BASE (plug-in setup)</term>
472        <listitem>
473          <para>
474            An area for plug-in and extensions installation must be setup.
475            Create an empty directory in a proper location in your file system,
476            and make sure that the user that the Tomcat
477            server will be running as has read permission in this
478            directory. Tomcat server set up instructions will follow
479            below. Remember this location for
480            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
481          </para>
482        </listitem>
483      </varlistentry>
484
485      <varlistentry id="installation.main.configuration">
486        <term>BASE (configuration)</term>
487        <listitem>
488          <para>
489            Basic BASE configuration is done in
490            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>:
491            <itemizedlist>
492              <listitem>
493                Uncomment the database engine section that match your setup.
494              </listitem>
495              <listitem>
496                Modify the <emphasis>db.url</emphasis>,
497                <emphasis>db.dynamic.catalog</emphasis>,
498                <emphasis>db.username</emphasis>,
499                and <emphasis>db.password</emphasis> settings to match
500                your choice above. (<emphasis>database host and
501                database name (e.g. base2)</emphasis>,
502                <emphasis>e.g. base2dynamic</emphasis>,
503                <emphasis>db_user</emphasis>, and
504                <emphasis>db_password</emphasis>, respectively.)
505              </listitem>
506              <listitem>
507                Modify the <emphasis>userfiles</emphasis> setting to
508                match your choice in file storage setup above.
509              </listitem>
510              <listitem>
511                Modify the <emphasis>plugins.dir</emphasis> setting to
512                match your choice in plug-in setup above.
513              </listitem>
514            </itemizedlist>
515            See the <xref linkend="appendix.base.config"/> for more
516            information about the settings in
517            the <filename>base.config</filename> file.
518          </para>
519          <para>
520            <emphasis>Optional but recommended.</emphasis> You may want
521            to modify extended properties to fit your needs. Extended
522            properties are defined in
523            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
524            There is an
525            administrator <ulink
526            url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document
527            discussing extended properties</ulink> available. If you
528            plan to perform a migration of a BASE version 1.2 database you
529            should probably not remove any extended properties
530            columns (this is not tested so the outcome is currently
531            undefined). However, adding columns does not affect
532            migration.
533          </para>
534        </listitem>
535      </varlistentry>
536
537      <varlistentry>
538        <term>BASE (database initialisation)</term>
539        <listitem>
540          <para>
541            Change directory to
542            <filename class="directory">&lt;base-dir&gt;/bin</filename>
543            and execute the following commands:
544        <programlisting>
545sudo ./initdb.sh [base_root_login] base_root_password
546./updateindexes.sh
547</programlisting>
548          </para>
549
550          <para>
551            In the first command sudo is required because a file will
552            be created in the directory defined by
553            <emphasis>userfiles</emphasis> above. If the directory is
554            writable by you then sudo is not needed.
555          </para>
556
557          <para>
558            The second command is important since
559            the Hibernate database initialisation utility is not always
560            able to create all required indexes. In some cases, Hibernate
561            will also create a new index, even if one already exists.
562            The command ensures that missing indexes are created and
563            that duplicates are removed. BASE will work without the
564            indexes but performance is impaired.
565          </para>
566
567            <important>
568            <para>
569            The <emphasis>base_root_login</emphasis> and
570            <emphasis>base_root_password</emphasis> you use here
571            is given to the BASE web application root user account.
572            The <emphasis>base_root_login</emphasis> is optional. If
573            not specified, <constant>root</constant> is used for
574            the login.
575            </para>
576            </important>
577
578          <para>
579            If the initialisation script fails, it is probably a
580            problem related to the underlying database. Make sure that
581            the database accepts network connection and make sure that
582            <emphasis>db_user</emphasis> has proper credentials. You
583            may also get a <emphasis>Permission denied</emphasis> on
584            file <filename>extension-settings.xml</filename> if you do
585            not have write permission to the directory defined by
586            variable <emphasis>userfiles</emphasis> in file
587            <filename>base.config</filename>. If the initialisation
588            fails on <filename>extension-settings.xml</filename> you
589            must drop the database and recreate the database as
590            described in <xref linkend="installation.main.database"/>.
591          </para>
592        </listitem>
593      </varlistentry>
594
595      <varlistentry>
596        <term>Tomcat</term>
597        <listitem>
598          <para>
599            Download and install Apache Tomcat 7.0.30 or any later 7.x
600            release, available from <ulink url="http://tomcat.apache.org" />.
601          </para>
602
603          <important>
604            <para>
605              As of BASE 3.3 Tomcat 7 is required. BASE will no longer
606              run on Tomcat 6 or lower.
607            </para>
608          </important>
609
610          <para>
611            There are a few configuration options that are needed to
612            make Tomcat work properly with BASE. The options are set in the
613            <code>CATALINA_OPTS</code> environment variable.
614          </para>
615         
616          <itemizedlist>
617            <listitem>
618              <para>
619                Increase the amount of memory that Tomcat is allowed to use. The default setting is
620                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
621              </para>
622            </listitem>
623            <listitem>
624              <para>
625                Disable strict parsing of JSP files.
626                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
627              </para>
628            </listitem>
629            <listitem>
630              <para>
631                Unless you have manually downloaded and installed JAI (Java Advanced
632                Imaging) native acceleration libraries (see <ulink 
633                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
634                it is a good idea to disable the native acceleration of JAI.
635                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
636              </para>
637            </listitem>
638            <listitem>
639              <para>
640                Enable headless mode if your are setting up a server which doesn't have
641                a display device connected to it. <code>-Djava.awt.headless=true</code>.
642              </para>
643            </listitem>
644          </itemizedlist>
645         
646          <para>
647            Depending on your system there are probably several ways to set the
648            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
649            line (as a single line) close to the top of the <filename>catalina.sh</filename> 
650            script that comes with Tomcat (directory <filename
651            class="directory">bin</filename>):
652<programlisting>CATALINA_OPTS="-Xmx1G
653-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
654-Dcom.sun.media.jai.disableMediaLib=true
655-Djava.awt.headless=true"</programlisting>
656          </para>
657          <para>
658            For more information about Tomcat options see
659            <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />.
660          </para>
661        </listitem>
662      </varlistentry>
663
664      <varlistentry>
665        <term>BASE and Tomcat</term>
666        <listitem>
667          <para>
668            Do the following:
669            <itemizedlist>
670              <listitem>
671                <para>
672                  Either move the <filename
673                  class="directory">&lt;base-dir&gt;/www</filename>
674                  directory to the Tomcat <filename
675                  class="directory">webapps</filename> directory or
676                  create a symbolic link from the Tomcat <filename
677                  class="directory">webapps</filename> directory to
678                  the <filename
679                  class="directory">&lt;base-dir&gt;/www</filename>
680                  directory
681<programlisting>cd /path/to/tomcat/webapps
682ln -s /path_to_base/www base2</programlisting>
683                </para>
684              </listitem>
685              <listitem>
686                <para>
687                  Make sure that user Tomcat is running as can read
688                  all objects in the directory defined by
689                  <emphasis>plugins.dir</emphasis> in file
690                  <filename>base.config</filename>.
691                </para>
692              </listitem>
693              <listitem>
694                <para>
695                  Make sure that user Tomcat is running as owns (i.e.,
696                  can read, write, delete and create) all objects in
697                  the directory, as well as the directory itself,
698                  defined by <emphasis>userfiles</emphasis> in file
699                  <filename>base.config</filename>.
700                </para>
701              </listitem>
702              <listitem>
703                <para>
704                  If you plan to install extensions you should make
705                  sure that the <filename
706                  class="directory">&lt;base-dir&gt;/www/extensions</filename>
707                  directory is writable by the user account Tomcat is
708                  running as.
709                </para>
710              </listitem>
711            </itemizedlist>
712          </para>
713          <para>
714            and finalise with start, or restart, Tomcat, and try
715            http://hostname:8080/base2 (change
716            <emphasis>hostname</emphasis> to your hostname and
717            <emphasis>base2</emphasis> if you selected another name
718            for the BASE Tomcat application) in your favourite
719            browser. The BASE log-in page should appear after a few
720            seconds.
721          </para>
722        </listitem>
723      </varlistentry>
724
725      <varlistentry>
726        <term>BASE, Apache, and Apache/Tomcat connector</term>
727        <listitem>
728          <para>
729            <emphasis>This step is optional</emphasis>.
730          </para>
731          <para>
732            If you want run the Tomcat server through the Apache web
733            server, you need to install the Apache version 2 web
734            server, available
735            from <ulink url="http://httpd.apache.org/" />,
736            and a apache-tomcat connector, available
737            from <ulink
738            url="http://tomcat.apache.org/connectors-doc/index.html" />
739          </para>
740        </listitem>
741      </varlistentry>
742
743      <varlistentry>
744        <term>Setup done!</term>
745        <listitem>
746          <para>
747            Happy BASEing. Now you can log on to your BASE server as
748            user <emphasis>root</emphasis> (use
749            the <emphasis>base_root_password</emphasis> from the
750            database initialisation step above). You should begin with
751            creating a couple user accounts, for more information on
752            how to create user accounts please refer to
753            <xref linkend="accounts"/>.
754          </para>
755        </listitem>
756      </varlistentry>
757
758    </variablelist>
759
760  </sect1>      <!-- Installation instructions -->
761
762  <sect1 id="installation.jobagents">
763    <title>Installing job agents</title>
764
765    <para>
766      It is important to understand that the BASE application can be
767      spread on to several computers. The main BASE application is
768      serving HTTP requests, the underlying database engine is
769      providing storage and persistence of data, and job agents can be
770      installed on computers that will serve the BASE installation
771      with computing power and perform analysis and run plug-ins. In a
772      straight forward setup one computer provides all services needed
773      for running BASE. From this starting point it is easy to add
774      computers to shares load from the BASE server by installing job
775      agents on these additional computers.
776    </para>
777
778    <para>
779      A job agent is a program running on a computer regularly
780      checking the BASE job queue for jobs awaiting execution. When
781      the job agent finds a job that it is enabled to execute, it
782      loads the plug-in and executes it. Job agents will in this way
783      free up resources on the BASE application server, and thus allow
784      the BASE server to concentrate on serving web pages. Job agents
785      are optional and must be installed and setup
786      separately. However, BASE is prepared for job agent setup and to
787      utilise the agents, but the agent are not required.
788    </para>
789
790    <para>
791      A job agent supports many configuration options that are not
792      supported by the internal job queue. For example, you can
793      <itemizedlist>
794        <listitem>
795          <para>
796            Specify exactly which plug-ins each job agent should be
797            able to execute.
798          </para>
799        </listitem>
800        <listitem>
801          <para>
802            Give some plug-ins higher priority than other plug-ins.
803          </para>
804        </listitem>
805        <listitem>
806          <para>
807            Specify which users/groups/projects should be able to use
808            a specific job agent.
809          </para>
810        </listitem>
811        <listitem>
812          <para>
813            Override memory settings and more for each plug-in.
814          </para>
815        </listitem>
816        <listitem>
817          <para>
818            Execute plug-ins in separate processes. Thus, a misbehaving
819            plug-in cannot bring the main application server down.
820          </para>
821        </listitem>
822        <listitem>
823          <para>
824            Add more computers with job agents as needed.
825          </para>
826        </listitem>
827      </itemizedlist>
828      All these options make it possible to create a very flexible
829      setup. For example one job agent can be assigned for importing
830      data only, another job agent can be assigned for running
831      analysis plug-ins for specific project only, and a third may be a
832      catch-all job agent that performs all low-priority jobs.
833    </para>
834
835    <sect2 id="installation.jobagents.serverside">
836      <title>BASE application server side setup</title>
837      <para>
838        <variablelist>
839          <varlistentry>
840            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
841            <listitem>
842              <para>
843                The setting <command>jobqueue.internal.runallplugins</command>
844                should be set to <command>false</command> for the
845                BASE server. This setting is found in
846                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
847                file. The changes will not take effect until the
848                application server is restarted.
849              </para>
850
851            </listitem>
852          </varlistentry>
853          <varlistentry id="installation.jobagent.user_account">
854            <term>Enable the job agent user account</term>
855            <listitem>
856              <para>
857                During installation of BASE a user account is created
858                for the job agent. This account is used by the job
859                agents to log on to BASE. The account is disabled by
860                default and must be enabled. Enable the account and
861                set a password using the BASE web interface.
862                The same password must also be set in the
863                <filename>jobagent.properties</filename> file, see
864                item
865                <xref linkend="installation.jobagent.client.properties"/>
866                below.
867              </para>
868            </listitem>
869          </varlistentry>
870        </variablelist>
871      </para>
872    </sect2>
873
874    <sect2 id="installation.jobagents.database">
875      <title>Database server setup</title>
876      <para>
877        <variablelist>
878          <varlistentry id="installation.jobagent.database">
879            <term>Create a user account on the database</term>
880            <listitem>
881              <para>
882                This is the similar to granting database access for
883                the BASE server user in the in the regular BASE
884                installation, cf.
885                <xref
886                linkend="installation.main.database"/>.
887                You must create an account in the database that is
888                allowed to connect from the job agent server. MySQL
889                example:
890<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
891GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
892
893                Replace <command>job.agent.host</command> with the
894                host name of the server that is going to run the job
895                agent. You should also set password. This password is
896                used in item
897                <xref linkend="installation.jobagent.client.config"/>
898                below in job agent server setup. You can use the same
899                database user and password as in the regular database
900                setup.
901              </para>
902            </listitem>
903          </varlistentry>
904        </variablelist>
905      </para>
906    </sect2>
907
908    <sect2 id="installation.jobagents.client">
909      <title>Job agent client setup</title>
910      <para>
911        <variablelist>
912          <varlistentry>
913            <term>Download and unpack a regular BASE distribution</term>
914            <listitem>
915              <para>
916                You <emphasis>must</emphasis> use the same version on
917                the web server and all job agents. You find the
918                downloads at
919                <ulink
920                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
921              </para>
922            </listitem>
923          </varlistentry>
924          <varlistentry id="installation.jobagent.client.config">
925            <term>Edit the <filename>base.config</filename> file</term>
926            <listitem>
927              <para>
928                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
929                file must be configured as in regular BASE
930                installation, cf.
931                <xref
932                linkend="installation.main.configuration"/>,
933                to use the same database as the web server
934                application. The most important settings are
935                <itemizedlist>
936                  <listitem>
937                    <para>
938                      <command>db.username</command>: The database
939                      user you created in item
940                      <xref
941                      linkend="installation.jobagent.database"/>
942                      above.
943                    </para>
944                  </listitem>
945                  <listitem>
946                    <para>
947                      <command>db.password</command>: The password for
948                      the user.
949                    </para>
950                  </listitem>
951                  <listitem>
952                    <para>
953                      <command>db.url</command>: The connection url to
954                      the database.
955                    </para>
956                  </listitem>
957                  <listitem>
958                    <para>
959                      <command>userfiles</command>: The path to the
960                      directory where user files are located. This
961                      directory must be accessible from all job
962                      agents, i.e., by nfs or other file system
963                      sharing method.
964                    </para>
965                  </listitem>
966                  <listitem>
967                    <para>
968                      <command>plugins.dir</command>: The path to the
969                      directory where plug-ins are located. This
970                      directory must be accessible from all job
971                      agents, i.e., by nfs or other file system
972                      sharing method.
973                    </para>
974                  </listitem>
975                </itemizedlist>
976                See the <xref linkend="appendix.base.config"/> for
977                more information about the settings in
978                the <filename>base.config</filename> file.
979              </para>
980            </listitem>
981          </varlistentry>
982          <varlistentry id="installation.jobagent.client.properties">
983            <term>Edit
984            the <filename>jobagent.properties</filename> file</term>
985            <listitem>
986              <para>
987                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
988                file contains settings for the job agent. The most
989                important ones to specify value for are
990                <itemizedlist>
991                  <listitem>
992                    <para>
993                      <command>agent.password</command>: The password
994                      you set for the job agent user account in item
995                      <xref
996                      linkend="installation.jobagent.user_account"/>
997                      above.
998                    </para>
999                  </listitem>
1000                  <listitem>
1001                    <para>
1002                      <command>agent.id</command>: An ID that must be
1003                      unique for each job agent accessing the BASE application.
1004                    </para>
1005                  </listitem>
1006                  <listitem>
1007                    <para>
1008                      <command>agent.remotecontrol</command>: The
1009                      name or ip address of the web server if you want it
1010                      to be able to display info about running
1011                      jobs. The job agent will only allow connections
1012                      from computers specified in this setting.
1013                    </para>
1014                  </listitem>
1015                </itemizedlist>
1016              </para>
1017              <para>
1018                The <filename>jobagent.properties</filename> file
1019                contains many more configuration options. See
1020                the <xref linkend="appendix.jobagent.properties"/> for
1021                more information.
1022              </para>
1023            </listitem>
1024          </varlistentry>
1025          <varlistentry>
1026            <term>Register the job agent</term>
1027            <listitem>
1028              <para>
1029                From the <filename>bin</filename> directory, register
1030                the job agent with
1031                <programlisting>./jobagent.sh register</programlisting>
1032              </para>
1033            </listitem>
1034          </varlistentry>
1035          <varlistentry>
1036            <term>Start the job agent</term>
1037            <listitem>
1038              <para>
1039                From the <filename>bin</filename> directory, start the
1040                job agent with
1041                <programlisting>./jobagent.sh start &amp;</programlisting>
1042              </para>
1043              <para>
1044                See the <xref linkend="appendix.jobagent.sh"/>
1045                for more information about what you can do
1046                with the job agent command line interface.
1047              </para>
1048            </listitem>
1049          </varlistentry>
1050        </variablelist>
1051      </para>
1052    </sect2>
1053
1054
1055    <sect2 id="installation.jobagents.configuration">
1056      <title>Configuring the job agent</title>
1057   
1058      <para>
1059        A job agent will not execute a plug-in unless the administrator
1060        has configured the job agent to do so. There are two things that
1061        must be done:
1062      </para>
1063     
1064      <itemizedlist>
1065        <listitem>
1066        <para>
1067          Share the job agent to the users, groups and project that should be
1068          able to use it. If the job agent is not shared, only the owner of
1069          job agent is allowed to use it. Use the regular <guilabel>Share</guilabel>
1070          functionality to specify which users/groups/projects
1071          should be able to use the job agent. You must give
1072          them at least <command>USE</command> permission.
1073          To give all users permission to the job agent share it
1074          to the <command>EVERYONE</command> group.
1075        </para>
1076        </listitem>
1077       
1078        <listitem>
1079        <para>
1080          Selecting plug-ins that the job agent should handle. This can be
1081          done either from the plug-in pages or from the job agent pages. To register
1082          a plug-in with one or more job agents from the plug-in pages, go
1083          to the edit view of the plug-in and select the <guilabel>Job
1084          agents</guilabel> tab. To do the same from the job agent pages,
1085          go to the edit view of the job agent and select
1086          the <guilabel>Plugins</guilabel> tab. The registration dialogues
1087          are very similar but only the plug-in side of registration is
1088          described here. The major difference is that it is not possible
1089          to enable/disable the internal job queue for plug-in when using
1090          the jobagent side of the registration.
1091        </para>
1092        </listitem>
1093      </itemizedlist>
1094   
1095      <figure id="plugins.figures.jobagents">
1096        <title>Select job agents for a plug-in</title>
1097        <screenshot>
1098          <mediaobject>
1099            <imageobject><imagedata 
1100              scalefit="1" width="100%"
1101              fileref="figures/plugin_jobagents.png" format="PNG"
1102              /></imageobject>
1103          </mediaobject>
1104        </screenshot>
1105      </figure>
1106   
1107      <helptext external_id="plugindefinition.jobagents" 
1108        title="Job agents">
1109       
1110        <para>
1111          Use this tab to specify which job agents the plug-in is
1112          installed and allowed to be executed on.
1113        </para>
1114       
1115        <variablelist>
1116        <varlistentry>
1117          <term><guilabel>Run this plugin on</guilabel></term>
1118          <listitem>
1119            <para>
1120              You may select if the internal job queue should execute the
1121              plug-in or not.
1122            </para>
1123          </listitem>
1124        </varlistentry>
1125        <varlistentry>
1126          <term><guilabel>Job agents</guilabel></term>
1127          <listitem>
1128            <para>
1129              A list with the job agents where the plug-in is installed and
1130              allowed to be executed. Select a job agent in this list to display
1131              more configuration options for the plug-in.
1132            </para>
1133          </listitem>
1134        </varlistentry>
1135        <varlistentry>
1136          <term><guilabel>Add job agents</guilabel></term>
1137          <listitem>
1138            <para>
1139              Use this button to open a pop-up window for selecting
1140              job agents.
1141            </para>
1142          </listitem>
1143        </varlistentry>
1144        <varlistentry>
1145          <term><guilabel>Remove</guilabel></term>
1146          <listitem>
1147            <para>
1148              Remove the selected plug-in from the list.
1149            </para>
1150          </listitem>
1151        </varlistentry>
1152        </variablelist>
1153       
1154        <para>
1155          The following properties are only displayed when a
1156          job agent has been selected in the list. Each job agent may have it's
1157          own settings of these properties. If you leave the values unspecified
1158          the job agent will use the default values specified on the
1159          <guilabel>Plugin</guilabel> tab.
1160        </para>
1161       
1162        <variablelist>
1163        <varlistentry>
1164          <term><guilabel>Max memory</guilabel></term>
1165          <listitem>
1166            <para>
1167              The maximum amount of memory the plug-in is allowed to use.
1168              Add around 40MB for the Java run-time environment and BASE.
1169              If not specified Java will choose it's default value which is 64MB.
1170            </para>
1171          </listitem>
1172        </varlistentry>
1173        <varlistentry>
1174          <term><guilabel>Trusted</guilabel></term>
1175          <listitem>
1176            <para>
1177              If the plug-in should be executed in a protected or
1178              unprotected environment. Currently, BASE only supports
1179              running plug-ins in an unprotected environment.
1180            </para>
1181          </listitem>
1182        </varlistentry>
1183        <varlistentry>
1184          <term><guilabel>Priority boost</guilabel></term>
1185          <listitem>
1186            <para>
1187              Used to give a plug-in higher priority in the job queue.
1188              Values between 0 and 10 are allowed. A higher value will
1189              give the plug-in higher priority. The priority boost is useful
1190              if we, for example, want to use one server mainly for importing
1191              data. By giving all import plugins a priority boost they will
1192              be executed before all other jobs, which will have to wait
1193              until there are no more waiting imports.
1194            </para>
1195          </listitem>
1196        </varlistentry>
1197        </variablelist>
1198       
1199        <seeother>
1200          <other external_id="plugindefinition.edit">Plug-in properties</other>
1201          <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
1202        </seeother>
1203      </helptext>
1204    </sect2>
1205
1206  </sect1>      <!-- job agent setup -->
1207
1208  <sect1 id="installation.serverconfigurations">
1209    <title>Server configurations</title>
1210    <para>
1211      Some server configurations can be done when the installation process is finished and
1212      BASE is up and running. Log into BASE with administration rights and then
1213      open the configuration dialog from menu
1214      <menuchoice>
1215        <guimenu>Administrate</guimenu>
1216        <guimenuitem>Server settings</guimenuitem>
1217      </menuchoice>.
1218      Each tab in the configuration dialog-window is described below.
1219    </para>
1220   
1221      <figure id="installation.figures.serverconfiguration">
1222        <title>Server configuration</title>
1223        <screenshot>
1224          <mediaobject>
1225            <imageobject><imagedata 
1226              fileref="figures/server_configuration.png" format="PNG"
1227              /></imageobject>
1228          </mediaobject>
1229        </screenshot>
1230      </figure>
1231     
1232    <variablelist>
1233      <varlistentry>
1234        <term>
1235          <guilabel>File transfer</guilabel>
1236        </term>
1237        <listitem>
1238          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1239            <variablelist>
1240              <varlistentry>
1241                <term><guilabel>Max upload rate</guilabel></term>
1242                <listitem>
1243                  <para>
1244                    This is a limit of how many bytes of data that should be
1245                    transferred per second when uploading files to BASE. Prefixes
1246                    like k, M or G can be used for larger values, just like
1247                    described in the tab. The limit is per ongoing upload
1248                    and the default value is 100MB/s.
1249                  </para>
1250                </listitem>
1251              </varlistentry>
1252              <varlistentry>
1253                <term><guilabel>Max download rate</guilabel></term>
1254                <listitem>
1255                  <para>
1256                    This is a limit of how many bytes of data that should be
1257                    transferred per second when downloading files from BASE. Prefixes
1258                    like k, M or G can be used for larger values. The limit is per ongoing
1259                    download and the default value is unlimited.
1260                  </para>
1261                </listitem>
1262              </varlistentry>
1263              <varlistentry>
1264                <term><guilabel>Unlimited</guilabel></term>
1265                <listitem>
1266                  <para>
1267                    Check one or both to not limit the upload/download transfer rate.
1268                    In this case, the Internet connection of the server is the limit.
1269                  </para>
1270                </listitem>
1271              </varlistentry>
1272            </variablelist>
1273          </helptext>
1274        </listitem>
1275      </varlistentry>
1276      <varlistentry>
1277        <term>
1278          <guilabel>About</guilabel>
1279        </term>
1280        <listitem>
1281          <helptext external_id="serverconfig.about"
1282            title="Information about the server">
1283            <variablelist>
1284              <varlistentry>
1285                <term><guilabel>Administrator name</guilabel></term>
1286                <listitem>
1287                  <para>
1288                    Name of the responsible administrator. The name is displayed
1289                    at the bottom of each page in BASE and in the about-dialog.
1290                  </para>
1291                </listitem>
1292              </varlistentry>
1293              <varlistentry>
1294                <term><guilabel>Administrator email</guilabel></term>
1295                <listitem>
1296                  <para>
1297                    An email which the administrator can be contacted on. The
1298                    administrator name, visible at the bottom of each page, will
1299                    be linked to this email address.
1300                  </para>
1301                </listitem>
1302              </varlistentry>
1303              <varlistentry>
1304                <term><guilabel>About</guilabel></term>
1305                <listitem>
1306                  <para>
1307                    Text written in this field is displayed in the
1308                    <guilabel>About this server</guilabel> section on the login
1309                    page and in the about-dialog window. We recommend changing the
1310                    default Latin text to something meaningful, or remove it
1311                    to hide the section completely.
1312                  </para>
1313                </listitem>
1314              </varlistentry>
1315            </variablelist>
1316          </helptext>
1317        </listitem>
1318      </varlistentry>
1319      <varlistentry>
1320        <term>
1321          <guilabel>Get account</guilabel>
1322        </term>
1323        <listitem>
1324          <helptext external_id="serverconfig.getaccount"
1325            title="Instructions to get an account">
1326            <para>
1327              A description what a user should do to get
1328              an account on the particular BASE server. This text is linked
1329              to the <guilabel>Get an account!</guilabel> link on the login
1330              page. We recommend that the Latin text is replaced with some useful
1331              information, or that it is removed to hide the link.
1332            </para>
1333          </helptext>
1334        </listitem>
1335      </varlistentry>
1336      <varlistentry>
1337        <term>
1338          <guilabel>Forgotten password</guilabel>
1339        </term>
1340        <listitem>
1341          <helptext external_id="serverconfig.password"
1342            title="Instructions when password is forgotten.">
1343            <para>
1344              A description what a user should do if the password is forgotten.
1345              This text is linked
1346              to the <guilabel>Forgot your password?</guilabel> link on the login
1347              page. We recommend that the Latin text is replaced with some useful
1348              information, or that it is removed to hide the link.
1349            </para>
1350          </helptext>
1351        </listitem>
1352      </varlistentry>
1353      <varlistentry>
1354        <term>
1355          <guilabel>Links</guilabel>
1356        </term>
1357        <listitem>
1358          <helptext external_id="serverconfig.links" title="Configurable links">
1359            <para>
1360              External configurable link-types inside BASE.
1361              <note>
1362                <para>
1363                  Only link-types that have been set will be visible in the web
1364                  client.
1365                </para>
1366              </note>
1367            </para>
1368            <variablelist>
1369              <varlistentry>
1370                <term><guilabel>Help</guilabel></term>
1371                <listitem>
1372                  <para>
1373                    Links to where the help text is located. By default
1374                    this is set to the documentation for the latest released
1375                    BASE version on the BASE web site,
1376                    <ulink
1377                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1378                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1379                   
1380                    If you want the documentation for a specific version you will
1381                    have to setup a site for that yourself and then change the link
1382                    to that site. The documentation is included in the downloaded package
1383                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1384                  </para>
1385                </listitem>
1386              </varlistentry>
1387              <varlistentry>
1388                <term>
1389                  <guilabel>FAQ</guilabel>
1390                </term>
1391                <listitem>
1392                  <para>Where frequently asked questions can be found. Empty by default.</para>
1393                </listitem>
1394              </varlistentry>
1395              <varlistentry>
1396                <term>
1397                  <guilabel>Report a bug</guilabel>
1398                </term>
1399                <listitem>
1400                  <para>
1401                    Where the user could report bugs, feature request or
1402                    perhaps other feedback that concerns the program. As default
1403                    this is set to the feedback section on BASE web site,
1404                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1405                    Note that users must login in order to submit information.
1406                  </para>
1407                </listitem>
1408              </varlistentry>
1409            </variablelist>
1410          </helptext>
1411        </listitem>
1412      </varlistentry>
1413    </variablelist>
1414   
1415    <sect2 id="installation.broadcast">
1416      <title>Sending a broadcast message to logged in users</title>
1417
1418      <para>
1419        It is possible to send a message to all logged in user.
1420        Open the
1421        <menuchoice>
1422          <guimenu>Administrate</guimenu>
1423          <guimenuitem>Broadcast message</guimenuitem>
1424        </menuchoice> dialog box.
1425      </para>
1426     
1427      <figure id="installation.figures.broadcast">
1428        <title>Broadcast message</title>
1429        <screenshot>
1430          <mediaobject>
1431            <imageobject><imagedata 
1432              fileref="figures/broadcast_message.png" format="PNG"
1433              /></imageobject>
1434          </mediaobject>
1435        </screenshot>
1436      </figure>
1437     
1438      <helptext external_id="broadcast.message" title="Broadcast message">
1439        <para>
1440        This dialog allows you to specify a message that is sent to all
1441        logged in users as well as on the login form. It is also possible
1442        to "disable" login.
1443        </para>
1444        <variablelist>
1445        <varlistentry>
1446          <term><guilabel>Title</guilabel></term>
1447          <listitem>
1448            <para>
1449            The title of the message. It should be a short and concise to
1450            avoid confusion. The title will be displayed on a lot of places
1451            and a user may have to click on it to read the more detailed
1452            message.
1453            </para>
1454          </listitem>
1455        </varlistentry>
1456        <varlistentry>
1457          <term><guilabel>Disable login</guilabel></term>
1458          <listitem>
1459            <para>
1460            Mark this check-box to try to prevent new users from logging in. To
1461            avoid problems that can be caused by blocking the server admin out,
1462            the login is not completely disabled. Any user can still login but
1463            only after by-passing several warnings.
1464            </para>
1465          </listitem>
1466        </varlistentry>
1467        <varlistentry>
1468          <term><guilabel>Message</guilabel></term>
1469          <listitem>
1470            <para>
1471            If needed, a longer message giving more information. Users may
1472            have to click on a link to be able to see the complete message.
1473            </para>
1474          </listitem>
1475        </varlistentry>
1476        </variablelist>
1477       
1478        <note>
1479          The message will be enabled until it is manually removed by saving
1480          an empty form, or until the Tomcat server is restarted. Since the
1481          message is only kept in memory, a restart will always remove it.
1482        </note>
1483     
1484      </helptext>
1485     
1486    </sect2>
1487   
1488  </sect1>
1489
1490  <sect1 id="installation.migrate">
1491    <title>Migrating from MySQL to PostgreSQL</title>
1492   
1493    <para>
1494      It is possible to migrate a BASE installation on a MySQL database to a
1495      PostgreSQL database. In a real-world scenario a migration is probably coupled
1496      with a hardware upgrade, i.e. the MySQL installation is on one (the old) server
1497      and the PostgreSQL installation is on another (the new) server. While
1498      this is not any problem per se, it requires a few extra steps to ensure that
1499      everything has been moved to the new server. There are three main steps involved:
1500    </para>
1501   
1502    <variablelist>
1503      <varlistentry>
1504        <term>Export</term>
1505        <listitem>
1506          <para>
1507          The first step is to export all data in the existing database. Use
1508          the following procedure:
1509          </para>
1510         
1511          <orderedlist>
1512            <listitem>
1513              <para>
1514              Upgrade to the latest BASE release. This is recommended since
1515              it probably has fewer bugs.
1516              </para>
1517            </listitem>
1518
1519            <listitem>
1520              <para>
1521              Make sure that no other processes are writing to the database
1522              when the export is running. Shut down Tomcat and all job agents.
1523              It may also be a good idea to ensure that no backup scripts or
1524              other external programs are reading from the database at the same
1525              time. If the database is large, this may affect performance due to
1526              increased disk I/O.
1527              </para>
1528            </listitem>
1529           
1530            <listitem>
1531              <para>
1532              Create a temporary working directory in a suitable
1533              location. This directory will be used for storing the
1534              exported data. Disk I/O performance may be better if
1535              this directory is on a different disk than what the
1536              database is using. Ensure that the location has enough
1537              free space to hold all data from the BASE database. The dump
1538              typically uses less than 10% of the disk space used by the
1539              MySQL tables.
1540              </para>
1541            </listitem>
1542
1543            <listitem>
1544              <para>
1545              Make sure that you have configured migration-specific settings
1546              in the <filename>base.config</filename> file. In most cases the
1547              default settings should be good, but if you are experiencing
1548              performance problems it may be necessary to change some settings.
1549              See <xref linkend="appendix.base.config.migrate" /> for more
1550              information.
1551              </para>
1552            </listitem>
1553
1554            <listitem>           
1555              <para>
1556                Start the export by changing to the <filename
1557                class="directory">&lt;base-dir&gt;/bin/</filename>
1558                directory and execute:
1559              </para>
1560<programlisting>
1561./migrate.sh export <replaceable>/path/to/migration/dir</replaceable>
1562</programlisting>
1563              <para>
1564                where <replaceable>/path/to/migration/dir</replaceable>
1565                is replaced with the path to the working directory created above.
1566                Depending on the size of the BASE installation the export may
1567                take a long time.
1568              </para>
1569            </listitem>
1570          </orderedlist>
1571         
1572          <note>
1573            <para>
1574              Make sure that the migration working directory is empty to perform
1575              a full export. Existing files in the directory causes the corresponding
1576              tables to be skipped. This can be useful when debugging and after a
1577              server crash, since the export will resume where it stopped. Just make
1578              sure that the database hasn't been modified in the meantime.
1579            </para>
1580          </note>
1581          <warning>
1582            <para>
1583            When exporting, make sure that no other process is updating the
1584            database since that may create an inconsistent snapshot. The
1585            export process does not lock the database or take any other means
1586            to protect it against concurrent modifications.
1587            </para>
1588          </warning>
1589        </listitem>
1590      </varlistentry>
1591     
1592      <varlistentry>
1593        <term>Moving data</term>
1594        <listitem>
1595          <para>
1596          This step is about moving the data from the old BASE server to the
1597          new BASE server. If the migration is taking place on a single server,
1598          this step can probably be skipped.
1599          </para>
1600         
1601          <orderedlist>
1602            <listitem>
1603              <para>
1604              Download and unpack the BASE software on the new server. Make sure that you are
1605              using the same version as on the old server. It is also important that
1606              the database is identically configured. Pay special attention
1607              to the <filename>extended-properties.xml</filename> and
1608              <filename>raw-data-types.xml</filename> files and any files
1609              in the <filename
1610              class="directory">&lt;base-dir&gt;/WEB-INF/classes/extended-properties</filename>
1611              and <filename
1612              class="directory">&lt;base-dir&gt;/WEB-INF/classes/raw-data-types</filename>
1613              directories.
1614              The import program protects against some mistakes by comparing
1615              the column names from the export with the column names in the new
1616              database, but it will, for example, not check that data types match.
1617              </para>
1618             
1619              <tip>
1620                The easiest way to do this is to simply copy the BASE installation
1621                from the old server to the new server. Then, go through the
1622                configuration files and make sure that paths are correct.
1623              </tip>
1624             
1625            </listitem>
1626         
1627            <listitem>
1628              <para>
1629              Move user files from the old server to the new server. Make sure that
1630              the <property>userfiles</property> setting in <filename>base.config</filename>
1631              is correct.
1632              </para>
1633            </listitem>
1634           
1635            <listitem>
1636              <para>
1637              Move plug-ins from the old server to the new server. Make sure that
1638              the <property>plugins.dir</property> setting in <filename>base.config</filename>
1639              is correct.
1640              </para>
1641            </listitem>
1642
1643            <listitem>
1644              <para>
1645              Check other settings in <filename>base.config</filename> and
1646              other configuration files for settings that may be affected by
1647              the move.
1648              </para>
1649            </listitem>
1650         
1651          </orderedlist>
1652         
1653        </listitem>
1654      </varlistentry>
1655     
1656      <varlistentry>
1657        <term>Import</term>
1658        <listitem>
1659          <para>
1660            When everything has been moved and is properly configured it is
1661            time to start with the import.
1662          </para>
1663         
1664          <orderedlist>
1665            <listitem>
1666              <para>
1667              Create a new empty database following the
1668              instructions in <xref linkend="installation.main.database" />.
1669              Make the corresponding changes in <filename>base.config</filename>
1670              so that the BASE installation points to the new database.
1671              Also, make sure that you have configured migration-specific settings
1672              in the <filename>base.config</filename> file. In most cases the
1673              default settings should be good, but if you are experiencing
1674              performance problems it may be necessary to change some settings.
1675              See <xref linkend="appendix.base.config.migrate" /> for more
1676              information.
1677              </para>
1678            </listitem>
1679         
1680            <listitem>
1681              <para>
1682              Read the
1683              <ulink url="http://www.postgresql.org/docs/9.1/interactive/populate.html">http://www.postgresql.org/docs/9.1/interactive/populate.html</ulink>
1684              document from the PostgreSQL documentation and consider implementing some
1685              of the tips. The migration script makes sure that no indexes or foreign
1686              key constraints are active during the data import, but the tips about memory,
1687              checkpoint intervals, WAL archiving, etc. (section 14.4.5 and on) can be useful.
1688              It may also be a good idea to turn off the auto-vacuum daemon during the import.
1689              </para>
1690            </listitem>
1691           
1692            <listitem>
1693              <para>
1694                Start the import by changing to the <filename
1695                class="directory">&lt;base-dir&gt;/bin/</filename>
1696                directory and execute:
1697              </para>
1698<programlisting>
1699./migrate.sh import <replaceable>/path/to/migration/dir</replaceable>
1700</programlisting>
1701              <para>
1702                where <replaceable>/path/to/migration/dir</replaceable>
1703                is replaced with the path to the directory where
1704                the exported data is stored. Depending on
1705                the size of the BASE installation this may take a long time.
1706              </para>
1707             
1708              <para>
1709                When the import has been completed, run this command
1710                to create the last missing indexes:
1711              </para>
1712<programlisting>
1713./updateindexes.sh
1714</programlisting>
1715             
1716              <note>
1717                <title>Installations with separate web and database servers</title>
1718                <para>
1719                Both export and import may be executed against remote MySQL/PostgreSQL
1720                servers without limitation. The migration working directory need only
1721                to be accessible by the BASE migration program.
1722                </para>
1723              </note>
1724             
1725            </listitem>
1726           
1727            <listitem>
1728              <para>
1729              Restart Tomcat and verify that the migration was successful. Eg.
1730              check that you can log in to BASE, that you can access files,
1731              that plug-ins are working, etc. Then, shut everything down again.
1732              </para>
1733            </listitem>
1734
1735            <listitem>
1736              <para>
1737              Setup backup procedures for the new server. Verify that the
1738              backup is working before starting up Tomcat again.         
1739              Restart any job agents (make sure that the are configured to use
1740              the new server). When everything is up and running again, the
1741              <replaceable>/path/to/migration/dir</replaceable> directory
1742              and all files can be deleted.
1743              </para>
1744            </listitem>
1745          </orderedlist>
1746       
1747        </listitem>
1748      </varlistentry>
1749    </variablelist>
1750   
1751  </sect1>
1752
1753</chapter>
Note: See TracBrowser for help on using the repository browser.