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

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

References #2137: Remove some of the deprecated code

Added a note in the documentation.

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