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

Last change on this file since 7609 was 7609, checked in by Nicklas Nordborg, 3 years ago

References #2151: Pre-compile all JSP pages before releases

Updated documentation with changes related to source code incompatibilities.

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