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

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

References #2138: Officially support Java 11 (or later)

Updated documentation to recommend Java 11.

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