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

Last change on this file since 7826 was 7826, checked in by Nicklas Nordborg, 20 months ago

References #2214: Upgrade Hibernate and other 3-rd party components

Added a note about testing is only made with MySQL to the update section.

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