source: branches/2.6-stable/doc/src/docbook/admindoc/installation_upgrade.xml @ 4175

Last change on this file since 4175 was 4175, checked in by Nicklas Nordborg, 14 years ago

Fixes #949: Installation documentation has incorrect information about which Java version to use

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 49.8 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_upgrade.xml 4175 2008-03-14 08:47:48Z nicklas $
7
8  Copyright (C) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="installation_upgrade">
30  <?dbhtml dir="installation_upgrade"?>
31
32  <title>Installation, setup, migration, and upgrade instructions</title>
33
34  <note>
35    These instructions apply only to the BASE release which this
36    document is a part of.
37  </note>
38
39  <para>
40    This chapter is divided into four parts. First, the process of
41    upgrading a BASE 2 server is described. Followed by set up of job
42    agents. (For these two first parts it is assumed that there is a
43    running server.) Then, the first time installation instructions
44    follows, and the chapter is concluded with information on how to
45    migrate data from a BASE 1.2.17 server to a BASE 2 server.
46  </para>
47
48  <para>
49    The first time installation is only to be performed once,
50    optionally followed by a migration. The migration can only be done
51    to a pristine (empty) BASE 2 server with one exception; The
52    migration can be restarted if it fails during the RawBioAssaysData
53    transfer, for all other failure points the migration has to be
54    restarted with an empty database. Migration from several BASE 1
55    installations to one BASE 2 server is not supported.
56  </para>
57
58  <para>
59    The instructions here assume
60    that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
61    on the server side. Other servlet engines may work but we only
62    test tomcat.
63  </para>
64
65
66  <sect1 id="installation_upgrade.upgrade">
67    <title>Upgrade instructions</title>
68
69    <important id="dropindexes">
70      <title>Upgrading from BASE 2.4.3 or lower to 2.4.4 or higher</title>
71      <para>
72        Older releases of BASE 2 used to create indexes for many columns
73        in the dynamic database. The same columns are part of the primary
74        key for the tables so the indexes are not really needed. The
75        result is very bad performance since the database engine sometimes
76        get stuck in "index update" mode making the entire server
77        very slow. BASE 2.4.4 no longer creates the indexes. Indexes on
78        existing tables should be dropped to increase the performance.
79        Tests have shown a 50-90% decrease in execution time for some
80        plug-ins
81        (<ulink url="http://base.thep.lu.se/ticket/294">http://base.thep.lu.se/ticket/294</ulink>).
82      </para>
83      <para>
84        Removing the indexes is very simple. <emphasis>After the server
85        has been upgraded</emphasis> following the usual instructions below, issue the
86        the following commands:
87      </para>
88   
89      <programlisting>
90cd &lt;basedir&gt;/bin
91./dynamicdb.sh -v -dropindexes
92</programlisting>
93
94      <para>
95        Skip the <option>-dropindexes</option> option to do a dry
96        run without actually deleting the indexes.
97      </para>
98    </important>
99
100    <para>
101      As always, backup your database before attempting an
102      upgrade. The BASE team performs extensive testing before
103      releasing a new version of BASE but there are always a
104      possibility for unexpected events during upgrades. In upgrades
105      requiring a change in the underlying database there is no
106      (supported) way to revert to a previous version of BASE using
107      BASE tools, you need to use your backup for this use case.
108    </para>
109
110    <para>
111      The strategy here is to install the new BASE release to another
112      directory than the one in use. This requires transfer of
113      configuration settings to the new install but more on that
114      below.
115    </para>
116
117    <variablelist>
118      <varlistentry>
119        <term>Shut down the tomcat server</term>
120        <listitem>
121          <para>
122            If the BASE application is not shut down already, it is
123            time to do it now. Do something like <command>sudo
124            /etc/init.d/tomcat5.5 stop</command>
125          </para>
126        </listitem>
127      </varlistentry>
128
129      <varlistentry>
130        <term>Rename your current server</term>
131        <listitem>
132          <para>
133            Rename your current BASE 2 installation <command>mv
134              /path/to/base /path/to/base_old</command>.
135          </para>
136        </listitem>
137      </varlistentry>
138
139      <varlistentry>
140        <term>Download and unpack BASE</term>
141        <listitem>
142          <para>
143            There are several ways to download BASE. Please refer to
144            section <xref linkend="resources.home_page.download"/> for
145            information on downloading BASE, and select the item
146            matching your download option:
147          </para>
148
149          <variablelist>
150            <varlistentry>
151              <term><emphasis>Pre-compiled package</emphasis></term>
152              <listitem>
153                <para>
154                  If you selected to download a pre-compiled package,
155                  unpack the downloaded file with <command>tar zxpf
156                  base-...tar.gz</command>.
157                </para>
158              </listitem>
159            </varlistentry>
160
161            <varlistentry>
162              <term><emphasis>Source package</emphasis></term>
163              <listitem>
164                <para>
165                  If you selected to download a source package, unpack
166                  the downloaded file with <command>tar zxpf
167                  base-...src.tar.gz</command>. Change to the new
168                  directory, and issue <command>ant
169                  package.bin</command>. This will create a binary
170                  package in the current directory. Unpack this new
171                  package (outside of the source file hierarchy).
172                </para>
173              </listitem>
174            </varlistentry>
175
176            <varlistentry>
177              <term><emphasis>Subversion checkout</emphasis></term>
178              <listitem>
179                <para>
180                  This option is for advanced users only and is not
181                  covered here. Please refer to
182                  <xref linkend="core_ref.build"/> for information on
183                  this download option.
184                </para>
185              </listitem>
186            </varlistentry>
187
188          </variablelist>
189        </listitem>
190
191      </varlistentry>
192
193      <varlistentry>
194        <term>Transfer files and settings</term>
195        <listitem>
196          <para>
197            Settings from the previous installation must be
198            transferred to the new installation. This is most easily
199            done by comparing the configuration files from the
200            previous install with the new files. Do not just copy the
201            old files to the new install since new options may have
202            appeared.
203          </para>
204          <para>
205            In the main BASE configuration file,
206            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>,
207            fields that needs to be transferred are usually
208            <emphasis>db.username</emphasis>,
209            <emphasis>db.password</emphasis>,
210            and <emphasis>userfiles</emphasis>.
211          </para>
212          <para>
213            Local settings in the raw data
214            tables, <filename>&lt;base-dir&gt;/www/WEB-INF/classes/raw-data-types.xml</filename>,
215            may need to be transferred.
216          </para>
217        </listitem>
218      </varlistentry>
219
220      <varlistentry>
221        <term>Updating database schema</term>
222        <listitem>
223          <para>
224            It is recommended that you also perform an update of your
225            database schema.  Running the update scripts are not
226            always necessary when upgrading BASE, but the running the
227            update scripts are safe even in cases when there is no
228            need to run them. Change directory
229            to <filename
230            class="directory">&lt;base-dir&gt;/bin/</filename> and issue
231<programlisting>
232sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
233sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
234</programlisting>
235            where <emphasis>base_root_login</emphasis> is the login
236            for the root user and <emphasis>base_root_password</emphasis> is the
237            password. The login is optional. If not specified,
238            <constant>root</constant> is used as the login.
239          </para>
240        </listitem>
241      </varlistentry>
242
243      <varlistentry>
244        <term>Remove tomcat cache</term>
245        <listitem>
246          <para>
247            As tomcat user, remove cached files and directories. Do
248            something like
249<programlisting>cd /usr/share/apache-tomcat-5.5.15/
250rm -rf work/Catalina</programlisting>
251          </para>
252        </listitem>
253      </varlistentry>
254
255      <varlistentry>
256        <term>Start tomcat</term>
257        <listitem>
258          <para>
259            Start the tomcat server: <command>sudo
260              /etc/init.d/tomcat5.5 start</command>
261          </para>
262        </listitem>
263      </varlistentry>
264
265    </variablelist>
266
267    <para>
268      Done! Upgrade of BASE is finished.
269    </para>
270
271  </sect1>      <!-- Upgrade instructions -->
272
273
274  <sect1 id="installation_upgrade.jobagents">
275    <title>Installing job agents</title>
276
277    <para>
278      It is important to understand that the BASE application can be
279      spread on to several computers. The main BASE application is
280      serving HTTP requests, the underlying database engine is
281      providing storage and persistence of data, and job agents can be
282      installed on computers that will serve the BASE installation
283      with computing power and perform analysis and run plug-in. In a
284      straight forward setup one computer provides all services needed
285      for running BASE. From this starting point it is easy to add
286      computers to shares load from the BASE server by installing job
287      agents on these additional computers.
288    </para>
289
290    <para>
291      A job agent is a program running on a computer regularly
292      checking the BASE job queue for jobs awaiting execution. When
293      the job agent finds a job that it is enabled to execute, it
294      loads the plug-in and executes it. Job agents will in this way
295      free up resources on the BASE application server, and thus allow
296      the BASE server to concentrate on serving web pages. Job agents
297      are optional and must be installed and setup
298      separately. However, BASE is prepared for job agent setup and to
299      utilize the agents, but the agent are not required.
300    </para>
301
302    <para>
303      A job agent supports many configuration options that are not
304      supported by the internal job queue. For example, you can
305      <itemizedlist>
306        <listitem>
307          <para>
308            Specify exactly which plug-ins each job agent should be
309            able to execute.
310          </para>
311        </listitem>
312        <listitem>
313          <para>
314            Give some plug-ins higher priority than other plug-ins.
315          </para>
316        </listitem>
317        <listitem>
318          <para>
319            Specify which users/groups/projects should be able to use
320            a specific job agent.
321          </para>
322        </listitem>
323        <listitem>
324          <para>
325            Override memory settings and more for each plug-in.
326          </para>
327        </listitem>
328        <listitem>
329          <para>
330            Execute plug-ins in separate processes. Thus, a misbehaving
331            plug-in cannot bring the main application server down.
332          </para>
333        </listitem>
334        <listitem>
335          <para>
336            Add more computers with job agents as needed.
337          </para>
338        </listitem>
339      </itemizedlist>
340      All these options make it possible to create a very flexible
341      setup. For example one job agent can be assigned for importing
342      data only, another job agent can be assigned for running
343      analysis plug-ins for specific project only, and a third may be a
344      catch-all job agent that performs all low-priority jobs.
345    </para>
346
347    <sect2 id="installation_upgrade.jobagents.serverside">
348      <title>BASE application server side setup</title>
349      <para>
350        <variablelist>
351          <varlistentry>
352            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
353            <listitem>
354              <para>
355                The setting <command>jobqueue.internal.runallplugins</command>
356                should be set to <command>false</command> for the
357                BASE server. This setting is found in
358                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
359                file. The changes will not take effect until the
360                application server is restarted.
361              </para>
362             
363              <note>
364                Prior to BASE 2.5 the internal job queue had to be disabled
365                completely. This is no longer the case since it is possible to
366                enable/disable the internal job queue separately for
367                each plug-in.
368              </note>
369             
370            </listitem>
371          </varlistentry>
372          <varlistentry id="installation_upgrade.jobagent.user_account">
373            <term>Enable the job agent user account</term>
374            <listitem>
375              <para>
376                During installation of BASE a user account is created
377                for the job agent. This account is used by the job
378                agents to log on to BASE. The account is disabled by
379                default and must be enabled. Enable the account and
380                set a password using the BASE web interface.
381                The same password must also be set in the
382                <filename>jobagent.properties</filename> file, see
383                item
384                <xref linkend="installation_upgrade.jobagent.client.properties"/>
385                below.
386              </para>
387            </listitem>
388          </varlistentry>
389        </variablelist>
390      </para>
391    </sect2>
392
393    <sect2 id="installation_upgrade.jobagents.database">
394      <title>Database server setup</title>
395      <para>
396        <variablelist>
397          <varlistentry id="installation_upgrade.jobagent.database">
398            <term>Create a user account on the database</term>
399            <listitem>
400              <para>
401                This is the similar to granting database access for
402                the BASE server user in the in the regular BASE
403                installation, cf.
404                <xref
405                linkend="installation_upgrade.installation.database"/>.
406                You must create an account in the database that is
407                allowed to connect from the job agent server. MySQL
408                example:
409<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
410GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
411
412                Replace <command>job.agent.host</command> with the
413                host name of the server that is going to run the job
414                agent. You should also set password. This password is
415                used in item
416                <xref linkend="installation_upgrade.jobagent.client.config"/>
417                below in job agent server setup. You can use the same
418                database user and password as in the regular database
419                setup.
420              </para>
421            </listitem>
422          </varlistentry>
423        </variablelist>
424      </para>
425    </sect2>
426
427    <sect2 id="installation_upgrade.jobagents.client">
428      <title>Job agent client setup</title>
429      <para>
430        <variablelist>
431          <varlistentry>
432            <term>Download and unpack a regular BASE 2 distribution</term>
433            <listitem>
434              <para>
435                You <emphasis>must</emphasis> use the same version on
436                the web server and all job agents. You find the
437                downloads at
438                <ulink
439                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
440              </para>
441            </listitem>
442          </varlistentry>
443          <varlistentry id="installation_upgrade.jobagent.client.config">
444            <term>Edit the <filename>base.config</filename> file</term>
445            <listitem>
446              <para>
447                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
448                file must be configured as in regular BASE
449                installation, cf.
450                <xref
451                linkend="installation_upgrade.installation.configuration"/>,
452                to use the same database as the web server
453                application. The most important settings are
454                <itemizedlist>
455                  <listitem>
456                    <para>
457                      <command>db.username</command>: The database
458                      user you created in item
459                      <xref
460                      linkend="installation_upgrade.jobagent.database"/>
461                      above.
462                    </para>
463                  </listitem>
464                  <listitem>
465                    <para>
466                      <command>db.password</command>: The password for
467                      the user.
468                    </para>
469                  </listitem>
470                  <listitem>
471                    <para>
472                      <command>db.url</command>: The connection url to
473                      the database.
474                    </para>
475                  </listitem>
476                  <listitem>
477                    <para>
478                      <command>userfiles</command>: The path to the
479                      directory where user files are located. This
480                      directory must be accessible from all job
481                      agents, i.e., by nfs or other file system
482                      sharing method.
483                    </para>
484                  </listitem>
485                </itemizedlist>
486                See the <xref linkend="appendix.base.config"/> for
487                more information about the settings in
488                the <filename>base.config</filename> file.
489              </para>
490            </listitem>
491          </varlistentry>
492          <varlistentry id="installation_upgrade.jobagent.client.properties">
493            <term>Edit
494            the <filename>jobagent.properties</filename> file</term>
495            <listitem>
496              <para>
497                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
498                file contains settings for the job agent. The most
499                important ones to specify value for are
500                <itemizedlist>
501                  <listitem>
502                    <para>
503                      <command>agent.password</command>: The password
504                      you set for the job agent user account in item
505                      <xref
506                      linkend="installation_upgrade.jobagent.user_account"/>
507                      above.
508                    </para>
509                  </listitem>
510                  <listitem>
511                    <para>
512                      <command>agent.id</command>: An ID that must be
513                      unique for each job agent accessing the BASE application.
514                    </para>
515                  </listitem>
516                  <listitem>
517                    <para>
518                      <command>agent.remotecontrol</command>: The
519                      name/ip address of the web server if you want it
520                      to be able to display info about running
521                      jobs. The job agent will only allow connections
522                      from computers specified in this setting.
523                    </para>
524                  </listitem>
525                </itemizedlist>
526              </para>
527              <para>
528                The <filename>jobagent.properties</filename> file
529                contains many more configuration options. See
530                the <xref linkend="appendix.jobagent.properties"/> for
531                more information.
532              </para>
533            </listitem>
534          </varlistentry>
535          <varlistentry>
536            <term>Register the job agent</term>
537            <listitem>
538              <para>
539                From the <filename>bin</filename> directory, register
540                the job agent with
541                <programlisting>./jobagent.sh register</programlisting>
542              </para>
543            </listitem>
544          </varlistentry>
545          <varlistentry>
546            <term>Start the job agent</term>
547            <listitem>
548              <para>
549                From the <filename>bin</filename> directory, start the
550                job agent with
551                <programlisting>./jobagent.sh start &amp;</programlisting>
552              </para>
553              <para>
554                See the <xref linkend="appendix.jobagent.sh"/>
555                for more information about what you can do
556                with the job agent command line interface.
557              </para>
558            </listitem>
559          </varlistentry>
560        </variablelist>
561      </para>
562    </sect2>
563
564    <sect2 id="installation_upgrade.jobagents.configuration">
565      <title>Configuring the job agent</title>
566      <para>
567        Before the job agent starts executing jobs for you it must be
568        configured. The configuration is done through the BASE web
569        interface. See <xref linkend="plugins.jobagents" />
570        <variablelist>
571          <varlistentry>
572            <term>Configure the plug-ins the job agent should handle</term>
573            <listitem>
574              <para>
575                <itemizedlist>
576                  <listitem>
577                    <para>
578                      Go to the
579                      <menuchoice>
580                        <guimenu>Administrate</guimenu>
581                        <guisubmenu>Plugins</guisubmenu>
582                        <guimenuitem>Job agents</guimenuitem>
583                      </menuchoice> menu.
584                    </para>
585                  </listitem>
586                  <listitem>
587                    <para>
588                      Select the job agent and click on the &gbEdit;
589                      button.
590                    </para>
591                  </listitem>
592                  <listitem>
593                    <para>
594                      On the <guilabel>Plugins</guilabel> tab you can
595                      specify which plug-ins the job agent should
596                      handle. Note that if you have installed external
597                      plug-ins on the web server, those plug-ins must be
598                      installed on the job agent as well. It is
599                      possible to specify different paths to the JAR
600                      file for each job agent.
601                    </para>
602                  </listitem>
603                </itemizedlist>
604              </para>
605            </listitem>
606          </varlistentry>
607          <varlistentry>
608            <term>Grant users access to the job agent</term>
609            <listitem>
610              <para>
611                Use the regular <guilabel>Share</guilabel>
612                functionality to specify which users/groups/projects
613                should be able to use the job agent. You must give
614                them at least <command>USE</command> permission.
615              </para>
616            </listitem>
617          </varlistentry>
618        </variablelist>
619      </para>
620    </sect2>
621
622  </sect1>      <!-- job agent setup -->
623
624
625  <sect1 id="installation_upgrade.installation">
626    <title>Installation instructions</title>
627
628    <variablelist>
629
630      <varlistentry>
631        <term>Java</term>
632        <listitem>
633          <para>
634            Download and install Java SDK 1.6, available from
635            <ulink url="http://java.sun.com/" />. Earlier versions
636            may work (eq. 1.5), but are not supported.
637          </para>
638        </listitem>
639      </varlistentry>
640
641      <varlistentry>
642        <term>Tomcat</term>
643        <listitem>
644          <para>
645            Download and install tomcat 5.5.16 or later, available
646            from <ulink
647            url="http://jakarta.apache.org/tomcat/" />
648            <important>
649              You MUST make sure that Tomcat uses the SERVER mode of
650              the Java run time engine
651              (see <ulink
652              url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
653            </important>
654            On Linux you do this by setting the environment variable:
655            <code>CATALINA_OPTS</code> to <code>-server</code>. It is
656            also a good idea to specify the maximum allowed memory to
657            use: <code>-server -Xmx500m</code> sets it to 500
658            megabytes. Basically add the next line close to the top of
659            the <filename>catalina.sh</filename> script that comes
660            with tomcat
661            (directory <filename
662            class="directory">bin</filename>):
663<programlisting>CATALINA_OPTS="-server -Xmx500m"</programlisting>
664          </para>
665          <para>
666            For more information about Tomcat options see
667            <ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
668          </para>
669        </listitem>
670      </varlistentry>
671
672      <varlistentry>
673        <term>Set up SQL database</term>
674        <listitem>
675          <para>
676            BASE 2
677            utilize <ulink
678            url="http://www.hibernate.org/">Hibernate</ulink> for
679            object persistence to a relational database. Hibernate
680            supports many database engines, but so far we only work
681            with <ulink url="http://www.mysql.com">MySQL</ulink>
682            and <ulink
683            url="http://www.postgresql.org/">PostgreSQL</ulink>.
684          </para>
685
686          <variablelist>
687            <varlistentry>
688              <term>MySQL</term>
689              <listitem>
690                <para>
691                  Download and install MySQL (tested with version
692                  5.0), available from
693                  <ulink url="http://www.mysql.com/" />. You need to
694                  be able to connect to the server over TCP, so
695                  the <emphasis>skip-networking</emphasis> option
696                  must <command>not</command> be used. The InnoDB
697                  table engine is also needed, so do not disable them
698                  (not that you would) but you may want to tune the
699                  InnoDB behaviour before creating BASE
700                  databases. BASE comes pre-configured for MySQL so
701                  there is no need to change database settings in the
702                  BASE configuration files.
703                </para>
704              </listitem>
705            </varlistentry>
706            <varlistentry>
707              <term>PostgreSQL</term>
708              <listitem>
709                <para>
710                  PostgreSQL 8.2 seems to be working very well with
711                  BASE and Hibernate. Download and install PostgreSQL,
712                  available from
713                  <ulink url="http://www.postgresql.org/" />. you must
714                  edit
715                  your <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
716                  file. Uncomment the settings for Postgres and
717                  comment out the settings for MySQL.
718                </para>
719               
720                <note>
721                  <para>
722                  Postgres versions prior to 8.2 have a non-optimal solution
723                  for locking rows in certain situations. This may cause two
724                  seemingly independent transactions to lock if they just
725                  reference a common database row. This may happen, for example,
726                  when importing raw data that have references to the same
727                  reporters. The problem has been solved in Postgres 8.2.
728                  </para>
729                </note>
730               
731              </listitem>
732            </varlistentry>
733          </variablelist>
734
735        </listitem>
736      </varlistentry>
737
738      <varlistentry>
739        <term>BASE (download and unpacking)</term>
740        <listitem>
741          <para>
742            <ulink
743            url="http://base.thep.lu.se/wiki/DownloadPage">Download
744            BASE</ulink> and unpack the downloaded file,
745            i.e. <command>tar zxpf base-...tar.gz</command>. If you
746            prefer to have the bleeding edge version of BASE, perform
747            a checkout of the source from the subversion repository
748            (subversion checkout instructions at
749            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
750            trac site</ulink>).
751          </para>
752          <para>
753            If you choose to download the binary package, skip to the
754            next item. The rest of us, read on and compile BASE 2. If
755            you downloaded a source distribution, unpack the
756            downloaded file <command>tar zxpf
757            base-...src.tar.gz</command>, or you may have performed a
758            subversion checkout.  Change to the 'root' base2
759            directory, and issue <command>ant
760            package.bin</command>. This will create a binary package
761            in the base2 'root' directory. Unpack this new package
762            (outside of the source file hierarchy), and from now on
763            the instructions are the same irrespective where you got
764            the binary package.
765          </para>
766          <para>
767            <emphasis>This section is intended for advanced users and
768              programmers only. In cases when you want to change the
769              BASE code and try out personalized features it may be
770              advantageous to run the tweaked BASE server against the
771              development tree. Instructions on how to accomplish this
772              is available in the
773              <ulink
774              url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
775              BASE document</ulink>. When you return back after
776              compiling in the subversion tree you can follow the
777              instruction here (with obvious changes to
778              paths).</emphasis>
779          </para>
780        </listitem>
781      </varlistentry>
782
783      <varlistentry id="installation_upgrade.installation.database">
784        <term>BASE (database engine)</term>
785        <listitem>
786          <para>
787            Instructions for MySQL and PostgreSQL are available
788            below. The database names (base2 and base2dynamic is used
789            here), the <emphasis>db_user</emphasis>, and
790            the <emphasis>db_password</emphasis> can be changed during
791            the creation of the databases. It is recommended to change
792            the <emphasis>db_password</emphasis>, the other changes
793            can be made if desired. The database names,
794            the <emphasis>db_user</emphasis>, and
795            the <emphasis>db_password</emphasis> are needed in a later
796            step below when configuring BASE.
797          </para>
798          <note>
799            Note that the <emphasis>db_user</emphasis> name
800            and <emphasis>db_password</emphasis> set here is used
801            internally by BASE in communication with the database and
802            is never used to log on to the BASE application.
803          </note>
804          <variablelist>
805            <varlistentry>
806              <term>MySQL</term>
807              <listitem>
808                <para>
809                  Create a new database for BASE, and add a
810                  <emphasis>db_user</emphasis> with at least
811                  <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
812                  <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
813                  <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
814                  <emphasis>INDEX</emphasis>,
815                  and <emphasis>ALTER</emphasis> permission for the
816                  new database. To do this, connect to your MySQL
817                  server and issue the next lines:
818<programlisting>CREATE DATABASE base2;
819CREATE DATABASE base2dynamic;
820GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
821GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
822                </para>
823                <para>
824                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
825                  file contains the above statements and can be used
826                  by the <filename>mysql</filename> command-line tool
827                  (remember to edit
828                  the <emphasis>db_user</emphasis>,
829                  <emphasis>db_password</emphasis>,
830                  and the database names in the script file before
831                  executing the command): <command>mysql -uroot -p
832                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
833                  header in the script file contains further
834                  information about the script.
835                </para>
836              </listitem>
837            </varlistentry>
838            <varlistentry>
839              <term>PostgreSQL</term>
840              <listitem>
841                <para>
842                  Create a new database for BASE, and add a
843                  <emphasis>db_user</emphasis> with the proper
844                  privileges. To do this, log in as your PostgreSQL
845                  user and issue these lines (omit comments):
846<programlisting>createuser db_user -P
847  # this will prompt for an password for the new user, and issue two
848  # more question that should be answered with character 'n' for no.
849createdb --owner db_user --encoding UNICODE base2
850psql base2
851  # this will start the psql command line tool. Issue the next line
852  # within the tool and quit with a '\q'.
853CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
854                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
855                  file contains the above statements and can be used
856                  by the <filename>psql</filename> command-line tool:
857                  <command>psql -f ./misc/sql/createdb.posgres.sql
858                    template1</command> The header in the script file
859                  contains further information about the script.
860                </para>
861              </listitem>
862            </varlistentry>
863          </variablelist>
864        </listitem>
865      </varlistentry>
866
867      <varlistentry>
868        <term>BASE (file storage setup)</term>
869        <listitem>
870          <para>
871            An area for file storage must be setup. Create an empty
872            directory in a proper location in your file system, and
873            set the owner to be the same as the one that the tomcat
874            server will be running as. Remember this location for
875            later use.
876          </para>
877        </listitem>
878      </varlistentry>
879
880      <varlistentry id="installation_upgrade.installation.configuration">
881        <term>BASE (configuration)</term>
882        <listitem>
883          <para>
884            Basic BASE configuration is done in
885            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>:
886            <itemizedlist>
887              <listitem>
888                Uncomment the database engine section that match your setup.
889              </listitem>
890              <listitem>
891                Modify the <emphasis>db.url</emphasis>,
892                <emphasis>db.dynamic.catalog</emphasis>,
893                <emphasis>db.username</emphasis>,
894                and <emphasis>db.password</emphasis> settings to match
895                your choice above. (<emphasis>database host and
896                database name (e.g. base2)</emphasis>,
897                <emphasis>e.g. base2dynamic</emphasis>,
898                <emphasis>db_user</emphasis>, and
899                <emphasis>db_password</emphasis>, respectively.)
900              </listitem>
901              <listitem>
902                Modify the <emphasis>userfiles</emphasis> setting to
903                match your choice above.
904              </listitem>
905            </itemizedlist>
906            See the <xref linkend="appendix.base.config"/> for more
907            information about the settings in
908            the <filename>base.config</filename> file.
909          </para>
910          <para>
911            <emphasis>Optional but recommended.</emphasis> You may want
912            to modify extended properties to fit your needs. Extended
913            properties are defined in
914            <filename>&lt;base-dir&gt;/www/WEB-INF/classes/extended-properties.xml</filename>.
915            There is an
916            administrator <ulink
917            url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
918            discussing extended properties</ulink> available. If you
919            plan to perform a migration of a BASE 1.2 database you
920            should probably not remove any extended properties
921            columns (this is not tested so the outcome is currently
922            undefined). However, adding columns does not affect
923            migration.
924          </para>
925        </listitem>
926      </varlistentry>
927
928      <varlistentry>
929        <term>BASE (database initialization)</term>
930        <listitem>
931          <para>
932            Change directory to
933            <filename class="directory">&lt;base-dir&gt;/bin</filename>
934            and run <filename>initdb.sh</filename> as
935<programlisting>./initdb.sh [base_root_login] base_root_password</programlisting>
936
937            <important>
938            <para>
939            The <emphasis>base_root_login</emphasis> and
940            <emphasis>base_root_password</emphasis> you use here
941            is given to the BASE web application root user account.
942            The <emphasis>base_root_login</emphasis> is optional. If
943            not specified, <constant>root</constant> is used for
944            the login.
945            </para>
946            </important>
947            If the initialisation script fail, it is most probably a
948            problem related to the underlying database. Make sure that
949            the database accepts network connection and make sure that
950            <emphasis>db_user</emphasis> has proper credentials.
951          </para>
952        </listitem>
953      </varlistentry>
954
955      <varlistentry>
956        <term>BASE and tomcat</term>
957        <listitem>
958          <para>
959            Either move the <filename
960            class="directory">&lt;base-dir&gt;/www</filename> directory
961            to the tomcat <filename class="directory">webapps</filename>
962            directory or create a symbolic link from the tomcat
963            <filename class="directory">webapps</filename> directory to
964            the <filename class="directory">&lt;base-dir&gt;/www</filename>
965            directory
966<programlisting>cd /path/to/tomcat/webapps
967ln -s /path_to_base/www base2</programlisting>
968            Start/restart tomcat, and try http://hostname:8080/base2
969            (change <emphasis>hostname</emphasis> to your hostname) in
970            your favourite browser. BASE log-in page should appear
971            after a few seconds.
972          </para>
973        </listitem>
974      </varlistentry>
975
976      <varlistentry>
977        <term>BASE, apache, and apache/tomcat connector</term>
978        <listitem>
979          <para>
980            <emphasis>This step is optional</emphasis>.
981          </para>
982          <para>
983            If you want run the tomcat server through the apache web
984            server, you need to install the apache version 2 web
985            server, available
986            from <ulink
987            url="http://www.apache.org/">http://www.apache.org/</ulink>,
988            and a apache-tomcat connector, available
989            from <ulink
990            url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
991            So, we got you there;-) To be honest, this step is not
992            really well documented since we previously used SuSE 9.3
993            on our demo/test server, and apache/tomcat/mod_jk comes
994            pre-installed. The current server does not use the
995            apache/tomcat connector. What you need to do is something
996            like this
997            <itemizedlist>
998              <listitem>
999                Get that tomcat server running in stand-alone
1000                mode.
1001              </listitem>
1002              <listitem>
1003                Get the apache 2 server running.
1004              </listitem>
1005              <listitem>
1006                Install mod_jk. Note, different version are used for
1007                apache 1.3 and 2. In SuSE 9.3 this step is done by
1008                installing <filename>mod_jk-ap20</filename>.
1009              </listitem>
1010              <listitem>
1011                Create a <filename>workers.properties</filename> file
1012                in the
1013                tomcat <filename class="directory">base</filename>
1014                directory (commonly copied from a template).
1015              </listitem>
1016              <listitem>
1017                Create a <filename>jk.conf</filename> file in the
1018                apache <filename class="directory">conf</filename>
1019                directory (commonly copied from a template), and make
1020                sure that <emphasis>jk</emphasis> is added to the
1021                modules to be loaded when apache starts.
1022              </listitem>
1023              <listitem>
1024                In <filename>jk.conf</filename> add the lines below
1025                and change paths appropriately.
1026<programlisting># The following lines makes apache aware of the location of
1027# the /base2 context
1028Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
1029&lt;Directory "/srv/www/tomcat5/base/webapps/base2"&gt;
1030Options Indexes FollowSymLinks
1031allow from all
1032&lt;/Directory&gt;
1033# The following lines mounts all base2 jsp files to tomcat
1034JkMount /base2 ajp13
1035JkMount /base2/* ajp13
1036# The following lines prohibits users from directly accessing WEB-INF
1037&lt;Location "/base2/WEB-INF/"&gt;
1038AllowOverride None
1039deny from all
1040&lt;/Location&gt;</programlisting>
1041              </listitem>
1042            </itemizedlist>
1043            You must restart the apache and the tomcat server after above steps.
1044          </para>
1045        </listitem>
1046      </varlistentry>
1047
1048      <varlistentry>
1049        <term>Setup done!</term>
1050        <listitem>
1051          <para>
1052            Happy BASEing. Now you can log on to your BASE 2 server as
1053            user <emphasis>root</emphasis> (use
1054            the <emphasis>base_root_password</emphasis> from the
1055            database initialization step above). You should begin with
1056            creating a couple user accounts, for more information on
1057            how to create user accounts please refer to
1058            <xref linkend="user_administration"/>.
1059          </para>
1060          <para>
1061            If you are planning to perform a migration of data from
1062            BASE 1.2.x please perform the steps in
1063            <xref linkend="installation_upgrade.migration"/> before
1064            doing anything else with your new BASE installation.
1065          </para>
1066        </listitem>
1067      </varlistentry>
1068
1069    </variablelist>
1070
1071  </sect1>      <!-- Installation instructions -->
1072
1073  <sect1 id="installation_upgrade.serverconfigurations">
1074    <title>Server configurations</title>
1075    <para>
1076      Some server configurations can be done when the installation process is finished and
1077      BASE is up and running. Log into BASE with administration rights and then
1078      open the configuration dialog from menu
1079      <menuchoice>
1080        <guimenu>Administrate</guimenu>
1081        <guimenuitem>Server settings</guimenuitem>
1082      </menuchoice>.
1083      Each tab in the configuration dialog-window is described below.
1084    </para>
1085    <variablelist>
1086      <varlistentry>
1087        <term>
1088          <guilabel>File transfer</guilabel>
1089        </term>
1090        <listitem>
1091          <helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1092            <variablelist>
1093              <varlistentry>
1094                <term><guilabel>Max transfer rate</guilabel></term>
1095                <listitem>
1096                  <para>
1097                    This is a limit of how many bytes of data that should be
1098                    transfered per second when uploading files to BASE. Prefixes
1099                    like k, M or G can be used for larger values, just like
1100                    described in the tab. The limit is per ongoing upload
1101                    and the default value is 100MB/s.
1102                  </para>
1103                </listitem>
1104              </varlistentry>
1105              <varlistentry>
1106                <term><guilabel>Unlimited</guilabel></term>
1107                <listitem>
1108                  <para>
1109                    Check this to not limit the transfer rate. In this case, the
1110                    internet connection of the server is the limit.
1111                  </para>
1112                </listitem>
1113              </varlistentry>
1114            </variablelist>
1115          </helptext>
1116        </listitem>
1117      </varlistentry>
1118      <varlistentry>
1119        <term>
1120          <guilabel>About</guilabel>
1121        </term>
1122        <listitem>
1123          <helptext external_id="serverconfig.about"
1124            title="Information about the server">
1125            <variablelist>
1126              <varlistentry>
1127                <term><guilabel>Administrator name</guilabel></term>
1128                <listitem>
1129                  <para>
1130                    Name of the responsible administrator. The name is displayed
1131                    at the bottom of each page in BASE and in the about-dialog.
1132                  </para>
1133                </listitem>
1134              </varlistentry>
1135              <varlistentry>
1136                <term><guilabel>Administrator email</guilabel></term>
1137                <listitem>
1138                  <para>
1139                    An email which the administrator can be contacted on. The
1140                    administrator name, visible at the bottom of each page, will
1141                    be linked to this email address.
1142                  </para>
1143                </listitem>
1144              </varlistentry>
1145              <varlistentry>
1146                <term><guilabel>About</guilabel></term>
1147                <listitem>
1148                  <para>
1149                    Text written in this field is displayed in the
1150                    <guilabel>About this server</guilabel> section on the login
1151                    page and in the about-dialog window. We recommend changing the
1152                    default latin text to something meaningful, or remove it
1153                    to hide the section completely.
1154                  </para>
1155                </listitem>
1156              </varlistentry>
1157            </variablelist>
1158          </helptext>
1159        </listitem>
1160      </varlistentry>
1161      <varlistentry>
1162        <term>
1163          <guilabel>Get account</guilabel>
1164        </term>
1165        <listitem>
1166          <helptext external_id="serverconfig.getaccount"
1167            title="Instructions to get an account">
1168            <para>
1169              A description what a none-registered user should do to get
1170              an account on the particular BASE-server. This text is linked
1171              to the <guilabel>Get an account!</guilabel> link on the login
1172              page. We recommend that the latin text is replaced with some useful
1173              information, or that it is removed to hide the link.
1174            </para>
1175          </helptext>
1176        </listitem>
1177      </varlistentry>
1178      <varlistentry>
1179        <term>
1180          <guilabel>Forgotten password</guilabel>
1181        </term>
1182        <listitem>
1183          <helptext external_id="serverconfig.password"
1184            title="Instructions when password is forgotten.">
1185            <para>
1186              A description what an user should do if the password is forgotten.
1187              This text is linked
1188              to the <guilabel>Forgot your password?</guilabel> link on the login
1189              page. We recommend that the latin text is replaced with some useful
1190              information, or that it is removed to hide the link.
1191            </para>
1192          </helptext>
1193        </listitem>
1194      </varlistentry>
1195      <varlistentry>
1196        <term>
1197          <guilabel>Links</guilabel>
1198        </term>
1199        <listitem>
1200          <helptext external_id="serverconfig.links" title="Configurable links">
1201            <para>
1202              External configurable link-types inside BASE.
1203              <note>
1204                <para>
1205                  Only link-types that have been set will be visible in the web
1206                  client.
1207                </para>
1208              </note>
1209            </para>
1210            <variablelist>
1211              <varlistentry>
1212                <term><guilabel>Help</guilabel></term>
1213                <listitem>
1214                  <para>
1215                    Links to where the help text is located. By default
1216                    this is set to the documentation for the latest released
1217                    BASE version on the BASE web site,
1218                    <ulink
1219                      url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1220                      http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1221                   
1222                    If you want the documentation for a specific version you will
1223                    have to setup a site for that yourself and then change the link
1224                    to that site. The documentation is included in the downloaded package
1225                    in the directory <filename>&lt;basedir&gt;/doc/html</filename>.
1226                  </para>
1227                </listitem>
1228              </varlistentry>
1229              <varlistentry>
1230                <term>
1231                  <guilabel>FAQ</guilabel>
1232                </term>
1233                <listitem>
1234                  <para>Where frequently asked questions can be found. Empty by default.</para>
1235                </listitem>
1236              </varlistentry>
1237              <varlistentry>
1238                <term>
1239                  <guilabel>Report a bug</guilabel>
1240                </term>
1241                <listitem>
1242                  <para>
1243                    Where the user could report bugs, feature request or
1244                    perhaps other feedback that concerns the program. As default
1245                    this is set to the feedback section on BASE web site,
1246                    <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1247                    Note that users must login in order to submit information.
1248                  </para>
1249                </listitem>
1250              </varlistentry>
1251            </variablelist>
1252          </helptext>
1253        </listitem>
1254      </varlistentry>
1255    </variablelist>
1256  </sect1>
1257
1258  <sect1 id="installation_upgrade.migration">
1259    <title>Migration instructions</title>
1260
1261    <caution>
1262      <title>The disclaimer section</title>
1263      <para>
1264        We have made extensive testing of the migration from BASE1.2
1265        to BASE2. To our knowledge the migration works but we cannot
1266        guarantee perfect functionality. The migration tool is
1267        supplied as is and usage is done at your risk. We are
1268        committed to solve migration problems at the level of
1269        transferring data from BASE 1.2 to 2.2.x, but cannot resolve
1270        data loss issues in a running BASE 2 server due to imperfect
1271        migration. When you start the migration tool you are required
1272        to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1273        to the <filename>migrate_from_1.2.sh</filename>
1274        script. Remember to check that the migration performed well
1275        before you decide to delete your 1.2 installation.
1276      </para>
1277      <para>
1278        Migration from the latest BASE 1.2.x release to the latest is
1279        supported.
1280      </para>
1281    </caution>
1282
1283    <para>
1284      Verify that your BASE 2 installation is up and running before
1285      attempting migration. Preferably try to log in using the root
1286      user through the web interface.
1287    </para>
1288
1289    <para>
1290      Make sure your BASE 1.2 runs with the latest
1291      (<emphasis>pristine</emphasis>) schema
1292      version, <emphasis>i.e.,</emphasis> the migration will only
1293      support an unmodified BASE 1.2 installation. If you have an out
1294      of date schema version, please upgrade to the latest schema
1295      using BASE 1.2 tools before migrating. If you have made local
1296      changes to the BASE 1.2 schema you need to patch the BASE 2
1297      schema as well as make proper changes to the migration program.
1298      If there are added columns to the reporter table in your BASE
1299      1.2 database you need to transfer the additional information
1300      after migration (even if you modified the BASE
1301      2 <filename>extended-properties.xml</filename> file).
1302    </para>
1303
1304    <para>
1305      The behaviour of migration is controlled
1306      through <filename>migration.properties</filename> file (see
1307      <xref linkend="appendix.migrate.properties"/>), but you should
1308      know what you do when you change parameters in this file.
1309    </para>
1310
1311    <para>
1312      Migration can be restarted in one specific case only; If the
1313      migration fails during the RawBioAssaysData transfer simply
1314      restart the migration and the script will ask you to verify that
1315      a restart should be attempted. For all other failure points the
1316      migration has to be restarted with an empty database.
1317    </para>
1318
1319    <para>
1320      Migration is performed with the following steps:
1321      <orderedlist>
1322
1323        <listitem>
1324          <para>
1325            To transfer files from BASE 1.2 (default migration
1326            behaviour), you must have file system access to BASE 1.2
1327            files, <emphasis>i.e.,</emphasis> the <filename
1328            class="directory">/ 1.2/data</filename>
1329            directory containing directories
1330            <filename class="directory">rawdata</filename>,
1331            <filename class="directory">uploads</filename>,
1332            <filename class="directory">protocols</filename>, ...
1333          </para>
1334        </listitem>
1335
1336        <listitem>
1337          <para>
1338            Change settings in the file
1339            <filename>&lt;base-dir&gt;/dist/www/WEB-INF/classes/migrate.properties</filename>.
1340            The available options are commented:
1341            <itemizedlist>
1342              <listitem>
1343                <para>
1344                  Modify <emphasis>db1.*</emphasis> parameters to
1345                  match your BASE 1.2 installation.
1346                </para>
1347              </listitem>
1348              <listitem>
1349                <para>
1350                  Set <emphasis>userfiles</emphasis> (note, this is
1351                  not the same parameter as
1352                  in <filename>base.config</filename>) to point to the
1353                  directory containing the BASE 1.2 files (defined in a
1354                  previous step above).
1355                </para>
1356              </listitem>
1357              <listitem>
1358                <para>
1359                  Set the <emphasis>pluginDir</emphasis> to point to
1360                  the directory where your BASE 1.2 plug-ins are
1361                  installed. The default is
1362                  <filename
1363                  class="directory">/usr/local/base/plugins</filename>.
1364                </para>
1365              </listitem>
1366              <listitem>
1367                <para>
1368                  Modify <emphasis>root.password</emphasis>.
1369                </para>
1370              </listitem>
1371              <listitem>
1372                <para>
1373                  Change the <emphasis>deletefiles</emphasis> setting
1374                  wisely. If you
1375                  set <emphasis>deletefiles=yes</emphasis> all BASE
1376                  1.2 files will be physically removed when copied to
1377                  BASE 2. Leave this options
1378                  as <emphasis>deletefiles=no</emphasis> unless you
1379                  are absolutely sure of what you are doing.
1380                </para>
1381              </listitem>
1382            </itemizedlist>
1383          </para>
1384        </listitem>
1385
1386        <listitem>
1387          <para>
1388            Run migration utility:
1389<programlisting>cd /path_to_base/dist/bin
1390./migrate_from_1.2.sh</programlisting>
1391          </para>
1392          <para>
1393            If the migration fails during the RawBioAssaysData
1394            transfer you can restart the migration at the point of
1395            failure. Simply restart the migration and the script will
1396            ask you to verify that a restart should be attempted. For
1397            all other failure points the migration has to be restarted
1398            with an empty database.
1399          </para>
1400        </listitem>
1401
1402        <listitem>
1403          <para>
1404            <emphasis>Optional, depends on your BASE 1.2 reporter
1405            table.</emphasis> Additional columns (as compared with a
1406            pristine database schema) in the reporter table in the
1407            BASE 1.2 schema are not transferred during migration. You
1408            have to perform the transfer manually after
1409            migration. Simply export the reporter information from
1410            BASE 1.2, and import the data into BASE 2. In BASE 1.2: i)
1411            View the reporters, ii) Use `Get as tab-separated text` to
1412            create a tab separated file (right click and save). In
1413            BASE 2, to import the file follow the instructions in
1414            <xref linkend="reporters.import"/>.
1415          </para>
1416        </listitem>
1417
1418        <listitem>
1419          <para>
1420            Migration done! Happy BASEing.
1421          </para>
1422        </listitem>
1423
1424      </orderedlist>
1425
1426    </para>
1427
1428  </sect1>      <!-- Migration instructions -->
1429
1430</chapter>
Note: See TracBrowser for help on using the repository browser.