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

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

References #2136: Remove support for spot images

Updated documentation.

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