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

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

References #2154: Test BASE with PostgreSQL 11

Updated documentation to recommend PostgreSQL 11 as the database to use. Re-ordered several sections so that PostgreSQL comes before MySQL.

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