Changeset 6326


Ignore:
Timestamp:
Sep 16, 2013, 2:52:42 PM (9 years ago)
Author:
Jari Häkkinen
Message:

Reverting changes to previous revision since I commited an old copy of installation.xml

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/admin/installation.xml

    r6324 r6326  
    99  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
    1010  Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg
    11   Copyright (C) 2010, 2011, 2012 Nicklas Nordborg
    12   Copyright (C) 2013 Jari Häkkinen
    1311
    1412  This file is part of BASE - BioArray Software Environment.
     
    3735    These instructions apply only to the BASE release which this
    3836    document is a part of. The instructions here assume
    39     that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used
     37    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used
    4038    on the server side. Other servlet engines may work but we only
    4139    test with Tomcat.
     
    5149        This section list some important information that may or may not
    5250        apply when upgrading from the <emphasis>previous</emphasis> BASE
    53         release to the current release (eg. 3.1.x to 3.2.x). If you are
    54         upgrading from a BASE installation that is older (eg. 2.x or 3.0.x to
    55         3.2.x) you should also read <xref linkend="appendix.update_warnings" />.
     51        release to the current release (eg. 3.2 to 3.3). If you are
     52        upgrading from a BASE installation that is older (eg. 2.x or 3.0-3.1 to
     53        3.3) you should also read <xref linkend="appendix.update_warnings" />.
    5654      </para>
    5755     
    58       <bridgehead>Custom logging implementations must be updated</bridgehead>
     56      <bridgehead>Java SE 7 and Tomcat 7 is required</bridgehead>
    5957      <para>
    60         The plug-in functionality for custom logging has been converted
    61         to an extension point. The default database logging will continue
    62         to function, but custom logging implementations must be converted
    63         to an extension. See <xref linkend="appendix.incompatible.3.2" /> and
    64         <xref linkend="extensions_developer.logging" /> for more information.
     58        BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink>
     59        and <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>. Servers with Java SE 6 or Tomcat 6
     60        should be updated to newer versions before installing BASE 3.3.
    6561      </para>
    6662
     
    9187            If the BASE application is not shut down already, it is
    9288            time to do it now. Do something like <command>sudo
    93             /etc/init.d/tomcat6.0 stop</command>
     89            /etc/init.d/tomcat7.0 stop</command>
    9490          </para>
    9591         
     
    227223          <para>
    228224            Start the Tomcat server: <command>sudo
    229               /etc/init.d/tomcat6.0 start</command>
     225              /etc/init.d/tomcat7.0 start</command>
    230226          </para>
    231227        </listitem>
     
    249245        <listitem>
    250246          <para>
    251             Download and install Java SE 6, available from
     247            Download and install Java SE 7, available from
    252248            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
    253             You can select either the JDK or the JRE version. We have only made a few tests
    254             with BASE and Java SE 7. While it seems to be working just fine we can't make
    255             any promises or provide any support for it.
     249            You can select either the JDK or the JRE version.
     250          </para>
     251         
     252          <important>
     253            <para>
     254            As of BASE 3.3 Java SE 7 is required. BASE will no longer run on
     255            Java SE 6 or lower.
     256            </para>
     257          </important>
     258         
     259        </listitem>
     260      </varlistentry>
     261
     262      <varlistentry>
     263        <term>Tomcat</term>
     264        <listitem>
     265          <para>
     266            Download and install Apache Tomcat 7.0.30 or any later 7.x release,
     267            available from <ulink url="http://tomcat.apache.org" />.
     268          </para>
     269         
     270          <important>
     271            <para>
     272            As of BASE 3.3 Tomcat 7 is required. BASE will no longer run on
     273            Tomcat 6 or lower.
     274            </para>
     275          </important>
     276         
     277          <para>
     278            There are a few configuration options that are needed to
     279            make Tomcat work properly with BASE. The options are set in the
     280            <code>CATALINA_OPTS</code> environment variable.
     281          </para>
     282         
     283          <itemizedlist>
     284            <listitem>
     285              <para>
     286                Increase the amount of memory that Tomcat is allowed to use. The default setting is
     287                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
     288              </para>
     289            </listitem>
     290            <listitem>
     291              <para>
     292                Disable strict parsing of JSP files.
     293                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
     294              </para>
     295            </listitem>
     296            <listitem>
     297              <para>
     298                Unless you have manually downloaded and installed JAI (Java Advanced
     299                Imaging) native acceleration libraries (see <ulink
     300                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
     301                it is a good idea to disable the native acceleration of JAI.
     302                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
     303              </para>
     304            </listitem>
     305            <listitem>
     306              <para>
     307                Enable headless mode if your are setting up a server which doesn't have
     308                a display device connected to it. <code>-Djava.awt.headless=true</code>.
     309              </para>
     310            </listitem>
     311         
     312          </itemizedlist>
     313         
     314          <para>
     315            Depending on your system there are probably several ways to set the
     316            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
     317            line (as a single line) close to the top of the <filename>catalina.sh</filename>
     318            script that comes with Tomcat (directory <filename
     319            class="directory">bin</filename>):
     320<programlisting>CATALINA_OPTS="-Xmx1G
     321-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
     322-Dcom.sun.media.jai.disableMediaLib=true
     323-Djava.awt.headless=true"</programlisting>
     324          </para>
     325          <para>
     326            For more information about Tomcat options see
     327            <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />.
    256328          </para>
    257329        </listitem>
     
    263335          <para>
    264336            BASE
    265             utilise <ulink
     337            utilize <ulink
    266338            url="http://www.hibernate.org/">Hibernate</ulink> for
    267339            object persistence to a relational database. Hibernate
     
    311383      </varlistentry>
    312384
     385      <varlistentry>
     386        <term>BASE (download and unpacking)</term>
     387        <listitem>
     388          <para>
     389            <ulink
     390            url="http://base.thep.lu.se/wiki/DownloadPage">Download
     391            BASE</ulink> and unpack the downloaded file,
     392            i.e. <command>tar zxpf base-...tar.gz</command>. If you
     393            prefer to have the bleeding edge version of BASE, perform
     394            a checkout of the source from the subversion repository
     395            (subversion checkout instructions at
     396            <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
     397            trac site</ulink>).
     398          </para>
     399          <para>
     400            If you choose to download the binary package, skip to the
     401            next item. The rest of us, read on and compile BASE. If
     402            you downloaded a source distribution, unpack the
     403            downloaded file <command>tar zxpf
     404            base-...src.tar.gz</command>, or you may have performed a
     405            subversion checkout.  Change to the 'root' base2
     406            directory, and issue <command>ant
     407            package.bin</command>. This will create a binary package
     408            in the base2 'root' directory. Unpack this new package
     409            (outside of the source file hierarchy), and from now on
     410            the instructions are the same irrespective where you got
     411            the binary package.
     412          </para>
     413          <para>
     414            <emphasis>This section is intended for advanced users and
     415              programmers only. In cases when you want to change the
     416              BASE code and try out personalized features it may be
     417              advantageous to run the tweaked BASE server against the
     418              development tree. Instructions on how to accomplish this
     419              is available in the
     420              <ulink
     421              url="http://base.thep.lu.se/wiki/BuildingBase">building
     422              BASE document</ulink>. When you return back after
     423              compiling in the subversion tree you can follow the
     424              instruction here (with obvious changes to
     425              paths).</emphasis>
     426          </para>
     427        </listitem>
     428      </varlistentry>
     429
    313430      <varlistentry id="installation.main.database">
    314431        <term>BASE (database engine)</term>
    315432        <listitem>
    316433          <para>
    317             The database names (base2 and base2dynamic are used here),
    318             the <emphasis>db_user</emphasis>, and the
    319             <emphasis>db_password</emphasis> can be changed during the
    320             creation of the databases. It is recommended to change the
    321             <emphasis>db_password</emphasis>, the other changes are
    322             optional and can be made if desired. The database names,
    323             the <emphasis>db_user</emphasis>, and the
    324             <emphasis>db_password</emphasis> are needed below when
    325             configuring BASE.
     434            Instructions for MySQL and PostgreSQL are available
     435            below. The database names (base2 and base2dynamic is used
     436            here), the <emphasis>db_user</emphasis>, and
     437            the <emphasis>db_password</emphasis> can be changed during
     438            the creation of the databases. It is recommended to change
     439            the <emphasis>db_password</emphasis>, the other changes
     440            can be made if desired. The database names,
     441            the <emphasis>db_user</emphasis>, and
     442            the <emphasis>db_password</emphasis> are needed in a later
     443            step below when configuring BASE.
    326444          </para>
    327445          <note>
    328             Note that the <emphasis>db_user</emphasis> name and
    329             <emphasis>db_password</emphasis> set here is used
     446            Note that the <emphasis>db_user</emphasis> name
     447            and <emphasis>db_password</emphasis> set here is used
    330448            internally by BASE in communication with the database and
    331449            is never used to log on to the BASE application.
     
    335453            <para>
    336454              Otherwise there will be a problem with storing values
    337               that uses characters outside the normal Latin1 range,
    338               for example unit-related such as µ (micro) and Ω (ohm).
     455              that uses characters outside the normal Latin1 range, for
     456              example unit-related such as µ (micro) and Ω (ohm).
    339457            </para>
    340458          </important>
     
    359477                </para>             
    360478                <para>
    361                   If you download BASE (instructions below) you find a file
    362                   <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
    363                   that contains the above statements and can be used
     479                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.mysql.sql</filename>
     480                  file contains the above statements and can be used
    364481                  by the <filename>mysql</filename> command-line tool
    365                   (remember to edit the <emphasis>db_user</emphasis>,
    366                   <emphasis>db_password</emphasis>, and the database
    367                   names in the script file before executing the
    368                   command): <command>mysql -uroot -p &lt;
    369                   &lt;base-dir&gt;/misc/sql/createdb.mysql.sql</command>. The
     482                  (remember to edit
     483                  the <emphasis>db_user</emphasis>,
     484                  <emphasis>db_password</emphasis>,
     485                  and the database names in the script file before
     486                  executing the command): <command>mysql -uroot -p
     487                  &lt; ./misc/sql/createdb.mysql.sql</command>. The
    370488                  header in the script file contains further
    371489                  information about the script.
     
    389507  # within the tool and quit with a '\q'.
    390508CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
    391 
    392                   If you download BASE (instructions below) you find a file
    393                   <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
    394                   that contains the above statements and can be used
     509                  The <filename>&lt;base-dir&gt;/misc/sql/createdb.postgresql.sql</filename>
     510                  file contains the above statements and can be used
    395511                  by the <filename>psql</filename> command-line tool:
    396                   <command>psql -f
    397                   &lt;base-dir&gt;/misc/sql/createdb.posgres.sql
    398                   template1</command> The header in the script file
     512                  <command>psql -f ./misc/sql/createdb.posgres.sql
     513                    template1</command> The header in the script file
    399514                  contains further information about the script.
    400515                </para>
     
    406521
    407522      <varlistentry>
    408         <term>BASE (download and unpacking)</term>
    409         <listitem>
    410           <para>
    411             <ulink
    412             url="http://base.thep.lu.se/wiki/DownloadPage">Download
    413             BASE</ulink> and unpack the downloaded file,
    414             i.e. <command>tar zxpf base-...tar.gz</command>. If you
    415             prefer to have the bleeding edge version of BASE, perform
    416             a checkout of the source from the subversion repository
    417             (subversion checkout instructions at
    418             <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
    419             trac site</ulink>).
    420           </para>
    421           <para>
    422             If you choose to download the binary package, skip to the
    423             next item. The rest of us, read on and compile BASE. If
    424             you downloaded a source distribution, unpack the
    425             downloaded file <command>tar zxpf
    426             base-...src.tar.gz</command>, or you may have performed a
    427             subversion checkout.  Change to the 'root' base2
    428             directory, and issue <command>ant
    429             package.bin</command>. This will create a binary package
    430             in the base2 'root' directory. Unpack this new package
    431             (outside of the source file hierarchy), and from now on
    432             the instructions are the same irrespective where you got
    433             the binary package.
    434           </para>
    435           <para>
    436             <emphasis>This section is intended for advanced users and
    437               programmers only. In cases when you want to change the
    438               BASE code and try out personalised features it may be
    439               advantageous to run the tweaked BASE server against the
    440               development tree. Instructions on how to accomplish this
    441               is available in the
    442               <ulink
    443               url="http://base.thep.lu.se/wiki/BuildingBase">building
    444               BASE document</ulink>. When you return back after
    445               compiling in the subversion tree you can follow the
    446               instruction here (with obvious changes to
    447               paths).</emphasis>
    448           </para>
    449         </listitem>
    450       </varlistentry>
    451 
    452       <varlistentry>
    453523        <term>BASE (file storage setup)</term>
    454524        <listitem>
    455525          <para>
    456526            An area for file storage must be setup. Create an empty
    457             directory in a proper location in your file system. Set
    458             the owner of the created directory to the user the Tomcat
    459             server will be running as. Tomcat server set up
    460             instructions will follow below. Remember this location for
     527            directory in a proper location in your file system, and
     528            set the owner to be the same as the one that the Tomcat
     529            server will be running as. Remember this location for
    461530            later use. The default location is <filename>/usr/local/base2/files</filename>.
    462531          </para>
     
    471540            Create an empty directory in a proper location in your file system,
    472541            and make sure that the user that the Tomcat
    473             server will be running as has read permission in this
    474             directory. Tomcat server set up instructions will follow
    475             below. Remember this location for
     542            server will be running as has read permission. Remember this location for
    476543            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
    477544          </para>
     
    532599
    533600      <varlistentry>
    534         <term>BASE (database initialisation)</term>
     601        <term>BASE (database initialization)</term>
    535602        <listitem>
    536603          <para>
     
    539606            and execute the following commands:
    540607        <programlisting>
    541 sudo ./initdb.sh [base_root_login] base_root_password
     608./initdb.sh [base_root_login] base_root_password
    542609./updateindexes.sh
    543610</programlisting>
    544           </para>
    545 
    546           <para>
    547             In the first command sudo is required because a file will
    548             be created in the directory defined by
    549             <emphasis>userfiles</emphasis> above. If the directory is
    550             writable by you then sudo is not needed.
    551           </para>
    552 
    553           <para>
    554             The second command is important for PostgreSQL users since
    555             the Hibernate database initialisation utility is not able
    556             to create all required indexes. BASE will work without the
    557             indexes but performance is impaired. Running the script as
    558             a MySQL user does not have a negative impact.
    559           </para>
     611
     612            The second command is important for PostgreSQL users
     613            since the Hibernate database initialisation utility
     614            is not able to create all indexes that are required.
     615            BASE will still work without the indexes but performance
     616            may suffer.
    560617
    561618            <important>
     
    569626            </para>
    570627            </important>
    571 
    572           <para>
    573             If the initialisation script fail, it is probably a
     628            If the initialisation script fail, it is most probably a
    574629            problem related to the underlying database. Make sure that
    575630            the database accepts network connection and make sure that
    576             <emphasis>db_user</emphasis> has proper credentials. You
    577             may also get a <emphasis>Permission denied</emphasis> on
    578             file <filename>extension-settings.xml</filename> if you do
    579             not have write permission to the directory defined by
    580             variable <emphasis>userfiles</emphasis> in file
    581             <filename>base.config</filename>. If the initialisation
    582             fails on <filename>extension-settings.xml</filename> you
    583             must drop the database and recreate the database as
    584             described in <xref linkend="installation.main.database"/>.
    585           </para>
    586         </listitem>
    587       </varlistentry>
    588 
    589       <varlistentry>
    590         <term>Tomcat</term>
    591         <listitem>
    592           <para>
    593             Download and install Apache Tomcat 6.0.20 or any later 6.x release,
    594             available from <ulink url="http://tomcat.apache.org" />. We have only
    595             made a few tests with BASE and Tomcat 7. While it seems to be working
    596             fine (except for the XJSP compiler) we can't make any promises or
    597             provide support for it.
    598             There are a few configuration options that are needed to
    599             make Tomcat work properly with BASE. The options are set in the
    600             <code>CATALINA_OPTS</code> environment variable.
    601           </para>
    602          
    603           <itemizedlist>
    604             <listitem>
    605               <para>
    606                 Increase the amount of memory that Tomcat is allowed to use. The default setting is
    607                 usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
    608               </para>
    609             </listitem>
    610             <listitem>
    611               <para>
    612                 Disable strict parsing of JSP files.
    613                 <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
    614               </para>
    615             </listitem>
    616             <listitem>
    617               <para>
    618                 Unless you have manually downloaded and installed JAI (Java Advanced
    619                 Imaging) native acceleration libraries (see <ulink
    620                 url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
    621                 it is a good idea to disable the native acceleration of JAI.
    622                 <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
    623               </para>
    624             </listitem>
    625             <listitem>
    626               <para>
    627                 Enable headless mode if your are setting up a server which doesn't have
    628                 a display device connected to it. <code>-Djava.awt.headless=true</code>.
    629               </para>
    630             </listitem>
    631           </itemizedlist>
    632          
    633           <para>
    634             Depending on your system there are probably several ways to set the
    635             the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
    636             line (as a single line) close to the top of the <filename>catalina.sh</filename>
    637             script that comes with Tomcat (directory <filename
    638             class="directory">bin</filename>):
    639 <programlisting>CATALINA_OPTS="-Xmx1G
    640 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
    641 -Dcom.sun.media.jai.disableMediaLib=true
    642 -Djava.awt.headless=true"</programlisting>
    643           </para>
    644           <para>
    645             For more information about Tomcat options see
    646             <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/index.html" />.
     631            <emphasis>db_user</emphasis> has proper credentials.
    647632          </para>
    648633        </listitem>
     
    653638        <listitem>
    654639          <para>
    655             Do the following:
    656             <itemizedlist>
    657               <listitem>
    658                 <para>
    659                   Either move the <filename
    660                   class="directory">&lt;base-dir&gt;/www</filename>
    661                   directory to the Tomcat <filename
    662                   class="directory">webapps</filename> directory or
    663                   create a symbolic link from the Tomcat <filename
    664                   class="directory">webapps</filename> directory to
    665                   the <filename
    666                   class="directory">&lt;base-dir&gt;/www</filename>
    667                   directory
     640            Either move the <filename
     641            class="directory">&lt;base-dir&gt;/www</filename> directory
     642            to the Tomcat <filename class="directory">webapps</filename>
     643            directory or create a symbolic link from the Tomcat
     644            <filename class="directory">webapps</filename> directory to
     645            the <filename class="directory">&lt;base-dir&gt;/www</filename>
     646            directory
    668647<programlisting>cd /path/to/tomcat/webapps
    669648ln -s /path_to_base/www base2</programlisting>
    670                 </para>
    671               </listitem>
    672               <listitem>
    673                 <para>
    674                   Make sure that user Tomcat is running as can read
    675                   all objects in the directory defined by
    676                   <emphasis>plugins.dir</emphasis> in file
    677                   <filename>base.config</filename>.
    678                 </para>
    679               </listitem>
    680               <listitem>
    681                 <para>
    682                   Make sure that user Tomcat is running as owns (i.e.,
    683                   can read, write, delete and create) all objects in
    684                   the directory, as well as the directory itself,
    685                   defined by <emphasis>userfiles</emphasis> in file
    686                   <filename>base.config</filename>.
    687                 </para>
    688               </listitem>
    689               <listitem>
    690                 <para>
    691                   If you plan to install extensions you should make
    692                   sure that the <filename
    693                   class="directory">&lt;base-dir&gt;/www/extensions</filename>
    694                   directory is writable by the user account Tomcat is
    695                   running as.
    696                 </para>
    697               </listitem>
    698             </itemizedlist>
    699           </para>
    700           <para>
    701             and finalise with start, or restart, Tomcat, and try
    702             http://hostname:8080/base2 (change
    703             <emphasis>hostname</emphasis> to your hostname and
    704             <emphasis>base2</emphasis> if you selected another name
    705             for the BASE Tomcat application) in your favourite
    706             browser. The BASE log-in page should appear after a few
    707             seconds.
     649          </para>
     650          <para>
     651            If you plan to install extensions you should make sure that
     652            the <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
     653            directory is writable by the user account Tomcat is running as.
     654          </para>
     655          <para>
     656            Start/restart Tomcat, and try http://hostname:8080/base2
     657            (change <emphasis>hostname</emphasis> to your hostname) in
     658            your favourite browser. The BASE log-in page should appear
     659            after a few seconds.
    708660          </para>
    709661        </listitem>
     
    735687            user <emphasis>root</emphasis> (use
    736688            the <emphasis>base_root_password</emphasis> from the
    737             database initialisation step above). You should begin with
     689            database initialization step above). You should begin with
    738690            creating a couple user accounts, for more information on
    739691            how to create user accounts please refer to
     
    772724      are optional and must be installed and setup
    773725      separately. However, BASE is prepared for job agent setup and to
    774       utilise the agents, but the agent are not required.
     726      utilize the agents, but the agent are not required.
    775727    </para>
    776728
     
    10711023          agents</guilabel> tab. To do the same from the job agent pages,
    10721024          go to the edit view of the job agent and select
    1073           the <guilabel>Plugins</guilabel> tab. The registration dialogues
     1025          the <guilabel>Plugins</guilabel> tab. The registration dialogs
    10741026          are very similar but only the plug-in side of registration is
    10751027          described here. The major difference is that it is not possible
     
    14811433      It is possible to migrate a BASE installation on a MySQL database to a
    14821434      PostgreSQL database. In a real-world scenario a migration is probably coupled
    1483       with a hardware upgrade, i.e. the MySQL installation is on one (the old) server
     1435      with a hardware upgrade, ie. the MySQL installation is on one (the old) server
    14841436      and the PostgreSQL installation is on another (the new) server. While
    14851437      this is not any problem per se, it requires a few extra steps to ensure that
     
    16001552              directories.
    16011553              The import program protects against some mistakes by comparing
    1602               the column names from the export with the column names in the new
     1554              the colum names from the export with the column names in the new
    16031555              database, but it will, for example, not check that data types match.
    16041556              </para>
Note: See TracChangeset for help on using the changeset viewer.