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

Last change on this file since 5884 was 5884, checked in by Nicklas Nordborg, 11 years ago

References #1630: Migrate from MySQL to PostgreSQL

Updated documentation with the changed behaviour for existing files.

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