Changeset 5737


Ignore:
Timestamp:
Sep 14, 2011, 2:36:05 PM (10 years ago)
Author:
Nicklas Nordborg
Message:

References #1590: Documentation cleanup

Updated Admin documentation:

  • Installation and updgrade instructions
  • Plug-ins and extensions

A lot of information has been moved around/merged with other parts. Screen shots are the old ones, which can be a bit confusing since the differences are big.

Location:
trunk
Files:
3 deleted
9 edited
4 moved

Legend:

Unmodified
Added
Removed

  • trunk/build.xml

    r5718 r5737  
    12891289    <mkdir dir="${docbook.html.out}/admindoc/user_administration"/>
    12901290    <mkdir dir="${docbook.html.out}/admindoc/installation_upgrade"/>
    1291     <mkdir dir="${docbook.html.out}/admindoc/plugin_installation"/>
     1291    <mkdir dir="${docbook.html.out}/admindoc/plugins"/>
    12921292    <mkdir dir="${docbook.html.out}/admindoc/extensions"/>
    12931293    <mkdir dir="${docbook.html.out}/admindoc/coreplugin_configuration"/>

  • trunk/doc/src/docbook/admindoc/index.xml

    r4889 r5737  
    2828  <title>Admin documentation</title>
    2929  <include file="installation_upgrade.xml"/>
    30   <include file="plugin_installation.xml"/>
    31   <include file="extensions.xml" />
     30  <include file="plugins.xml"/>
    3231  <include file="user_administration.xml"/>
    3332</part>

  • trunk/doc/src/docbook/admindoc/installation_upgrade.xml

    r5367 r5737  
    3030  <?dbhtml dir="installation_upgrade"?>
    3131
    32   <title>Installation, setup, migration, and upgrade instructions</title>
     32  <title>Installation and upgrade instructions</title>
    3333
    3434  <note>
     35    <para>
    3536    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 three parts. First, the process of
    41     upgrading a BASE 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. The first time installation is only to be performed once.
    45   </para>
    46 
    47   <para>
    48     The instructions here assume
     37    document is a part of. The instructions here assume
    4938    that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used
    5039    on the server side. Other servlet engines may work but we only
    5140    test with Tomcat.
    52   </para>
    53 
     41    </para>
     42  </note>
    5443
    5544  <sect1 id="installation_upgrade.upgrade">
    … …  
    5746
    5847    <important id="installation_upgrade.upgrade.important">
    59       <title>Important information for upgrading to the current release</title>
     48      <title>Important information for upgrading from BASE 2.17 to BASE 3.0-alfa</title>
     49     
     50      <bridgehead>Do not use on a production server!</bridgehead>
    6051      <para>
    61         This section list some important information that may or may not
    62         apply when upgrading from the <emphasis>previous</emphasis> BASE
    63         release to the current release (eg. 2.8.x to 2.9.x). If you are
    64         upgrading from a BASE installation that is older (eg. 2.7.x to 2.9.x)
    65         you should also read <xref linkend="appendix.update_warnings" />.
     52        The update has not been tested enough to consider this a safe option.
     53        The update may cause loss of data. Even if the update works, it is not
     54        certain that the 3.0-alfa version can be updated to the 3.0-final
     55        version. Before updating make sure that you have a backup of your
     56        BASE 2.17 database.
    6657      </para>
    67    
    68       <bridgehead>BASE 2.9 must use a database that supports UTF-8</bridgehead>
     58
     59      <bridgehead>Updating is supported from BASE 2.17 only</bridgehead>
    6960      <para>
    70         If you are upgrading from BASE 2.8 or lower and your existing
    71         database is not using UTF-8 you must convert the database to
    72         UTF-8 <emphasis>before you execute the <code>./updatedb.sh</code></emphasis>
    73         script.
     61        If your BASE is an older version you'll first need to update
     62        to BASE 2.17.
    7463      </para>
     64
     65      <bridgehead>Old plug-ins and extensions may not work</bridgehead>
    7566      <para>
    76         BASE 2.9 includes a utility that can convert an existing MySQL
    77         database. After installing the BASE 2.9 files, but <emphasis>before</emphasis>
    78         running the <code>./updatedb.sh</code> script, execute the following
    79         on the command line:
     67        The BASE API has changed in several places and it is not certain that
     68        plug-ins and extensions developed for BASE 2 works with BASE 3. The
     69        update will disable all plug-ins and extensions that are currently installed.
     70        Before you update we recommend that you go through all (external) plug-ins
     71        and check if there is an updated version. The recommended approach
     72        is to first update BASE and then install updated versions of plug-ins
     73        and extensions following the instructions in <xref
     74        linkend="plugins.installation"/>.
    8075      </para>
    81       <programlisting>
    82 <![CDATA[
    83 cd <base-dir>/bin
    84 ./onetimefix.sh utf8 -x
    85 ]]>
    86 </programlisting>
    87    
     76     
    8877      <para>
    89         The <code>-x</code> option makes the script update the database immediately.
    90         You can leave this option out to have it generate a SQL script file
    91         (<filename>convert-to-utf8.sql</filename>) instead. The script will by default
    92         not try to convert tables that it already thinks are using UTF-8. If the script
    93         for some reason is incorrect when detecting this, you can use the option
    94         <code>-f</code> to force conversion of all tables.
     78        If there is no updated version of a specific plug-in you may try
     79        a manual re-installation of the old plug-ins. Follow the instructions
     80        in <xref linkend="plugins.installation.manual" />.
    9581      </para>
    96 
     82     
     83      <bridgehead>Batch item importer changes</bridgehead>
    9784      <para>
    98         The conversion utility only works with MySQL. PostgreSQL users should
    99         instead use a backup and restore using as described in the
    100         <ulink url="http://www.postgresql.org/docs/8.1/static/backup.html">PostgreSQL manual</ulink>.
    101         Eg. dump the existing BASE database, create a new database that uses UTF8 and
    102         restore the backup into the new database.
     85        There are several changes to batch item importers that may affect
     86        current workflows and file templates used for importing data.
    10387      </para>
    104 
     88     
     89      <itemizedlist>
     90        <listitem>
     91          <para>
     92            Sample and extract importer: The 'pooled' column is no longer used.
     93            Instead a 'parent type' column should be used which should contain
     94            the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT).
     95            Existing importer configurations and file templates may have to be updated.
     96          </para>
     97        </listitem>
     98        <listitem>
     99          <para>
     100            Labeled extract importer: This has been deprecated and it is recommended
     101            that the Extract importer is used instead. Existing importer configurations
     102            should be re-created as extract importer configurations.
     103          </para>
     104        </listitem>
     105        <listitem>
     106          <para>
     107            Hybridization importer: This has been deprecated and it is recommended
     108            that the Physical bioassay importer is used instead. Existing importer configurations
     109            should be re-created as physical bioassay importer configurations.
     110          </para>
     111        </listitem>
     112        <listitem>
     113          <para>
     114            Scan importer: This has been deprecated and it is recommended
     115            that the Derived bioassay importer is used instead. Existing importer configurations
     116            should be re-created as derived bioassay importer configurations.
     117          </para>
     118        </listitem>
     119      </itemizedlist>
     120     
     121      <note>
     122        The deprecated importers can be re-enabled by an administrator, but they are
     123        lacking features that are available in the new importers so this is not
     124        something that we recommend.
     125      </note>
     126     
    105127    </important>
    106128   
    … …  
    196218                  This option is for advanced users only and is not
    197219                  covered here. Please refer to
    198                   <xref linkend="core_ref.build"/> for information on
     220                  <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on
    199221                  this download option.
    200222                </para>
    … …  
    261283
    262284      <varlistentry>
    263         <term>Remove Tomcat cache</term>
    264         <listitem>
    265           <para>
    266             As Tomcat user, remove cached files and directories. Do
    267             something like
    268 <programlisting>cd /usr/share/apache-tomcat-6.0/
    269 rm -rf work/Catalina</programlisting>
    270           </para>
    271         </listitem>
    272       </varlistentry>
    273 
    274       <varlistentry>
    275285        <term>Start Tomcat</term>
    276286        <listitem>
    … …  
    290300  </sect1>      <!-- Upgrade instructions -->
    291301
    292 
    293   <sect1 id="installation_upgrade.jobagents">
    294     <title>Installing job agents</title>
    295 
    296     <para>
    297       It is important to understand that the BASE application can be
    298       spread on to several computers. The main BASE application is
    299       serving HTTP requests, the underlying database engine is
    300       providing storage and persistence of data, and job agents can be
    301       installed on computers that will serve the BASE installation
    302       with computing power and perform analysis and run plug-in. In a
    303       straight forward setup one computer provides all services needed
    304       for running BASE. From this starting point it is easy to add
    305       computers to shares load from the BASE server by installing job
    306       agents on these additional computers.
    307     </para>
    308 
    309     <para>
    310       A job agent is a program running on a computer regularly
    311       checking the BASE job queue for jobs awaiting execution. When
    312       the job agent finds a job that it is enabled to execute, it
    313       loads the plug-in and executes it. Job agents will in this way
    314       free up resources on the BASE application server, and thus allow
    315       the BASE server to concentrate on serving web pages. Job agents
    316       are optional and must be installed and setup
    317       separately. However, BASE is prepared for job agent setup and to
    318       utilize the agents, but the agent are not required.
    319     </para>
    320 
    321     <para>
    322       A job agent supports many configuration options that are not
    323       supported by the internal job queue. For example, you can
    324       <itemizedlist>
    325         <listitem>
    326           <para>
    327             Specify exactly which plug-ins each job agent should be
    328             able to execute.
    329           </para>
    330         </listitem>
    331         <listitem>
    332           <para>
    333             Give some plug-ins higher priority than other plug-ins.
    334           </para>
    335         </listitem>
    336         <listitem>
    337           <para>
    338             Specify which users/groups/projects should be able to use
    339             a specific job agent.
    340           </para>
    341         </listitem>
    342         <listitem>
    343           <para>
    344             Override memory settings and more for each plug-in.
    345           </para>
    346         </listitem>
    347         <listitem>
    348           <para>
    349             Execute plug-ins in separate processes. Thus, a misbehaving
    350             plug-in cannot bring the main application server down.
    351           </para>
    352         </listitem>
    353         <listitem>
    354           <para>
    355             Add more computers with job agents as needed.
    356           </para>
    357         </listitem>
    358       </itemizedlist>
    359       All these options make it possible to create a very flexible
    360       setup. For example one job agent can be assigned for importing
    361       data only, another job agent can be assigned for running
    362       analysis plug-ins for specific project only, and a third may be a
    363       catch-all job agent that performs all low-priority jobs.
    364     </para>
    365 
    366     <sect2 id="installation_upgrade.jobagents.serverside">
    367       <title>BASE application server side setup</title>
    368       <para>
    369         <variablelist>
    370           <varlistentry>
    371             <term>Make sure the internal job queue doesn't execute all plug-ins</term>
     302  <sect1 id="installation_upgrade.installation">
     303    <title>Installation instructions</title>
     304
     305    <variablelist>
     306
     307      <varlistentry>
     308        <term>Java</term>
     309        <listitem>
     310          <para>
     311            Download and install Java SE 6, available from
     312            <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />.
     313            You can select either the JDK or the JRE version. We have not yet tested BASE with
     314            Java SE 7 so we can't tell if it works or not.
     315          </para>
     316        </listitem>
     317      </varlistentry>
     318
     319      <varlistentry>
     320        <term>Tomcat</term>
     321        <listitem>
     322          <para>
     323            Download and install Apache Tomcat 6.0.20 or any later 6.x release,
     324            available from <ulink
     325            url="http://tomcat.apache.org" />. We have not yet tested BASE
     326            with Tomcat 7 so we can't tell if it works or not.
     327            There are a few configuration options that are needed to
     328            make Tomcat work properly with BASE. The options are set in the
     329            <code>CATALINA_OPTS</code> environment variable.
     330          </para>
     331         
     332          <itemizedlist>
    372333            <listitem>
    373334              <para>
    374                 The setting <command>jobqueue.internal.runallplugins</command>
    375                 should be set to <command>false</command> for the
    376                 BASE server. This setting is found in
    377                 the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
    378                 file. The changes will not take effect until the
    379                 application server is restarted.
     335                Increase the amount of memory that Tomcat is allowed to use. The default setting is
     336                usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>.
    380337              </para>
    381              
    382               <note>
    383                 Prior to BASE 2.5 the internal job queue had to be disabled
    384                 completely. This is no longer the case since it is possible to
    385                 enable/disable the internal job queue separately for
    386                 each plug-in.
    387               </note>
    388              
    389338            </listitem>
    390           </varlistentry>
    391           <varlistentry id="installation_upgrade.jobagent.user_account">
    392             <term>Enable the job agent user account</term>
    393339            <listitem>
    394340              <para>
    395                 During installation of BASE a user account is created
    396                 for the job agent. This account is used by the job
    397                 agents to log on to BASE. The account is disabled by
    398                 default and must be enabled. Enable the account and
    399                 set a password using the BASE web interface.
    400                 The same password must also be set in the
    401                 <filename>jobagent.properties</filename> file, see
    402                 item
    403                 <xref linkend="installation_upgrade.jobagent.client.properties"/>
    404                 below.
     341                Disable strict parsing of JSP files.
     342                <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code>
    405343              </para>
    406344            </listitem>
    407           </varlistentry>
    408         </variablelist>
    409       </para>
    410     </sect2>
    411 
    412     <sect2 id="installation_upgrade.jobagents.database">
    413       <title>Database server setup</title>
    414       <para>
    415         <variablelist>
    416           <varlistentry id="installation_upgrade.jobagent.database">
    417             <term>Create a user account on the database</term>
    418345            <listitem>
    419346              <para>
    420                 This is the similar to granting database access for
    421                 the BASE server user in the in the regular BASE
    422                 installation, cf.
    423                 <xref
    424                 linkend="installation_upgrade.installation.database"/>.
    425                 You must create an account in the database that is
    426                 allowed to connect from the job agent server. MySQL
    427                 example:
    428 <programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
    429 GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
    430 
    431                 Replace <command>job.agent.host</command> with the
    432                 host name of the server that is going to run the job
    433                 agent. You should also set password. This password is
    434                 used in item
    435                 <xref linkend="installation_upgrade.jobagent.client.config"/>
    436                 below in job agent server setup. You can use the same
    437                 database user and password as in the regular database
    438                 setup.
     347                Unless you have manually downloaded and installed JAI (Java Advanced
     348                Imaging) native acceleration libraries (see <ulink
     349                url="http://java.sun.com/javase/technologies/desktop/media/jai/" />)
     350                it is a good idea to disable the native acceleration of JAI.
     351                <code>-Dcom.sun.media.jai.disableMediaLib=true</code>
    439352              </para>
    440353            </listitem>
    441           </varlistentry>
    442         </variablelist>
    443       </para>
    444     </sect2>
    445 
    446     <sect2 id="installation_upgrade.jobagents.client">
    447       <title>Job agent client setup</title>
    448       <para>
    449         <variablelist>
    450           <varlistentry>
    451             <term>Download and unpack a regular BASE distribution</term>
    452354            <listitem>
    453355              <para>
    454                 You <emphasis>must</emphasis> use the same version on
    455                 the web server and all job agents. You find the
    456                 downloads at
    457                 <ulink
    458                 url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
     356                Enable headless mode if your are setting up a server which doesn't have
     357                a display device connected to is. <code>-Djava.awt.headless=true</code>.
    459358              </para>
    460359            </listitem>
    461           </varlistentry>
    462           <varlistentry id="installation_upgrade.jobagent.client.config">
    463             <term>Edit the <filename>base.config</filename> file</term>
    464             <listitem>
    465               <para>
    466                 The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
    467                 file must be configured as in regular BASE
    468                 installation, cf.
    469                 <xref
    470                 linkend="installation_upgrade.installation.configuration"/>,
    471                 to use the same database as the web server
    472                 application. The most important settings are
    473                 <itemizedlist>
    474                   <listitem>
    475                     <para>
    476                       <command>db.username</command>: The database
    477                       user you created in item
    478                       <xref
    479                       linkend="installation_upgrade.jobagent.database"/>
    480                       above.
    481                     </para>
    482                   </listitem>
    483                   <listitem>
    484                     <para>
    485                       <command>db.password</command>: The password for
    486                       the user.
    487                     </para>
    488                   </listitem>
    489                   <listitem>
    490                     <para>
    491                       <command>db.url</command>: The connection url to
    492                       the database.
    493                     </para>
    494                   </listitem>
    495                   <listitem>
    496                     <para>
    497                       <command>userfiles</command>: The path to the
    498                       directory where user files are located. This
    499                       directory must be accessible from all job
    500                       agents, i.e., by nfs or other file system
    501                       sharing method.
    502                     </para>
    503                   </listitem>
    504                 </itemizedlist>
    505                 See the <xref linkend="appendix.base.config"/> for
    506                 more information about the settings in
    507                 the <filename>base.config</filename> file.
    508               </para>
    509             </listitem>
    510           </varlistentry>
    511           <varlistentry id="installation_upgrade.jobagent.client.properties">
    512             <term>Edit
    513             the <filename>jobagent.properties</filename> file</term>
    514             <listitem>
    515               <para>
    516                 The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
    517                 file contains settings for the job agent. The most
    518                 important ones to specify value for are
    519                 <itemizedlist>
    520                   <listitem>
    521                     <para>
    522                       <command>agent.password</command>: The password
    523                       you set for the job agent user account in item
    524                       <xref
    525                       linkend="installation_upgrade.jobagent.user_account"/>
    526                       above.
    527                     </para>
    528                   </listitem>
    529                   <listitem>
    530                     <para>
    531                       <command>agent.id</command>: An ID that must be
    532                       unique for each job agent accessing the BASE application.
    533                     </para>
    534                   </listitem>
    535                   <listitem>
    536                     <para>
    537                       <command>agent.remotecontrol</command>: The
    538                       name/ip address of the web server if you want it
    539                       to be able to display info about running
    540                       jobs. The job agent will only allow connections
    541                       from computers specified in this setting.
    542                     </para>
    543                   </listitem>
    544                 </itemizedlist>
    545               </para>
    546               <para>
    547                 The <filename>jobagent.properties</filename> file
    548                 contains many more configuration options. See
    549                 the <xref linkend="appendix.jobagent.properties"/> for
    550                 more information.
    551               </para>
    552             </listitem>
    553           </varlistentry>
    554           <varlistentry>
    555             <term>Register the job agent</term>
    556             <listitem>
    557               <para>
    558                 From the <filename>bin</filename> directory, register
    559                 the job agent with
    560                 <programlisting>./jobagent.sh register</programlisting>
    561               </para>
    562             </listitem>
    563           </varlistentry>
    564           <varlistentry>
    565             <term>Start the job agent</term>
    566             <listitem>
    567               <para>
    568                 From the <filename>bin</filename> directory, start the
    569                 job agent with
    570                 <programlisting>./jobagent.sh start &amp;</programlisting>
    571               </para>
    572               <para>
    573                 See the <xref linkend="appendix.jobagent.sh"/>
    574                 for more information about what you can do
    575                 with the job agent command line interface.
    576               </para>
    577             </listitem>
    578           </varlistentry>
    579         </variablelist>
    580       </para>
    581     </sect2>
    582 
    583     <sect2 id="installation_upgrade.jobagents.configuration">
    584       <title>Configuring the job agent</title>
    585       <para>
    586         Before the job agent starts executing jobs for you it must be
    587         configured. The configuration is done through the BASE web
    588         interface. See <xref linkend="plugins.jobagents" />
    589         <variablelist>
    590           <varlistentry>
    591             <term>Configure the plug-ins the job agent should handle</term>
    592             <listitem>
    593               <para>
    594                 <itemizedlist>
    595                   <listitem>
    596                     <para>
    597                       Go to the
    598                       <menuchoice>
    599                         <guimenu>Administrate</guimenu>
    600                         <guisubmenu>Plugins</guisubmenu>
    601                         <guimenuitem>Job agents</guimenuitem>
    602                       </menuchoice> menu.
    603                     </para>
    604                   </listitem>
    605                   <listitem>
    606                     <para>
    607                       Select the job agent and click on the &gbEdit;
    608                       button.
    609                     </para>
    610                   </listitem>
    611                   <listitem>
    612                     <para>
    613                       On the <guilabel>Plugins</guilabel> tab you can
    614                       specify which plug-ins the job agent should
    615                       handle. Note that if you have installed external
    616                       plug-ins on the web server, those plug-ins must be
    617                       installed on the job agent as well. It is
    618                       possible to specify different paths to the JAR
    619                       file for each job agent.
    620                     </para>
    621                   </listitem>
    622                 </itemizedlist>
    623               </para>
    624             </listitem>
    625           </varlistentry>
    626           <varlistentry>
    627             <term>Grant users access to the job agent</term>
    628             <listitem>
    629               <para>
    630                 Use the regular <guilabel>Share</guilabel>
    631                 functionality to specify which users/groups/projects
    632                 should be able to use the job agent. You must give
    633                 them at least <command>USE</command> permission.
    634               </para>
    635             </listitem>
    636           </varlistentry>
    637         </variablelist>
    638       </para>
    639     </sect2>
    640 
    641   </sect1>      <!-- job agent setup -->
    642 
    643 
    644   <sect1 id="installation_upgrade.installation">
    645     <title>Installation instructions</title>
    646 
    647     <variablelist>
    648 
    649       <varlistentry>
    650         <term>Java</term>
    651         <listitem>
    652           <para>
    653             Download and install Java SDK 1.6 (aka Java 6), available from
    654             <ulink url="http://java.sun.com/" />.
    655           </para>
    656         </listitem>
    657       </varlistentry>
    658 
    659       <varlistentry>
    660         <term>Tomcat</term>
    661         <listitem>
    662           <para>
    663             Download and install Apache Tomcat 6.0.20 or later, available
    664             from <ulink
    665             url="http://tomcat.apache.org" />.
    666 
    667             It is a good idea to specify the maximum allowed memory
    668             that Tomcat can use. The default setting is usually not
    669             large enough. If you are using Tomcat 6.0.18 or higher
    670             you also need to disable strict parsing of JSP files.
    671           </para>
    672360         
    673           <para>
    674             Unless you have manually downloaded and installed JAI (Java Advanced
    675             Imaging) native acceleration libraries (see <ulink
    676             url="https://jai.dev.java.net/">https://jai.dev.java.net/</ulink>)
    677             it is also a good idea to disable the native acceleration of JAI.
    678           </para>
    679           <para>
    680             All of the above is done by setting Java startup options for
    681             Tomcat in the <code>CATALINA_OPTS</code> environment variable.
    682            
    683             Basically add the next line (as a single line) close to the top of
    684             the <filename>catalina.sh</filename> script that comes
    685             with Tomcat
    686             (directory <filename
     361          </itemizedlist>
     362         
     363          <para>
     364            Depending on your system there are probably several ways to set the
     365            the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following
     366            line (as a single line) close to the top of the <filename>catalina.sh</filename>
     367            script that comes with Tomcat (directory <filename
    687368            class="directory">bin</filename>):
    688 <programlisting>CATALINA_OPTS="-Xmx500m
     369<programlisting>CATALINA_OPTS="-Xmx1G
    689370-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
    690 -Dcom.sun.media.jai.disableMediaLib=true"</programlisting>
     371-Dcom.sun.media.jai.disableMediaLib=true
     372-Djava.awt.headless=true"</programlisting>
    691373          </para>
    692374          <para>
    … …  
    698380
    699381      <varlistentry>
    700         <term>Set up SQL database</term>
     382        <term>Set up an SQL database</term>
    701383        <listitem>
    702384          <para>
    … …  
    717399                <para>
    718400                  Download and install MySQL (tested with version
    719                   5.0), available from
     401                  5.1), available from
    720402                  <ulink url="http://www.mysql.com/" />. You need to
    721403                  be able to connect to the server over TCP, so
    … …  
    735417              <listitem>
    736418                <para>
    737                   PostgreSQL 8.2 seems to be working very well with
     419                  PostgreSQL 8.4 seems to be working very well with
    738420                  BASE and Hibernate. Download and install PostgreSQL,
    739421                  available from
    … …  
    755437                  </para>
    756438                </note>
    757                
     439                <para>
     440                  We have not yet tested BASE with PostgreSQL 9 so we can't tell
     441                  if it works or not.
     442                </para>
    758443              </listitem>
    759444            </varlistentry>
    … …  
    799484              is available in the
    800485              <ulink
    801               url="http://base.thep.lu.se/chrome/site/doc/historical/development/build.html">building
     486              url="http://base.thep.lu.se/wiki/BuildingBase">building
    802487              BASE document</ulink>. When you return back after
    803488              compiling in the subversion tree you can follow the
    … …  
    908593            set the owner to be the same as the one that the Tomcat
    909594            server will be running as. Remember this location for
    910             later use.
     595            later use. The default location is <filename>/usr/local/base2/files</filename>.
     596          </para>
     597        </listitem>
     598      </varlistentry>
     599     
     600      <varlistentry>
     601        <term>BASE (plug-in setup)</term>
     602        <listitem>
     603          <para>
     604            An area for plug-in and extensions installation must be setup.
     605            Create an empty directory in a proper location in your file system,
     606            and make sure that the user that the Tomcat
     607            server will be running as has read permission. Remember this location for
     608            later use. The default location is <filename>/usr/local/base2/plugins</filename>.
    911609          </para>
    912610        </listitem>
    … …  
    936634              <listitem>
    937635                Modify the <emphasis>userfiles</emphasis> setting to
    938                 match your choice above.
     636                match your choice in file storage setup above.
     637              </listitem>
     638              <listitem>
     639                Modify the <emphasis>plugins.dir</emphasis> setting to
     640                match your choice in plug-in setup above.
    939641              </listitem>
    940642            </itemizedlist>
    … …  
    1035737            server, you need to install the Apache version 2 web
    1036738            server, available
    1037             from <ulink
    1038             url="http://www.apache.org/">http://www.apache.org/</ulink>,
     739            from <ulink url="http://httpd.apache.org/" />,
    1039740            and a apache-tomcat connector, available
    1040741            from <ulink
    1041             url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
    1042             So, we got you there;-) To be honest, this step is not
    1043             really well documented since we previously used SuSE 9.3
    1044             on our demo/test server, and apache/tomcat/mod_jk comes
    1045             pre-installed. The current server does not use the
    1046             apache/tomcat connector. What you need to do is something
    1047             like this
    1048             <itemizedlist>
    1049               <listitem>
    1050                 Get that Tomcat server running in stand-alone
    1051                 mode.
    1052               </listitem>
    1053               <listitem>
    1054                 Get the Apache 2 server running.
    1055               </listitem>
    1056               <listitem>
    1057                 Install mod_jk. Note, different version are used for
    1058                 apache 1.3 and 2. In SuSE 9.3 this step is done by
    1059                 installing <filename>mod_jk-ap20</filename>.
    1060               </listitem>
    1061               <listitem>
    1062                 Create a <filename>workers.properties</filename> file
    1063                 in the
    1064                 Tomcat <filename class="directory">base</filename>
    1065                 directory (commonly copied from a template).
    1066               </listitem>
    1067               <listitem>
    1068                 Create a <filename>jk.conf</filename> file in the
    1069                 apache <filename class="directory">conf</filename>
    1070                 directory (commonly copied from a template), and make
    1071                 sure that <emphasis>jk</emphasis> is added to the
    1072                 modules to be loaded when apache starts.
    1073               </listitem>
    1074               <listitem>
    1075                 In <filename>jk.conf</filename> add the lines below
    1076                 and change paths appropriately.
    1077 <programlisting># The following lines makes apache aware of the location of
    1078 # the /base2 context
    1079 Alias /base2 "/srv/www/tomcat6/base/webapps/base2"
    1080 &lt;Directory "/srv/www/tomcat6/base/webapps/base2"&gt;
    1081 Options Indexes FollowSymLinks
    1082 allow from all
    1083 &lt;/Directory&gt;
    1084 # The following lines mounts all base2 jsp files to Tomcat
    1085 JkMount /base2 ajp13
    1086 JkMount /base2/* ajp13
    1087 # The following lines prohibits users from directly accessing WEB-INF
    1088 &lt;Location "/base2/WEB-INF/"&gt;
    1089 AllowOverride None
    1090 deny from all
    1091 &lt;/Location&gt;</programlisting>
    1092               </listitem>
    1093             </itemizedlist>
    1094             You must restart the Apache and the Tomcat server after above steps.
     742            url="http://tomcat.apache.org/connectors-doc/index.html" />
    1095743          </para>
    1096744        </listitem>
    … …  
    1109757            <xref linkend="user_administration"/>.
    1110758          </para>
    1111           <para>
    1112             If you are planning to perform a migration of data from
    1113             BASE version 1.2.x please perform the steps in
    1114             <xref linkend="installation_upgrade.migration"/> before
    1115             doing anything else with your new BASE installation.
    1116           </para>
    1117759        </listitem>
    1118760      </varlistentry>
    … …  
    1121763
    1122764  </sect1>      <!-- Installation instructions -->
     765
     766  <sect1 id="installation_upgrade.jobagents">
     767    <title>Installing job agents</title>
     768
     769    <para>
     770      It is important to understand that the BASE application can be
     771      spread on to several computers. The main BASE application is
     772      serving HTTP requests, the underlying database engine is
     773      providing storage and persistence of data, and job agents can be
     774      installed on computers that will serve the BASE installation
     775      with computing power and perform analysis and run plug-ins. In a
     776      straight forward setup one computer provides all services needed
     777      for running BASE. From this starting point it is easy to add
     778      computers to shares load from the BASE server by installing job
     779      agents on these additional computers.
     780    </para>
     781
     782    <para>
     783      A job agent is a program running on a computer regularly
     784      checking the BASE job queue for jobs awaiting execution. When
     785      the job agent finds a job that it is enabled to execute, it
     786      loads the plug-in and executes it. Job agents will in this way
     787      free up resources on the BASE application server, and thus allow
     788      the BASE server to concentrate on serving web pages. Job agents
     789      are optional and must be installed and setup
     790      separately. However, BASE is prepared for job agent setup and to
     791      utilize the agents, but the agent are not required.
     792    </para>
     793
     794    <para>
     795      A job agent supports many configuration options that are not
     796      supported by the internal job queue. For example, you can
     797      <itemizedlist>
     798        <listitem>
     799          <para>
     800            Specify exactly which plug-ins each job agent should be
     801            able to execute.
     802          </para>
     803        </listitem>
     804        <listitem>
     805          <para>
     806            Give some plug-ins higher priority than other plug-ins.
     807          </para>
     808        </listitem>
     809        <listitem>
     810          <para>
     811            Specify which users/groups/projects should be able to use
     812            a specific job agent.
     813          </para>
     814        </listitem>
     815        <listitem>
     816          <para>
     817            Override memory settings and more for each plug-in.
     818          </para>
     819        </listitem>
     820        <listitem>
     821          <para>
     822            Execute plug-ins in separate processes. Thus, a misbehaving
     823            plug-in cannot bring the main application server down.
     824          </para>
     825        </listitem>
     826        <listitem>
     827          <para>
     828            Add more computers with job agents as needed.
     829          </para>
     830        </listitem>
     831      </itemizedlist>
     832      All these options make it possible to create a very flexible
     833      setup. For example one job agent can be assigned for importing
     834      data only, another job agent can be assigned for running
     835      analysis plug-ins for specific project only, and a third may be a
     836      catch-all job agent that performs all low-priority jobs.
     837    </para>
     838
     839    <sect2 id="installation_upgrade.jobagents.serverside">
     840      <title>BASE application server side setup</title>
     841      <para>
     842        <variablelist>
     843          <varlistentry>
     844            <term>Make sure the internal job queue doesn't execute all plug-ins</term>
     845            <listitem>
     846              <para>
     847                The setting <command>jobqueue.internal.runallplugins</command>
     848                should be set to <command>false</command> for the
     849                BASE server. This setting is found in
     850                the <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
     851                file. The changes will not take effect until the
     852                application server is restarted.
     853              </para>
     854
     855            </listitem>
     856          </varlistentry>
     857          <varlistentry id="installation_upgrade.jobagent.user_account">
     858            <term>Enable the job agent user account</term>
     859            <listitem>
     860              <para>
     861                During installation of BASE a user account is created
     862                for the job agent. This account is used by the job
     863                agents to log on to BASE. The account is disabled by
     864                default and must be enabled. Enable the account and
     865                set a password using the BASE web interface.
     866                The same password must also be set in the
     867                <filename>jobagent.properties</filename> file, see
     868                item
     869                <xref linkend="installation_upgrade.jobagent.client.properties"/>
     870                below.
     871              </para>
     872            </listitem>
     873          </varlistentry>
     874        </variablelist>
     875      </para>
     876    </sect2>
     877
     878    <sect2 id="installation_upgrade.jobagents.database">
     879      <title>Database server setup</title>
     880      <para>
     881        <variablelist>
     882          <varlistentry id="installation_upgrade.jobagent.database">
     883            <term>Create a user account on the database</term>
     884            <listitem>
     885              <para>
     886                This is the similar to granting database access for
     887                the BASE server user in the in the regular BASE
     888                installation, cf.
     889                <xref
     890                linkend="installation_upgrade.installation.database"/>.
     891                You must create an account in the database that is
     892                allowed to connect from the job agent server. MySQL
     893                example:
     894<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
     895GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
     896
     897                Replace <command>job.agent.host</command> with the
     898                host name of the server that is going to run the job
     899                agent. You should also set password. This password is
     900                used in item
     901                <xref linkend="installation_upgrade.jobagent.client.config"/>
     902                below in job agent server setup. You can use the same
     903                database user and password as in the regular database
     904                setup.
     905              </para>
     906            </listitem>
     907          </varlistentry>
     908        </variablelist>
     909      </para>
     910    </sect2>
     911
     912    <sect2 id="installation_upgrade.jobagents.client">
     913      <title>Job agent client setup</title>
     914      <para>
     915        <variablelist>
     916          <varlistentry>
     917            <term>Download and unpack a regular BASE distribution</term>
     918            <listitem>
     919              <para>
     920                You <emphasis>must</emphasis> use the same version on
     921                the web server and all job agents. You find the
     922                downloads at
     923                <ulink
     924                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
     925              </para>
     926            </listitem>
     927          </varlistentry>
     928          <varlistentry id="installation_upgrade.jobagent.client.config">
     929            <term>Edit the <filename>base.config</filename> file</term>
     930            <listitem>
     931              <para>
     932                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/base.config</filename>
     933                file must be configured as in regular BASE
     934                installation, cf.
     935                <xref
     936                linkend="installation_upgrade.installation.configuration"/>,
     937                to use the same database as the web server
     938                application. The most important settings are
     939                <itemizedlist>
     940                  <listitem>
     941                    <para>
     942                      <command>db.username</command>: The database
     943                      user you created in item
     944                      <xref
     945                      linkend="installation_upgrade.jobagent.database"/>
     946                      above.
     947                    </para>
     948                  </listitem>
     949                  <listitem>
     950                    <para>
     951                      <command>db.password</command>: The password for
     952                      the user.
     953                    </para>
     954                  </listitem>
     955                  <listitem>
     956                    <para>
     957                      <command>db.url</command>: The connection url to
     958                      the database.
     959                    </para>
     960                  </listitem>
     961                  <listitem>
     962                    <para>
     963                      <command>userfiles</command>: The path to the
     964                      directory where user files are located. This
     965                      directory must be accessible from all job
     966                      agents, i.e., by nfs or other file system
     967                      sharing method.
     968                    </para>
     969                  </listitem>
     970                  <listitem>
     971                    <para>
     972                      <command>plugins.dir</command>: The path to the
     973                      directory where plug-ins are located. This
     974                      directory must be accessible from all job
     975                      agents, i.e., by nfs or other file system
     976                      sharing method.
     977                    </para>
     978                  </listitem>
     979                </itemizedlist>
     980                See the <xref linkend="appendix.base.config"/> for
     981                more information about the settings in
     982                the <filename>base.config</filename> file.
     983              </para>
     984            </listitem>
     985          </varlistentry>
     986          <varlistentry id="installation_upgrade.jobagent.client.properties">
     987            <term>Edit
     988            the <filename>jobagent.properties</filename> file</term>
     989            <listitem>
     990              <para>
     991                The <filename>&lt;base-dir&gt;/www/WEB-INF/classes/jobagent.properties</filename>
     992                file contains settings for the job agent. The most
     993                important ones to specify value for are
     994                <itemizedlist>
     995                  <listitem>
     996                    <para>
     997                      <command>agent.password</command>: The password
     998                      you set for the job agent user account in item
     999                      <xref
     1000                      linkend="installation_upgrade.jobagent.user_account"/>
     1001                      above.
     1002                    </para>
     1003                  </listitem>
     1004                  <listitem>
     1005                    <para>
     1006                      <command>agent.id</command>: An ID that must be
     1007                      unique for each job agent accessing the BASE application.
     1008                    </para>
     1009                  </listitem>
     1010                  <listitem>
     1011                    <para>
     1012                      <command>agent.remotecontrol</command>: The
     1013                      name or ip address of the web server if you want it
     1014                      to be able to display info about running
     1015                      jobs. The job agent will only allow connections
     1016                      from computers specified in this setting.
     1017                    </para>
     1018                  </listitem>
     1019                </itemizedlist>
     1020              </para>
     1021              <para>
     1022                The <filename>jobagent.properties</filename> file
     1023                contains many more configuration options. See
     1024                the <xref linkend="appendix.jobagent.properties"/> for
     1025                more information.
     1026              </para>
     1027            </listitem>
     1028          </varlistentry>
     1029          <varlistentry>
     1030            <term>Register the job agent</term>
     1031            <listitem>
     1032              <para>
     1033                From the <filename>bin</filename> directory, register
     1034                the job agent with
     1035                <programlisting>./jobagent.sh register</programlisting>
     1036              </para>
     1037            </listitem>
     1038          </varlistentry>
     1039          <varlistentry>
     1040            <term>Start the job agent</term>
     1041            <listitem>
     1042              <para>
     1043                From the <filename>bin</filename> directory, start the
     1044                job agent with
     1045                <programlisting>./jobagent.sh start &amp;</programlisting>
     1046              </para>
     1047              <para>
     1048                See the <xref linkend="appendix.jobagent.sh"/>
     1049                for more information about what you can do
     1050                with the job agent command line interface.
     1051              </para>
     1052            </listitem>
     1053          </varlistentry>
     1054        </variablelist>
     1055      </para>
     1056    </sect2>
     1057
     1058
     1059    <sect2 id="installation_upgrade.jobagents.configuration">
     1060      <title>Configuring the job agent</title>
     1061   
     1062      <para>
     1063        A job agent will not execute a plug-in unless the administrator
     1064        has configured the job agent to do so. There are two things that
     1065        must be done:
     1066      </para>
     1067     
     1068      <itemizedlist>
     1069        <listitem>
     1070        <para>
     1071          Share the job agent to the users, groups and project that should be
     1072          able to use it. If the job agent is not shared, only the owner of
     1073          job agent is allowed to use it. Use the regular <guilabel>Share</guilabel>
     1074          functionality to specify which users/groups/projects
     1075          should be able to use the job agent. You must give
     1076          them at least <command>USE</command> permission.
     1077          To give all users permission to the job agent share it
     1078          to the <command>EVERYONE</command> group.
     1079        </para>
     1080        </listitem>
     1081       
     1082        <listitem>
     1083        <para>
     1084          Selecting plug-ins that the job agent should handle. This can be
     1085          done either from the plug-in pages or from the job agent pages. To register
     1086          a plug-in with one or more job agents from the plug-in pages, go
     1087          to the edit view of the plug-in and select the <guilabel>Job
     1088          agents</guilabel> tab. To do the same from the job agent pages,
     1089          go to the edit view of the job agent and select
     1090          the <guilabel>Plugins</guilabel> tab. The registration dialogs
     1091          are very similar but only the plug-in side of registration is
     1092          described here. The major difference is that it is not possible
     1093          to enable/disable the internal job queue for plug-in when using
     1094          the jobagent side of the registration.
     1095        </para>
     1096        </listitem>
     1097      </itemizedlist>
     1098   
     1099      <figure id="plugins.figures.jobagents">
     1100        <title>Select job agents for a plug-in</title>
     1101        <screenshot>
     1102          <mediaobject>
     1103            <imageobject><imagedata
     1104              scalefit="1" width="100%"
     1105              fileref="figures/plugin_jobagents.png" format="PNG"
     1106              /></imageobject>
     1107          </mediaobject>
     1108        </screenshot>
     1109      </figure>
     1110   
     1111      <helptext external_id="plugindefinition.jobagents"
     1112        title="Job agents">
     1113       
     1114        <para>
     1115          Use this tab to specify which job agents the plug-in is
     1116          installed and allowed to be executed on.
     1117        </para>
     1118       
     1119        <variablelist>
     1120        <varlistentry>
     1121          <term><guilabel>Run this plugin on</guilabel></term>
     1122          <listitem>
     1123            <para>
     1124              You may select if the internal job queue should execute the
     1125              plug-in or not.
     1126            </para>
     1127          </listitem>
     1128        </varlistentry>
     1129        <varlistentry>
     1130          <term><guilabel>Job agents</guilabel></term>
     1131          <listitem>
     1132            <para>
     1133              A list with the job agents where the plug-in is installed and
     1134              allowed to be executed. Select a plug-in in this list to display
     1135              more configuration options for the plug-in.
     1136            </para>
     1137          </listitem>
     1138        </varlistentry>
     1139        <varlistentry>
     1140          <term><guilabel>Add job agents</guilabel></term>
     1141          <listitem>
     1142            <para>
     1143              Use this button to open a pop-up window for selecting
     1144              job agents.
     1145            </para>
     1146          </listitem>
     1147        </varlistentry>
     1148        <varlistentry>
     1149          <term><guilabel>Remove</guilabel></term>
     1150          <listitem>
     1151            <para>
     1152              Remove the selected plug-in from the list.
     1153            </para>
     1154          </listitem>
     1155        </varlistentry>
     1156        </variablelist>
     1157       
     1158        <para>
     1159          The following properties are only displayed when a
     1160          job agent has been selected in the list. Each job agent may have it's
     1161          own settings of these properties. If you leave the values unspecified
     1162          the job agent will use the default values specified on the
     1163          <guilabel>Plugin</guilabel> tab.
     1164        </para>
     1165       
     1166        <variablelist>
     1167        <varlistentry>
     1168          <term><guilabel>Max memory</guilabel></term>
     1169          <listitem>
     1170            <para>
     1171              The maximum amount of memory the plug-in is allowed to use.
     1172              Add around 40MB for the Java run-time environment and BASE.
     1173              If not specified Java will choose it's default value which is 64MB.
     1174            </para>
     1175          </listitem>
     1176        </varlistentry>
     1177        <varlistentry>
     1178          <term><guilabel>Trusted</guilabel></term>
     1179          <listitem>
     1180            <para>
     1181              If the plug-in should be executed in a protected or
     1182              unprotected environment. Currently, BASE only supports
     1183              running plug-ins in an unprotected environment.
     1184            </para>
     1185          </listitem>
     1186        </varlistentry>
     1187        <varlistentry>
     1188          <term><guilabel>Priority boost</guilabel></term>
     1189          <listitem>
     1190            <para>
     1191              Used to give a plug-in higher priority in the job queue.
     1192              Values between 0 and 10 are allowed. A higher value will
     1193              give the plug-in higher priority. The priority boost is useful
     1194              if we, for example, want to use one server mainly for importing
     1195              data. By giving all import plugins a priority boost they will
     1196              be executed before all other jobs, which will have to wait
     1197              until there are no more waiting imports.
     1198            </para>
     1199          </listitem>
     1200        </varlistentry>
     1201        </variablelist>
     1202       
     1203        <seeother>
     1204          <other external_id="plugindefinition.edit">Plug-in properties</other>
     1205          <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
     1206        </seeother>
     1207      </helptext>
     1208    </sect2>
     1209
     1210  </sect1>      <!-- job agent setup -->
    11231211
    11241212  <sect1 id="installation_upgrade.serverconfigurations">
    … …  
    12181306            title="Instructions to get an account">
    12191307            <para>
    1220               A description what a none-registered user should do to get
    1221               an account on the particular BASE-server. This text is linked
     1308              A description what a user should do to get
     1309              an account on the particular BASE server. This text is linked
    12221310              to the <guilabel>Get an account!</guilabel> link on the login
    12231311              page. We recommend that the Latin text is replaced with some useful
    … …  
    12351323            title="Instructions when password is forgotten.">
    12361324            <para>
    1237               A description what an user should do if the password is forgotten.
     1325              A description what a user should do if the password is forgotten.
    12381326              This text is linked
    12391327              to the <guilabel>Forgot your password?</guilabel> link on the login
    … …  
    13421430            Mark this check-box to try to prevent new users from logging in. To
    13431431            avoid problems that can be caused by blocking the server admin out,
    1344             the login is not completely, disabled. Any user can still login but
     1432            the login is not completely disabled. Any user can still login but
    13451433            only after by-passing several warnings.
    13461434            </para>
    … …  
    13701458  </sect1>
    13711459
    1372   <sect1 id="installation_upgrade.migration">
    1373     <title>Migration instructions</title>
    1374    
    1375     <para>
    1376       The support for migration from BASE 1.2 to BASE 2 ended in
    1377       BASE 2.6, but the migration program was included in the
    1378       distribution until BASE 2.15. As of BASE 2.16 the migration
    1379       program is no longer included in the distribution. Our
    1380       recommendation for migration is to try BASE 2.15 first and
    1381       then upgrade to the newest BASE version. Full instructions for
    1382       the migratation program are included in the BASE 2.15 distribution.
    1383     </para>
    1384 
    1385   </sect1>      <!-- Migration instructions -->
    1386 
    13871460</chapter>

  • trunk/doc/src/docbook/admindoc/plugins.xml

    r5735 r5737  
    2828
    2929<chapter id="plugins">
    30   <?dbhtml dir="plugin_installation"?>
    31   <title>Plug-ins</title>
     30  <?dbhtml dir="plugins"?>
     31  <title>Plug-ins and extensions</title>
    3232
    3333  <para>
    34     BASE can get extended functionality by the use of plug-ins. In fact, most
    35     of the hard work, such as data import/export and analysis is done with plug-ins.
     34    BASE can get extended functionality by the use of plug-ins and extensions.
     35    Much of the hard work, such as data import/export and analysis is done with plug-ins.
    3636    BASE ships with a number of standard plug-ins, the core plug-ins, which gives
    37     basic import/export and analysis functionality. See <xref linkend="resources" />
    38     for more information about the core plug-ins and 3rd-party plug-ins.
     37    basic import/export and analysis functionality. Typically a plug-in interacts with
     38    a user by asking for parameters that it need to be able to do it's work. For
     39    example, which file to import data from, and maybe some regular expressions that
     40    should be used when parsing the file and then some information about how the data
     41    in the file should be mapped to items and properties in BASE. When the plug-in has
     42    all parameters it needs a <guilabel>Job</guilabel> is added to a job queue. A job
     43    agent or similar is then responsible for sceduling and executing (possibly on a
     44    different machine) the plug-in code.
    3945  </para>
     46 
     47  <para>
     48    Extensions are historically more targeted at additions to the user interface,
     49    such as additional menu items, toolbar buttons, etc. As a result, extensions have
     50    a lot more flexibility when it comes to the visual appearance. On the other
     51    hand they are executed immediately as a result of user interaction and are expected
     52    to perform quickly and without delay.
     53  </para>
     54 
     55  <para>
     56    Starting with BASE 3 the extension mechanism has been somewhat extended to cover
     57    other things that are not directly related to the web interface. For example,
     58    extensions can be used to add support for other protocols than HTTP when using
     59    external files. The main difference between a plug-in and extension is that an
     60    extension must execute immediately it's service is requested, but a plug-in can
     61    be scheduled for later execution.
     62  </para>
    4063
    4164
    4265  <sect1 id="plugins.installation">
    43     <title>Installing plug-ins</title>
     66    <title>Managing plug-ins and extensions</title>
     67   
     68    <note>
     69      <title>Changes since BASE 2</title>
     70      <para>
     71        The plug-in and extensions installation has changed since BASE 2. The major
     72        changes are:
     73      </para>
     74      <itemizedlist>
     75        <listitem>
     76        <para>
     77          The main JAR file must be installed in the directory specified by the
     78          <constant>plugins.dir</constant> setting in <filename>base.config</filename>.
     79          Subdirectories are not allowed. This applies to both plug-ins and
     80          extensions. The <filename>WEB-INF/extensions</filename> is not used for
     81          extensions anymore.
     82        </para>
     83        </listitem>
     84        <listitem>
     85        <para>
     86          A package must be installed as a whole. It is no longer possible to only
     87          select some of the plug-ins to install. If neccessary, the administrator can
     88          always disable plug-ins that is not wanted.
     89        </para>
     90        </listitem>
     91      </itemizedlist>
     92    </note>
     93   
    4494    <para>
    45       The first step is to install the plug-in on the web server. To make
    46       these instructions easier to read we assume the plug-in comes as
    47       a single JAR file and that it does not depend on any other JAR files.
     95      The first step is to install the actual code on the web server. The recommendation
     96      to developers is to ship the entire package as a single JAR file. If everything is
     97      JAVA based this should not be a problem. A common exception is that configuration
     98      files should be installed (and configured) separately. Always read the installation
     99      instructions for the package you are installing. The rest of the instructions in
     100      this section assume that the plug-in/extensions comes as a single JAR file.
    48101    </para>
    49102   
     103    <note>
     104      <title>Make sure the extensions folder is writable by Tomcat</title>
     105      <para>
     106        The package you are installing may include resources such as HTML
     107        files, JSP scripts, images, etc. that needs to be extracted to the
     108        web application path before they can be used. This extraction is
     109        automatically done by the installation wizard, but you have to make
     110        sure that the user account Tomcat is running as has permission
     111        to create (and delete) new files in the
     112        <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
     113        directory.
     114      </para>
     115    </note>
     116   
    50117    <para>
    51       We recommend that you install the plug-in JAR file outside the web
    52       server's Classpath. Do not put the plug-in in the
    53       <filename>&lt;base-dir&gt;/www/WEB-INF/lib</filename>
    54       directory or any other directory where the web server keeps it's classes.
    55       This makes BASE use it's own class loader that support unloading of classes
    56       as well. This means that you can install new plug-ins and update
    57       existing ones without restarting the web server.
     118      So, the first step should be simple. Just put the JAR file in the
     119      dedicated plug-ins directory. This is the directory that is specified
     120      in the <constant>plugins.dir</constant> setting in <filename>base.config</filename>.
    58121    </para>
    59122   
    60     <para>
    61       We recommend that you create a separate directory for plug-ins and
    62       install all of them there. You may use a sub-directory for each plug-in
    63       if you like, for example:
    64       <filename>&lt;base-dir&gt;/plugins/&lt;name-of-plugin&gt;</filename>
    65     </para>
    66    
    67     <note>
    68       <title>Plug-ins that use other JAR files</title>
    69       <para>
    70         Some plug-ins may depend on other JAR files. Normally,
    71         these JAR files should be put in the same directory as the
    72         plug-in JAR file. This may, however, vary from plug-in to plug-in
    73         so always check the plug-in documentation first.
    74       </para>
    75     </note>
    76    
    77     <para>
    78       When the plug-in is installed on the server you must register it with BASE. To register
    79       the plug-in with BASE go to
    80       <menuchoice>
    81         <guimenu>Administrate</guimenu>
    82         <guisubmenu>Plugins</guisubmenu>
    83         <guimenuitem>Definitions</guimenuitem>
    84       </menuchoice>
    85       and click on the &gbNew; button. In the pop-up window that appears
    86       you should first decide if you want to do a manual or an (almost) automatic
    87       installation. An automatic installation scans the server disks for plug-ins
    88       and lets you select which ones to install or update from a list in the
    89       web interface. In a manual installation you are required to enter the
    90       path and class name of the plug-in yourself.
    91     </para>
    92    
    93     <sect2 id="plugins.select.installtype">
    94       <title>Select installation method</title>
    95       <para>
    96         This window appears, like described above, when automatic installation/registration
    97         of plug-ins is available.
    98         <figure id="plugins.figures.selectinstall">
    99           <title>Select installation type</title>
    100           <screenshot>
    101             <mediaobject>
    102               <imageobject>
    103                 <imagedata fileref="figures/select_install.png" format="PNG"
    104                   scalefit="1" width="70%" />
    105               </imageobject>
    106             </mediaobject>
    107           </screenshot>
    108         </figure>
    109       </para>
    110       <helptext external_id="plugindefinition.installationtype"
    111         title="Select installation type">
    112         <variablelist>
    113           <varlistentry>
    114             <term><guilabel>Install</guilabel>
    115             </term>
    116             <listitem>
    117               <para>
    118               How to register the plug-in(s) with BASE.
    119               <variablelist>
    120               <varlistentry>
    121                 <term><emphasis>Automatically</emphasis></term>
    122                 <listitem>
    123                   <para>
    124                   BASE will scan the selected directories for JAR files containing
    125                   plug-ins. If it finds any, you will have the option
    126                   to select which ones to install from a list.
    127                   <nohelp>The next step will be <xref linkend="plugins.autoinstall" /></nohelp>
    128                   </para>
    129                 </listitem>
    130               </varlistentry>
    131               <varlistentry>
    132                 <term><emphasis>Manually</emphasis></term>
    133                 <listitem>
    134                   <para>
    135                   Class name and JAR path have to be entered manually by the
    136                   administrator. Only one plug-in can be registered at
    137                   a time in this way. Next step will be
    138                   <nohelp><xref linkend="plugins.install.properties" /></nohelp>
    139                   </para>
    140                 </listitem>
    141               </varlistentry>
    142               </variablelist>
    143             </para>
    144             </listitem>
    145           </varlistentry>
    146           <varlistentry>
    147             <term><guilabel>Directories</guilabel> (only when <emphasis>Automatically</emphasis> is selected)</term>
    148             <listitem>
    149               <para>
    150                 Select the checkboxes were BASE should look for new plug-ins.
    151                 For security reasons the only options are the dedicated plug-ins
    152                 directory that is configured in the <filename>base.config</filename>
    153                 directory and the extensions that directory that is normally
    154                 used for extensions to the web client.
    155               </para>
    156             </listitem>
    157           </varlistentry>
    158         </variablelist>
     123    <sect2 id="plugins.installation.wizard">
     124      <title>Automatic installation wizard</title>
     125   
     126      <para>
     127        When the plug-in/extensions package is installed on the server you must register
     128        it with BASE. Go to
     129        <menuchoice>
     130          <guimenu>Administrate</guimenu>
     131          <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     132          <guimenuitem>Overview</guimenuitem>
     133        </menuchoice>.
     134      </para>
     135     
     136      <figure id="extensions.figures.installedextensions">
     137        <title>Installed extensions &amp; plug-ins</title>
     138        <screenshot>
     139          <mediaobject>
     140            <imageobject>
     141              <imagedata fileref="figures/installed_extensions.png" format="PNG" />
     142            </imageobject>
     143          </mediaobject>
     144        </screenshot>
     145      </figure>
     146     
     147      <helptext
     148        external_id="extensions.details.main"
     149        title="Installed extensions">
    159150       
    160         <note>
    161           The automatic installation doesn't allow you to set all properties
    162           that can be set in a manual installation. If you for example, need
    163           to share the plug-ins to other users or assign them to job agents
    164           this must be done after the auto-installation has been completed.
    165         </note>
     151        <para>
     152          The left-hand side of the screen shows a tree with all installed
     153          plug-ins and extensions, sorted by extension point and by file. Use
     154          the + and - icons to expand and collapse parts of the tree. Click on an item
     155          in the tree to display detailed information about it
     156          on the right-hand side of the screen. Click on the
     157          <guibutton>Install/uninstall</guibutton> button to start
     158          the installation wizard (which can also be used for uninstallation).
     159        </para>
    166160       
    167161        <seeother>
    168           <other external_id="plugindefinition.edit">Manual installation</other>
    169           <other external_id="plugindefintion.autoinstaller">Automatic installation</other>
     162          <other external_id="extensions.install-wizard">Install/uninstall wizard</other>
    170163        </seeother>
     164      </helptext>
     165     
     166      <figure id="plugins.figures.installwizard">
     167        <title>Extensions and plug-ins installation wizard</title>
     168        <screenshot>
     169          <mediaobject>
     170            <imageobject>
     171              <imagedata fileref="figures/plugins_install_wizard.png" format="PNG"
     172                scalefit="1" width="100%" />
     173            </imageobject>
     174          </mediaobject>
     175        </screenshot>
     176      </figure>
    171177       
     178 
     179      <helptext
     180        external_id="extensions.install-wizard"
     181        title="Extensions and plug-ins installation wizard">
     182       
     183        <para>
     184          This wizard can be used for both installing, re-installing and un-installing
     185          plug-in and extension packages. The first dialog shows a list with all
     186          currently installed packages as well as any new packages that has been
     187          found on the server. The list includes the name of the JAR file,
     188          the current status and some information provided by the author of the package.
     189          There are also two columns <guilabel>Install</guilabel> and
     190          <guilabel>Uninstall</guilabel> which may or may not have a checkbox in them.
     191          For new packages there should be a checkbox in the install column that is already
     192          checked. Already installed packages can either be re-installed or uninstalled by
     193          checking the appropriate checkbox. If there is a problem with a package an error
     194          message is displayed and neither installation or uninstallation is possible.
     195        </para>
     196       
     197        <para>
     198          Click on <guibutton>Next</guibutton> to perform the selected actions. The next
     199          dialog should display a summary with the installation results.
     200          Hopefully everything was succeessful. Close the dialog and refresh the overview tree
     201          to see the changes.
     202        </para>
     203     
     204        <note>
     205          <para>
     206            Uninstalling a package doesn't remove the plug-in definitions from BASE nor
     207            does it remove the JAR file from the server. This is because there may be jobs
     208            and other items referencing the plug-ins. The plug-ins are only marked as disabled
     209            and it is up to the administrator to actually delete them if it is possible.
     210          </para>
     211        </note>
    172212      </helptext>
     213     
     214      <figure id="plugins.figures.installresults">
     215        <title>Extensions and plug-ins installation results</title>
     216        <screenshot>
     217          <mediaobject>
     218            <imageobject>
     219              <imagedata fileref="figures/plugins_install_wizard_2.png" format="PNG"
     220                scalefit="1" width="100%" />
     221            </imageobject>
     222          </mediaobject>
     223        </screenshot>
     224      </figure>
    173225    </sect2>
    174226
    175     <sect2 id="plugins.install.properties">
    176       <title>Plug-in properties</title>
    177    
    178     <para>
    179       This section describes the manual installation of a plug-in.
    180     </para>
    181    
    182     <figure id="plugins.figures.install">
    183       <title>Installing a plug-in</title>
    184       <screenshot>
    185         <mediaobject>
    186           <imageobject><imagedata
    187             fileref="figures/install_plugin.png" format="PNG"
    188             /></imageobject>
    189         </mediaobject>
    190       </screenshot>
    191     </figure>
     227    <sect2 id="plugins.installation.manual">
     228      <title>Manual plug-in registration</title>
     229   
     230      <para>
     231        Manual installation of a plug-in should almost never be neccessary.
     232        One exception is that developers may want to do this as a first step
     233        before everything has been properly packaged. Another exception is plug-ins
     234        developed for BASE 2 that doesn't support the automatic installation procedure.
     235        If the old plug-in still works API-wise in BASE 3, manual installation
     236        can be used to install it. Repackaging such a plug-in is however not difficult
     237        so we recommend that the plug-in author is asked to provide an updated
     238        version.
     239      </para>
     240     
     241      <para>
     242        To perform a manual installation, go to <menuchoice>
     243        <guimenu>Administrate</guimenu>
     244        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     245        <guimenuitem>Plug-in definitions</guimenuitem>
     246        </menuchoice> and click on the <guibutton>New</guibutton> button.
     247      </para>
     248   
     249      <figure id="plugins.figures.installmanual">
     250        <title>Manually installing a plug-in</title>
     251        <screenshot>
     252          <mediaobject>
     253            <imageobject><imagedata
     254              fileref="figures/plugins_install_manual.png" format="PNG"
     255              /></imageobject>
     256          </mediaobject>
     257        </screenshot>
     258      </figure>
    192259   
    193260    <helptext external_id="plugindefinition.edit"
    … …  
    208275        <listitem>
    209276          <para>
    210             The Java class name of the plug-in.
    211           </para>
    212         </listitem>
    213       </varlistentry>
    214       <varlistentry>
    215         <term><guilabel>Path</guilabel></term>
    216         <listitem>
    217           <para>
    218             The path to the JAR file on the web server. If left empty
     277            The full Java class name of the plug-in.
     278          </para>
     279        </listitem>
     280      </varlistentry>
     281      <varlistentry>
     282        <term><guilabel>JAR file</guilabel></term>
     283        <listitem>
     284          <para>
     285            The name of the JAR file on the web server. The JAR file must
     286            be installed in the directory specified by the <constant>plugins.dir</constant>
     287            setting in <filename>base.config</filename> If left empty
    219288            the plug-in must be on the web server's class path (not
    220289            recommended).
    … …  
    230299            the internal job queue is used this setting has no effect and the
    231300            plug-in may use as much memory as it likes.
    232             <nohelp>See <xref linkend="plugins.jobagents" /> later
    233             in this chapter.</nohelp>
     301            <nohelp>See <xref linkend="installation_upgrade.jobagents.configuration" /> for more information.</nohelp>
    234302          </para>
    235303        </listitem>
    … …  
    313381    </sect2>
    314382   
    315     <sect2 id="plugins.autoinstall">
    316       <title>Automatic installation of plug-ins</title>
    317      
    318       <para>
    319         This section describes the automatic installation of plug-ins
    320         using a wizard.
    321       </para>
    322      
    323       <figure id="plugins.figures.autoinstall">
    324         <title>Auto install plug-ins</title>
    325      
    326         <screenshot>
    327           <mediaobject>
    328             <imageobject>
    329               <imagedata
    330                 fileref="figures/plugin_autoinstall.png" format="PNG"
    331               />
    332             </imageobject>
    333           </mediaobject>
    334         </screenshot>
    335       </figure>
    336      
    337       <para>
    338         This window lists all the plug-ins that were found in JAR files,
    339         after scanning the selected directories from the previous step.
    340         There are a few options to set for each plug-in before they can be registered.
    341       </para>
    342      
    343       <helptext external_id="plugindefintion.autoinstaller" title="Auto install plugins">
    344         <para>
    345           The page has, for each plug-in, a row that is divided into four columns with
    346           information or settings. These are explained more in details below. There is an icon
    347           in the <guilabel>Install</guilabel> column that displays summarized information about the plug-in when
    348           the mouse pointer is held over it. Most of this information is from the plug-in's
    349           <classname docapi="net.sf.basedb.core.plugins">About</classname>
    350           property but some, like 'Works with', 'Class' and 'Jar' is from the installation
    351           file included in the JAR file. A plug-in can also be distributed with one or many
    352           configurations that can be selected for import together with plug-in
    353           registration. The configurations are by default hidden but can easily be viewed by
    354           expanding the configuration tree for a plug-in.
    355           <variablelist>
    356             <varlistentry>
    357               <term>
    358                 <guilabel>Plugins</guilabel>
    359               </term>
    360               <listitem>
    361                 <para>
    362                   The plug-in's name, from the plug-in class. Names of the
    363                   configurations that comes with a plug-in are also displayed in
    364                   this column but in a tree under the plug-in they belong to.
    365                 </para>
    366               </listitem>
    367             </varlistentry>
    368             <varlistentry>
    369               <term>
    370                 <guilabel>Install</guilabel>
    371               </term>
    372               <listitem>
    373                 <para>
    374                   A selection list for each plug-in found when scanning the plug-in directory.
    375                   There are at least two option for each plug-in in this drop-down list. The
    376                   default option
    377                   <emphasis>no</emphasis>
    378                   will not register the plug-in to BASE while
    379                   <emphasis>yes</emphasis>
    380                   will register the plug-in when proceeding. If the plug-in
    381                   also have configurations the <emphasis>yes</emphasis>
    382                   option is replaced with <emphasis>plugin only</emphasis>
    383                   and <emphasis>plugin + configurations</emphasis>.
    384                   If the last option is selected all configurations for the
    385                   specific plug-in will be imported.
    386                 </para>
    387                 <para>
    388                   Each listed configuration can individually be defined if it
    389                   should be imported or not. This is done by selecting
    390                   <emphasis>yes</emphasis> or <emphasis>no</emphasis>.
    391                 </para>
    392                 <note>
    393                   <para>
    394                     Plug-ins that already are registered in BASE will be disabled in the list,
    395                     unless the plug-in comes from a JAR file in a different path than the
    396                     one registered in BASE, or if the version does not consist
    397                     with the one registered in BASE. In these cases the
    398                     drop-down list is enabled for selection but the plug-in
    399                     name is marked with an exclamation mark and the plug-in will be
    400                     re-registered and updated if any of the two install options are
    401                     selected.
    402                   </para>
    403                 </note>
    404                 <note>
    405                   <para>
    406                     If a configuration in the list has an identical name as a configuration in BASE
    407                     and the configurations are for the same plug-in, there will be a warning in the
    408                     list beside the install-select box. The already existing configuration will not
    409                     be overwritten if the new plug-in configuration is set to be imported,
    410                     but there will be two configurations with the same name and for the same plug-in.
    411                   </para>
    412                 </note>
    413               </listitem>
    414             </varlistentry>
    415             <varlistentry>
    416               <term>
    417                 <guilabel>Trusted</guilabel>
    418               </term>
    419               <listitem>
    420                 <para>
    421                   If the plug-in is trusted enough to be executed in an
    422                   unprotected environment. See
    423                   <nohelp>
    424                     <xref linkend="plugins.install.properties" />
    425                   </nohelp>
    426                 </para>
    427               </listitem>
    428             </varlistentry>
    429             <varlistentry>
    430               <term>
    431                 <guilabel>Immediate execution</guilabel>
    432               </term>
    433               <listitem>
    434                 <para>
    435                   If the plug-in is allowed to bypass the job queue and be
    436                   executed immediately. See
    437                   <nohelp>
    438                     <xref linkend="plugins.install.properties" />
    439                   </nohelp>
    440                 </para>
    441               </listitem>
    442             </varlistentry>
    443           </variablelist>
    444         </para>       
    445         <para>
    446           Click on &gbSave; to finish the registration
    447           or on &gbCancel; to abort.
    448         </para>
    449         <seeother>
    450           <other external_id="plugindefinition.edit">Edit plugins</other>
    451         </seeother>
    452       </helptext>
    453     </sect2>
    454    
     383
    455384    <sect2 id="plugins.installation.base1">
    456385      <title>BASE version 1 plug-ins</title>
    … …  
    476405        <listitem>
    477406        <para>
    478           Follow the instructions in
    479           <xref linkend="plugins.configuration.base1" /> to configure
    480           Base1PluginExecuter for use of the BASE1 plug-in.
     407          Upload the <filename>*.base</filename> file for the BASE
     408          version 1 plug-in. If you cannot find the file, you can let
     409          your BASE version 1 server create one for you. In your BASE
     410          version 1 installation go to
     411          <menuchoice>
     412            <guimenu>Analyze data</guimenu>
     413            <guimenuitem>Plug-ins</guimenuitem>
     414          </menuchoice>
     415          and use the <guilabel>Export</guilabel> function. This will
     416          create a configuration file for your BASE version 1 plug-in
     417          that you can upload to your new BASE server.
    481418        </para>
    482419        </listitem>
     420
     421        <listitem>
     422          <para>
     423            Create a new plug-in configuration using, for example,
     424            the <guibutton>New configuration</guibutton> button in
     425            single-item view for
     426            the <emphasis>Base1PluginExecuter</emphasis> plug-in.
     427          </para>
     428        </listitem>
     429
     430        <listitem>
     431          <para>
     432            Start the configuration wizard and select parameters:
     433          </para>
     434          <itemizedlist>
     435            <listitem>
     436            <para>
     437              <guilabel>File</guilabel>: The <filename>*.base</filename> file
     438              describing the BASE version 1 plug-in. This can be left empty for
     439              manual configuration, but in reality it is only usable for tweaking
     440              an existing configuration that has been created from a file
     441              in the first place.
     442            </para>
     443            </listitem>
     444            <listitem>
     445            <para>
     446              <guilabel>Plugin executables path</guilabel>: The path to the executable
     447              program that was installed in the first step.
     448             
     449            </para>
     450            </listitem>
     451            <listitem>
     452            <para>
     453              <guilabel>Source intensities</guilabel>: Select if the plug-in can work
     454              with regular or logged data (or both).
     455            </para>
     456            </listitem>
     457            <listitem>
     458            <para>
     459              <guilabel>Resulting intensities</guilabel>: Select if the plug-in generates
     460              regular or logged data.
     461            </para>
     462            </listitem>
     463          </itemizedlist>
     464         
     465          <para>
     466            Click <guibutton>Next</guibutton> to finish the wizard.
     467          </para>
     468         
     469        </listitem>
     470
     471        <listitem>
     472          <para>
     473            To check that the new plug-in works correctly, you need to
     474            have an experiment with some data. Go to the single-item
     475            view for a bioassay set and click on the <guibutton>Run
     476            analysis</guibutton> button. Select
     477            the <emphasis>Base1PluginExecuter</emphasis> plug-in. The
     478            list of configurations should include the newly installed
     479            plug-in. Select it and click on &gbNext;.
     480          </para>
     481        </listitem>
     482
     483        <listitem>
     484          <para>
     485            This will enter regular plug-in execution wizard and you
     486            will have to enter parameters needed by the plug-in.
     487          </para>
     488        </listitem>
     489
     490      </orderedlist>
     491
     492    </sect2>
     493     
     494   
     495    <sect2 id="plugins.installation.xjspcompiler">
     496      <title>Installing the X-JSP compiler</title>
     497      <para>
     498        Some extensions may want to use custom JSP files that also uses
     499        classes that are stored in the extension's JAR file. The problem
     500        with this is that Tomcat usually doesn't know to look for classes
     501        in the <filename>plugins.dir</filename> directory. To solve
     502        this problem BASE ships with a X-JSP compiler that can do this.
     503        This compiler has been mapped to files with a <code>.xjsp</code>
     504        extension, which are just regular JSP files with a different extension.
     505      </para>
     506     
     507      <para>
     508        The X-JSP compiler must be installed into Tomcat's internal
     509        library folder (<filename>$CATALINA_HOME/lib</filename>)
     510        since this is the only place where Tomcat look for compilers. The installation
     511        is easy. Simply copy <filename>&lt;base-dir&gt;/bin/jar/base-xjsp-compiler-3.x.jar</filename>
     512        to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat.
     513      </para>
     514     
     515      <note>
     516        <title>X-JSP is experimental</title>
     517        <para>
     518          This is an experimental feature that depends on internal functionality
     519          in Tomcat. It may or may not work with future versions of Tomcat.
     520          The compiler will most likely not work with other servlet
     521          containers.
     522        </para>
     523      </note>
     524    </sect2>
     525   
     526    <sect2 id="plugins.installation.disable">
     527      <title>Disable/enable plug-ins and extensions</title>
     528     
     529      <para>
     530        It is possible to disable specific extensions, extension point
     531        and or a plug-in without uninstalling the XML or JAR file.
     532        When you click on an item in the tree on the left-hand side of the
     533        screen a lot of detailed information about it will show up on the right-hand side.
     534        The right-hand side usually has a <guibutton>Disable</guibutton>
     535        or <guibutton>Disable all</guibutton> button in the toolbar. Click on that button
     536        to disable the plug-in, extension or all extensions
     537        for an extension point. The button will change to <guibutton>Enable</guibutton>
     538        or <guibutton>Enable all</guibutton> which lets you enable the extensions and
     539        plug-ins again.
     540      </para>
     541    </sect2>
     542
     543    <sect2 id="plugins.permissions">
     544      <title>Plug-in permissions</title>
     545 
     546      <helptext external_id="plugindefinition.edit.permissions"
     547        title="Edit plug-in permissions">
     548 
     549     
     550        <para>
     551          When a plug-in is executed the default is to give it the same
     552          permissions as the user that started it. This can be seen as a
     553          security risk if the plug-in is not trusted, or if someone manages
     554          to replace the plug-in code with their own code. A malicious plug-in can,
     555          for example, delete the entire database if invoked by the root user.
     556        </para>
    483557       
    484       </orderedlist>
    485      
    486 
     558        <para>
     559          To limit this problem it is possible to tune the permissions for
     560          a plug-in so that it only has permission to do things that it
     561          is supposed to do. For example, a plug-in that import reporters
     562          may only need permission to update and create new reporters and
     563          nothing else.
     564        </para>
     565     
     566        <nohelp>
     567        <para>
     568          To enable the permission system for a plug-in go the
     569          edit view of the plug-in and select the <guilabel>Permissions</guilabel>
     570          tab.
     571        </para>
     572       
     573        <figure id="plugins.figures.permissions">
     574          <title>Setting permissions on a plug-in</title>
     575          <screenshot>
     576            <mediaobject>
     577              <imageobject><imagedata
     578                fileref="figures/plugin_permissions.png" format="PNG"
     579                /></imageobject>
     580            </mediaobject>
     581          </screenshot>
     582        </figure>
     583        </nohelp>
     584 
     585        <variablelist>
     586        <varlistentry>
     587          <term><guilabel>Use permissions</guilabel></term>
     588          <listitem>
     589            <para>
     590              Select if the plug-in should use the permission system
     591              or not. If <guilabel>no</guilabel> is selected, the rest
     592              of the form is disabled.
     593            </para>
     594          </listitem>
     595        </varlistentry>
     596        <varlistentry>
     597          <term><guilabel>Item types</guilabel></term>
     598          <listitem>
     599            <para>
     600              The list contains all item types found in BASE that
     601              can have permissions set on them. The list is more or less the
     602              same as the permission list for roles.
     603              <nohelp>
     604                See <xref linkend="user_administration.roles.edit.permissions" />.
     605              </nohelp>
     606            </para>
     607          </listitem>
     608        </varlistentry>
     609        <varlistentry>
     610          <term><guilabel>Always grant</guilabel></term>
     611          <listitem>
     612            <para>
     613              The selected permissions will always be granted
     614              to the plug-in no matter if the logged in user had the
     615              permission to begin with or not. This makes it possible to
     616              develop a plug-in that allows users to do things that they
     617              are normally not allowed to do. The reporter importer is
     618              for example allowed to create and use reporter types.
     619            </para>
     620          </listitem>
     621        </varlistentry>
     622        <varlistentry>
     623          <term><guilabel>Always deny</guilabel></term>
     624          <listitem>
     625            <para>
     626              The selected permissions will always be denied
     627              to the plug-in no matter if the logged in user had the
     628              permission to begin with or not. The default is to always
     629              deny all permissions. Permissions that are not always
     630              denied and not always granted uses permissions from
     631              the logged in user.
     632            </para>
     633          </listitem>
     634        </varlistentry>
     635        <varlistentry>
     636          <term><guilabel>Requested by plug-in</guilabel></term>
     637          <listitem>
     638            <para>
     639              To make it easier for the server administrator
     640              to assign permissions, the plug-in developer can
     641              let the plug-in include a list of permissions that
     642              are needed. Plug-in developers are advised to
     643              only include the minimal set of permissions that are
     644              required for the plug-in to function. Click on the
     645              <guibutton>Use requested permissions</guibutton>
     646              button to give the plug-in the requested permissions.
     647            </para>
     648          </listitem>
     649        </varlistentry>
     650        </variablelist>
     651     
     652        <seeother>
     653          <other external_id="plugindefinition.edit">Plug-in properties</other>
     654          <other external_id="plugindefinition.jobagents">Job agents</other>
     655          <other external_id="role.edit.permissions">Role permissions</other>
     656        </seeother>   
     657      </helptext>
     658   
    487659    </sect2>
    488    
     660
    489661  </sect1>
    490662
    491   <sect1 id="plugins.permissions">
    492     <title>Plug-in permissions</title>
    493 
    494     <helptext external_id="plugindefinition.edit.permissions"
    495       title="Edit plug-in permissions">
    496 
    497    
    498       <para>
    499         When a plug-in is executed the default is to give it the same
    500         permissions as the user that started it. This can be seen as a
    501         security risk if the plug-in is not trusted, or if someone manages
    502         to replace the plug-in code with their own code. A malicious plugin can,
    503         for example, delete the entire database if invoked by the root user.
    504       </para>
    505      
    506       <para>
    507         To limit this problem it is possible to tune the permissions for
    508         a plug-in so that it only has permission to do things that it
    509         is supposed to do. For example, a plug-in that import reporters
    510         may only need permission to update and create new reporters and
    511         nothing else.
    512       </para>
    513    
    514       <nohelp>
    515       <para>
    516         To enable the permission system for a plug-in go the
    517         edit view of the plug-in and select the <guilabel>Permissions</guilabel>
    518         tab.
    519       </para>
    520      
    521       <figure id="plugins.figures.permissions">
    522         <title>Setting permissions on a plug-in</title>
    523         <screenshot>
    524           <mediaobject>
    525             <imageobject><imagedata
    526               fileref="figures/plugin_permissions.png" format="PNG"
    527               /></imageobject>
    528           </mediaobject>
    529         </screenshot>
    530       </figure>
    531       </nohelp>
    532 
    533       <variablelist>
    534       <varlistentry>
    535         <term><guilabel>Use permissions</guilabel></term>
    536         <listitem>
    537           <para>
    538             Select if the plug-in should use the permission system
    539             or not. If <guilabel>no</guilabel> is selected, the rest
    540             of the form is disabled.
    541           </para>
    542         </listitem>
    543       </varlistentry>
    544       <varlistentry>
    545         <term><guilabel>Item types</guilabel></term>
    546         <listitem>
    547           <para>
    548             The list contains all item types found in BASE that
    549             can have permissions set on them. The list is more or less the
    550             same as the permission list for roles.
    551             <nohelp>
    552               See <xref linkend="user_administration.roles.edit.permissions" />.
    553             </nohelp>
    554           </para>
    555         </listitem>
    556       </varlistentry>
    557       <varlistentry>
    558         <term><guilabel>Always grant</guilabel></term>
    559         <listitem>
    560           <para>
    561             The selected permissions will always be granted
    562             to the plug-in no matter if the logged in user had the
    563             permission to begin with or not. This makes it possible to
    564             develop a plugin that allows users to do things that they
    565             are normally not allowed to do. The reporter importer is
    566             for example allowed to create and use reporter types.
    567           </para>
    568         </listitem>
    569       </varlistentry>
    570       <varlistentry>
    571         <term><guilabel>Always deny</guilabel></term>
    572         <listitem>
    573           <para>
    574             The selected permissions will always be denied
    575             to the plug-in no matter if the logged in user had the
    576             permission to begin with or not. The default is to always
    577             deny all permissions. Permissions that are not always
    578             denied and not always granted uses permissions from
    579             the logged in user.
    580           </para>
    581         </listitem>
    582       </varlistentry>
    583       <varlistentry>
    584         <term><guilabel>Requested by plug-in</guilabel></term>
    585         <listitem>
    586           <para>
    587             To make it easier for the server administrator
    588             to assign permissions, the plug-in developer can
    589             let the plug-in include a list of permissions that
    590             are needed. Plug-in developers are advised to
    591             only include the minimal set of permissions that are
    592             required for the plug-in to function. Click on the
    593             <guibutton>Use requested permissions</guibutton>
    594             button to give the plug-in the requested permissions.
    595           </para>
    596         </listitem>
    597       </varlistentry>
    598       </variablelist>
    599    
    600       <seeother>
    601         <other external_id="plugindefinition.edit">Plug-in properties</other>
    602         <other external_id="plugindefinition.jobagents">Job agents</other>
    603         <other external_id="role.edit.permissions">Role permissions</other>
    604       </seeother>   
    605     </helptext>
    606    
    607    
    608   </sect1>
    609 
    610 
    611   <sect1 id="plugins.jobagents">
    612     <title>Job agents</title>
    613     <para>
    614       Job agents are used for executing plug-ins on external
    615       computers. Using job agents will free up resources on the BASE
    616       application server, and allow the server to concentrate on
    617       serving web pages. Job agents are optional and must be installed
    618       separately. See <xref linkend="installation_upgrade.jobagents"
    619       /> for more information about setting up job agents. This
    620       section assumes that at least one job agent is setup to serve
    621       your BASE installation.
    622     </para>
    623    
    624     <para>
    625       A job agent will not execute a plug-in unless the administrator
    626       has configured the job agent to do so. This can be done either
    627       from the plug-in pages or from the job agent pages. To register
    628       a plug-in with one or more job agents from the plug-in pages, go
    629       to the edit view of the plug-in and select the <guilabel>Job
    630       agents</guilabel> tab. To do the same from the job agent pages,
    631       go to the edit view of the job agent and select
    632       the <guilabel>Plugins</guilabel> tab. The registration dialogs
    633       are very similar but only the plug-in side of registration is
    634       described here, the job agent route is described in
    635       <xref linkend="installation_upgrade.jobagents" />.
    636     </para>
    637    
    638     <figure id="plugins.figures.jobagents">
    639       <title>Select job agents for a plug-in</title>
    640       <screenshot>
    641         <mediaobject>
    642           <imageobject><imagedata
    643             scalefit="1" width="100%"
    644             fileref="figures/plugin_jobagents.png" format="PNG"
    645             /></imageobject>
    646         </mediaobject>
    647       </screenshot>
    648     </figure>
    649    
    650     <helptext external_id="plugindefinition.jobagents"
    651       title="Job agents">
    652      
    653       <para>
    654         Use this tab to specify which job agents the plug-in is
    655         installed and allowed to be executed on.
    656       </para>
    657      
    658       <variablelist>
    659       <varlistentry>
    660         <term><guilabel>Run this plugin on</guilabel></term>
    661         <listitem>
    662           <para>
    663             You may select if the internal job queue should execute the
    664             plug-in or not.
    665           </para>
    666         </listitem>
    667       </varlistentry>
    668       <varlistentry>
    669         <term><guilabel>Job agents</guilabel></term>
    670         <listitem>
    671           <para>
    672             A list with the job agents where the plug-in is installed and
    673             allowed to be executed. Select a plug-in in this list to display
    674             more configuration options for the plug-in.
    675           </para>
    676         </listitem>
    677       </varlistentry>
    678       <varlistentry>
    679         <term><guilabel>Add job agents</guilabel></term>
    680         <listitem>
    681           <para>
    682             Use this button to open a pop-up window for selecting
    683             job agents.
    684           </para>
    685         </listitem>
    686       </varlistentry>
    687       <varlistentry>
    688         <term><guilabel>Remove</guilabel></term>
    689         <listitem>
    690           <para>
    691             Remove the selected plug-in from the list.
    692           </para>
    693         </listitem>
    694       </varlistentry>
    695       </variablelist>
    696      
    697       <para>
    698         The following properties are only displayed when a
    699         job agent has been selected in the list. Each job agent may have it's
    700         own settings of these properties. If you leave the values unspecified
    701         the job agent will use the default values specified on the
    702         <guilabel>Plugin</guilabel> tab.
    703       </para>
    704      
    705       <variablelist>
    706       <varlistentry>
    707         <term><guilabel>Jar path</guilabel></term>
    708         <listitem>
    709           <para>
    710             The path on the external server to the JAR file containing the
    711             plug-in code. If not specified the same path as on the web server
    712             is used.
    713           </para>
    714         </listitem>
    715       </varlistentry>
    716       <varlistentry>
    717         <term><guilabel>Max memory</guilabel></term>
    718         <listitem>
    719           <para>
    720             The maximum amount of memory the plug-in is allowed to use.
    721             Add around 40MB for the Java run-time environment and BASE.
    722             If not specified Java will choose it's default value which is 64MB.
    723           </para>
    724         </listitem>
    725       </varlistentry>
    726       <varlistentry>
    727         <term><guilabel>Trusted</guilabel></term>
    728         <listitem>
    729           <para>
    730             If the plug-in should be executed in a protected or
    731             unprotected environment. Currently, BASE only supports
    732             running plug-ins in an unprotected environment.
    733           </para>
    734         </listitem>
    735       </varlistentry>
    736       <varlistentry>
    737         <term><guilabel>Priority boost</guilabel></term>
    738         <listitem>
    739           <para>
    740             Used to give a plug-in higher priority in the queue.
    741             Values between 0 and 10 are allowed. A higher value will
    742             give the plug-in higher priority. The priority boost is useful
    743             if we, for example, want to use one server mainly for importing
    744             data. By giving all import plugins a priority boost they will
    745             be executed before all other jobs, which will have to wait
    746             until there are no more waiting imports.
    747           </para>
    748         </listitem>
    749       </varlistentry>
    750       </variablelist>
    751      
    752       <seeother>
    753         <other external_id="plugindefinition.edit">Plug-in properties</other>
    754         <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
    755       </seeother>
    756     </helptext>
    757   </sect1>
    758663 
    759664  <sect1 id="plugins.configuration">
    … …  
    774679      <menuchoice>
    775680        <guimenu>Administrate</guimenu>
    776         <guisubmenu>Plugins</guisubmenu>
    777         <guimenuitem>Configurations</guimenuitem>
     681        <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     682        <guimenuitem>Plug-in configurations</guimenuitem>
    778683      </menuchoice>
    779       page.
     684      page or from the single-item view page of each plug-in.
    780685    </para>
    781686   
    … …  
    959864      <note>
    960865        <title>Do not go back</title>
     866        <para>
    961867        It is not possible to go backwards in the wizard.
    962868        If you try it will most likely result in an
    963869        unexpected error and the configuration must be restarted
    964870        from the beginning.
     871        </para>
    965872      </note>
    966873     
    … …  
    979886        BASE ships with one importer and one exporter that allows
    980887        you to import and export plug-in configurations. This makes
    981         it easy to copy configurations between servers. The BASE website
    982         also has a <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/admin/plugin_configuration/coreplugins.html"
    983         >page where you can download additional configurations</ulink>
    984         not included in the main distribution.
     888        it easy to copy configurations between servers.
    985889      </para>
    986890     
    … …  
    990894        <menuchoice>
    991895          <guimenu>Administrate</guimenu>
    992           <guisubmenu>Plugins</guisubmenu>
    993           <guimenuitem>Configurations</guimenuitem>
     896          <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     897          <guimenuitem>Plug-in configurations</guimenuitem>
    994898        </menuchoice>
    995899      </para>
    … …  
    14631367    </sect2>
    14641368
    1465     <sect2 id="plugins.configuration.base1">
    1466       <title>Configuring Base1PluginExecuter</title>
    1467       <para>
    1468         BASE version 1 plug-ins are supported through the use of
    1469         the <emphasis>Base1PluginExecuter</emphasis> plug-in. Each
    1470         BASE version 1 plug-in must have at least one
    1471         Base1PluginExecuter configuration to work. To install a BASE
    1472         version 1 plug-in follow these instructions:
    1473       </para>
    1474      
    1475       <orderedlist>
    1476         <listitem>
    1477         <para>
    1478           Install the BASE version plug-in package as outlined in
    1479           <xref linkend="plugins.installation.base1" />
    1480         </para>
    1481         </listitem>
    1482 
    1483         <listitem>
    1484         <para>
    1485           Upload the <filename>*.base</filename> file for the BASE
    1486           version 1 plug-in. If you cannot find the file, you can let
    1487           your BASE version 1 server create one for you. In your BASE
    1488           version 1 installation go to
    1489           <menuchoice>
    1490             <guimenu>Analyze data</guimenu>
    1491             <guimenuitem>Plug-ins</guimenuitem>
    1492           </menuchoice>
    1493           and use the <guilabel>Export</guilabel> function. This will
    1494           create a configuration file for your BASE version 1 plug-in
    1495           that you can upload to your new BASE server.
    1496         </para>
    1497         </listitem>
    1498 
    1499         <listitem>
    1500           <para>
    1501             Create a new plug-in configuration using, for example,
    1502             the <guibutton>New configuration</guibutton> button in
    1503             single-item view for
    1504             the <emphasis>Base1PluginExecuter</emphasis> plug-in.
    1505           </para>
    1506         </listitem>
    1507 
    1508         <listitem>
    1509           <para>
    1510             Start the configuration wizard and select
    1511             the <filename>*.base</filename> file describing the BASE
    1512             version 1 plug-in and enter the path and file name to the
    1513             location of the executable.
    1514           </para>
    1515         </listitem>
    1516 
    1517         <listitem>
    1518           <para>
    1519             To check that the new plug-in works correctly, you need to
    1520             have an experiment with some data. Go to the single-item
    1521             view for a bioassay set and click on the <guibutton>Run
    1522             analysis</guibutton> button. Select
    1523             the <emphasis>Base1PluginExecuter</emphasis> plug-in. The
    1524             list of configurations should include the newly installed
    1525             plug-in. Select it and click on &gbNext;.
    1526           </para>
    1527         </listitem>
    1528 
    1529         <listitem>
    1530           <para>
    1531             This will enter regular plug-in execution wizard and you
    1532             will have to enter parameters needed by the plug-in.
    1533           </para>
    1534         </listitem>
    1535 
    1536       </orderedlist>
    1537 
    1538     </sect2>
    1539  
    15401369  </sect1>
    15411370 

  • trunk/doc/src/docbook/appendix/web.xml.xml

    r5678 r5737  
    168168        files to a compiler that includes the extension supplied JAR file(s)
    169169        in the class path. Can be disabled if no extensions use this feature.
    170         See also <xref linkend="admin.extensions.xjspcompiler" /> for more information
     170        See also <xref linkend="plugins.installation.xjspcompiler" /> for more information
    171171        about how to enable this feature.
    172172        </para>

  • trunk/doc/src/docbook/developerdoc/api_overview.xml

    r5525 r5737  
    34643464        which are regular JSP files with a different extension. This feature is
    34653465        experimental and requires installing an extra JAR into Tomcat's lib
    3466         directory. See <xref linkend="admin.extensions.xjspcompiler" /> for
     3466        directory. See <xref linkend="plugins.installation.xjspcompiler" /> for
    34673467        more information.
    34683468      </para>

  • trunk/doc/src/docbook/developerdoc/extensions.xml

    r5654 r5737  
    4848      extensions. From this page, if you are logged in with enough permissions,
    4949      it is also possible to configure the extensions system, enable/disable
    50       extensions, etc. Read more about this in <xref linkend="admin.extensions" />.
     50      extensions, etc. Read more about this in <xref linkend="plugins" />.
    5151    </para>
    5252
    … …  
    6363      <listitem>
    6464        <para>
    65         <xref linkend="admin.extensions" />.
     65        <xref linkend="plugins" />.
    6666        </para>
    6767      </listitem>
    … …  
    913913          X-JSP compiler is installed into Tomcat's internal <filename>/lib</filename>
    914914          directory. It is an optional step and not all BASE installations
    915           may have the compiler installed. See <xref linkend="admin.extensions.xjspcompiler" />.
     915          may have the compiler installed. See <xref linkend="plugins.installation.xjspcompiler" />.
    916916        </para>
    917917      </note>

  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r5654 r5737  
    190190        the auto-installation wizard. The wizard makes it very easy for a
    191191        server administrator to install new plug-ins. See
    192         <xref linkend="plugins.autoinstall" />.
     192        <xref linkend="plugins.installation.wizard" />.
    193193      </para>
    194194     

  • trunk/lib/docbook/custom-styles/docbook/plain/css/docbook.css

    r5678 r5737  
    233233}
    234234
    235 div.warning div.tip {
     235div.warning div.tip, div.important div.note {
    236236  background-color: #ffffff;
    237237}

  • trunk/www/admin/extensions/wizard.jsp

    r5616 r5737  
    9494  <input type=hidden name="cmd" value="DoManualScan">
    9595 
    96   <h3 class="docked">Extensions and plug-ins installation wizard <base:help helpid="extensions.manualscan" /></h3>
     96  <h3 class="docked">Extensions and plug-ins installation wizard <base:help helpid="extensions.install-wizard" /></h3>
    9797  <tbl:table id="extensions" clazz="itemlist">
    9898    <tbl:columndef id="file" title="File" />
Note: See TracChangeset for help on using the changeset viewer.