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

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

References #1924, #1927 and #1325. Added information about incompatible changes and things to consider when updgrading to BASE 3.5.

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