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

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

References #2129: Preparations for Java 11 support

Adding extra JAR files that are required for running BASE with Java 11.

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