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

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

References #2139: Switch to Java 11 (or later)

Updated the documentation.

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