Changeset 3689


Ignore:
Timestamp:
Aug 20, 2007, 12:04:48 PM (16 years ago)
Author:
Jari Häkkinen
Message:

Fixes #615.

Location:
trunk/doc
Files:
1 deleted
1 edited

Legend:

Unmodified
Added
Removed

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

    r3679 r3689  
    3030  <?dbhtml dir="installation_upgrade"?>
    3131
    32   <title>Installation, migration, and upgrade instructions</title>
     32  <title>Installation, setup, migration, and upgrade instructions</title>
    3333
    3434  <note>
    … …  
    3838
    3939  <para>
    40     This chapter is divided into three parts. First, the process of
    41     upgrading a BASE 2 server is described. It is assumed that there
    42     is a running server. Then, the first time installation
    43     instructions follows, and the chapter is concluded with
    44     information on how to migrate data from a BASE 1.2.17 server to a
    45     BASE 2 server.
     40    This chapter is divided into four parts. First, the process of
     41    upgrading a BASE 2 server is described. Followed by set up of job
     42    agents. (For these two first parts it is assumed that there is a
     43    running server.) Then, the first time installation instructions
     44    follows, and the chapter is concluded with information on how to
     45    migrate data from a BASE 1.2.17 server to a BASE 2 server.
    4646  </para>
    4747
    4848  <para>
    49     The first time installation is expected to be performed only once,
    50     and optionally followed by a migration. The migration can only be
     49    The first time installation is only to be performed once,
     50    optionally followed by a migration. The migration can only be
    5151    done to a pristine (empty) BASE 2 server, and migration from
    5252    several BASE 1 installations to one BASE 2 server is not
    … …  
    159159                <para>
    160160                  This option is for advanced users only and is not
    161                   covered here. Please refer
    162                   to <ulink
    163                   url="http://base.thep.lu.se/chrome/site/doc/development/build.html">the
    164                   building BASE document</ulink> for information on
     161                  covered here. Please refer to
     162                  <xref linkend="core_ref.build"/> for information on
    165163                  this download option.
    166164                </para>
    … …  
    251249
    252250
     251  <sect1 id="installation_upgrade.jobagents">
     252    <title>Installing job agents</title>
     253
     254    <para>
     255      It is important to understand that the BASE application can be
     256      spread on to several computers. The main BASE application is
     257      serving HTTP requests, the underlying database engine is
     258      providing storage and persistence of data, and job agents can be
     259      installed on computers that will serve the BASE installation
     260      with computing power and perform analysis and run plug-in. In a
     261      straight forward setup one computer provides all services needed
     262      for running BASE. From this starting point it is easy to add
     263      computers to shares load from the BASE server by installing job
     264      agents on these additional computers.
     265    </para>
     266
     267    <para>
     268      A job agent is a program running on a computer regularly
     269      checking the BASE job queue for jobs awaiting execution. When
     270      the job agent finds a job that it is enabled to execute, it
     271      loads the plugin and executes it. Job agents will in this way
     272      free up resources on the BASE application server, and thus allow
     273      the BASE server to concentrate on serving web pages. Job agents
     274      are optional and must be installed and setup
     275      separately. However, BASE is prepared for job agent setup and to
     276      utilize the agents, but the agent are not required.
     277    </para>
     278
     279    <para>
     280      A job agent supports many configuration options that are not
     281      supported by the internal job queue. For example, you can
     282      <itemizedlist>
     283        <listitem>
     284          <para>
     285            Specify exactly which plugins each job agent should be
     286            able to execute.
     287          </para>
     288        </listitem>
     289        <listitem>
     290          <para>
     291            Give some plugins higher priority than other plugins.
     292          </para>
     293        </listitem>
     294        <listitem>
     295          <para>
     296            Specify which users/groups/projects should be able to use
     297            a specific job agent.
     298          </para>
     299        </listitem>
     300        <listitem>
     301          <para>
     302            Override memory settings and more for each plugin.
     303          </para>
     304        </listitem>
     305        <listitem>
     306          <para>
     307            Execute plugins in separate processes. Thus, a misbehaving
     308            plugin cannot bring the main application server down.
     309          </para>
     310        </listitem>
     311        <listitem>
     312          <para>
     313            Add more computers with job agents as needed.
     314          </para>
     315        </listitem>
     316      </itemizedlist>
     317      All these options make it possible to create a very flexible
     318      setup. For example one job agent can be assigned for importing
     319      data only, another job agent can be assigned for running
     320      analysis plugins for specific project only, and a third may be a
     321      catch-all job agent that performs all low-priority jobs.
     322    </para>
     323
     324    <sect2 id="installation_upgrade.jobagents.serverside">
     325      <title>BASE application server side setup</title>
     326      <para>
     327        <variablelist>
     328          <varlistentry>
     329            <term>Disable the internal job queue</term>
     330            <listitem>
     331              <para>
     332                It is not recommended to use the internal job queue
     333                when job agents are used. The
     334                setting <command>jobqueue.internal.enabled</command>
     335                should be changed to <command>false</command> for the
     336                BASE server. This setting is found in
     337                the <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
     338                file. The changes will not take effect until the
     339                application server is restarted.
     340              </para>
     341            </listitem>
     342          </varlistentry>
     343          <varlistentry>
     344            <term id="installation_upgrade.jobagent.user_account">Enable the job agent user account</term>
     345            <listitem>
     346              <para>
     347                During installation of BASE a user account is created
     348                for the job agent. This account is used by the job
     349                agents to log on to BASE. The account is disabled by
     350                default and must be enabled. Enable the account and
     351                set a password. This password is set in the
     352                <filename>jobagent.properties</filename> file, see
     353                item
     354                <xref linkend="installation_upgrade.jobagent.client.properties"/>
     355                below.
     356              </para>
     357            </listitem>
     358          </varlistentry>
     359        </variablelist>
     360      </para>
     361    </sect2>
     362
     363    <sect2 id="installation_upgrade.jobagents.database">
     364      <title>Database server setup</title>
     365      <para>
     366        <variablelist>
     367          <varlistentry>
     368            <term id="installation_upgrade.jobagent.database">Create a user account on the database</term>
     369            <listitem>
     370              <para>
     371                This is the similar to granting database access for
     372                the BASE server user in the in the regular BASE
     373                installation, cf.
     374                <xref
     375                linkend="installation_upgrade.installation.database"/>.
     376                You must create an account in the database that is
     377                allowed to connect from the job agent server. MySQL
     378                example:
     379<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
     380GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
     381
     382                Replace <command>job.agent.host</command> with the
     383                host name of the server that is going to run the job
     384                agent. You should also set password. This password is
     385                used in item
     386                <xref linkend="installation_upgrade.jobagent.client.config"/>
     387                below in job agent server setup. You can use the same
     388                database user and password as in the regular database
     389                setup.
     390              </para>
     391            </listitem>
     392          </varlistentry>
     393        </variablelist>
     394      </para>
     395    </sect2>
     396
     397    <sect2 id="installation_upgrade.jobagents.client">
     398      <title>Job agent client setup</title>
     399      <para>
     400        <variablelist>
     401          <varlistentry>
     402            <term>Download and unpack a regular BASE 2 distribution</term>
     403            <listitem>
     404              <para>
     405                You <emphasis>must</emphasis> use the same version on
     406                the web server and all job agents. You find the
     407                downloads at
     408                <ulink
     409                url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
     410              </para>
     411            </listitem>
     412          </varlistentry>
     413          <varlistentry>
     414            <term id="installation_upgrade.jobagent.client.config">Edit the <filename>base.config</filename> file</term>
     415            <listitem>
     416              <para>
     417                The <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
     418                file must be configured as in regular BASE
     419                installation, cf.
     420                <xref
     421                linkend="installation_upgrade.installation.configuration"/>,
     422                to use the same database as the web server
     423                application. The most important settings are
     424                <itemizedlist>
     425                  <listitem>
     426                    <para>
     427                      <command>db.username</command>: The database
     428                      user you created in item
     429                      <xref
     430                      linkend="installation_upgrade.jobagent.database"/>
     431                      above.
     432                    </para>
     433                  </listitem>
     434                  <listitem>
     435                    <para>
     436                      <command>db.password</command>: The password for
     437                      the user.
     438                    </para>
     439                  </listitem>
     440                  <listitem>
     441                    <para>
     442                      <command>db.url</command>: The connection url to
     443                      the database.
     444                    </para>
     445                  </listitem>
     446                  <listitem>
     447                    <para>
     448                      <command>userfile</command>: The path to the
     449                      directory where user files are located. This
     450                      directory must be accessible from all job
     451                      agents, i.e., by nfs or other file system
     452                      sharing method.
     453                    </para>
     454                  </listitem>
     455                </itemizedlist>
     456                See the <xref linkend="appendix.base.config"/> for
     457                more information about the settings in
     458                the <filename>base.config</filename> file.
     459              </para>
     460            </listitem>
     461          </varlistentry>
     462          <varlistentry>
     463            <term id="installation_upgrade.jobagent.client.properties">Edit
     464            the <filename>jobagent.properties</filename> file</term>
     465            <listitem>
     466              <para>
     467                The <filename>/path/to/base/www/WEB-INF/classes/jobagent.properties</filename>
     468                file contains settings for the job agent. The most
     469                important ones to specify value for are
     470                <itemizedlist>
     471                  <listitem>
     472                    <para>
     473                      <command>agent.password</command>: The password
     474                      you set for the job agent user account in item
     475                      <xref
     476                      linkend="installation_upgrade.jobagent.user_account"/>
     477                      above.
     478                    </para>
     479                  </listitem>
     480                  <listitem>
     481                    <para>
     482                      <command>agent.id</command>: An ID that must be
     483                      unique for each job agent accessing the BASE application.
     484                    </para>
     485                  </listitem>
     486                  <listitem>
     487                    <para>
     488                      <command>agent.remotecontrol</command>: The
     489                      name/ip address of the web server if you want it
     490                      to be able to display info about running
     491                      jobs. The job agent will only allow connections
     492                      from computers specified in this setting.
     493                    </para>
     494                  </listitem>
     495                </itemizedlist>
     496              </para>
     497              <para>
     498                The <filename>jobagent.properties</filename> file
     499                contains many more configuration options. See
     500                the <xref linkend="appendix.jobagent.properties"/> for
     501                more information.
     502              </para>
     503            </listitem>
     504          </varlistentry>
     505          <varlistentry>
     506            <term>Register the job agent</term>
     507            <listitem>
     508              <para>
     509                From the <filename>bin</filename> directory, register
     510                the job agent with
     511                <programlisting>./jobagent.sh register</programlisting>
     512              </para>
     513            </listitem>
     514          </varlistentry>
     515          <varlistentry>
     516            <term>Start the job agent</term>
     517            <listitem>
     518              <para>
     519                From the <filename>bin</filename> directory, start the
     520                job agent with
     521                <programlisting>./jobagent.sh start &amp;</programlisting>
     522              </para>
     523              <para>
     524                See the <xref linkend="appendix.jobagent.sh"/>
     525                reference for more information about what you can do
     526                with the job agent command line interface.
     527              </para>
     528            </listitem>
     529          </varlistentry>
     530        </variablelist>
     531      </para>
     532    </sect2>
     533
     534    <sect2 id="installation_upgrade.jobagents.configuration">
     535      <title>Configuring the job agent</title>
     536      <para>
     537        Before the job agent starts executing jobs for you it must be
     538        configured. The configuration is done through the BASE web
     539        interface.
     540        <variablelist>
     541          <varlistentry>
     542            <term>Configure the plugins the job agent should handle</term>
     543            <listitem>
     544              <para>
     545                <itemizedlist>
     546                  <listitem>
     547                    <para>
     548                      Go to the
     549                      <menuchoice>
     550                        <guimenu>Administrate</guimenu>
     551                        <guisubmenu>Plugins</guisubmenu>
     552                        <guimenuitem>Job agents</guimenuitem>
     553                      </menuchoice> menu.
     554                    </para>
     555                  </listitem>
     556                  <listitem>
     557                    <para>
     558                      Select the job agent and click on the &gbEdit;
     559                      button.
     560                    </para>
     561                  </listitem>
     562                  <listitem>
     563                    <para>
     564                      On the <guilabel>Plugins</guilabel> tab you can
     565                      specify which plugins the job agent should
     566                      handle. Note that if you have installed external
     567                      plugins on the web server, those plugins must be
     568                      installed on the job agent as well. It is
     569                      possible to specify different paths to the JAR
     570                      file for each job agent.
     571                    </para>
     572                  </listitem>
     573                </itemizedlist>
     574              </para>
     575            </listitem>
     576          </varlistentry>
     577          <varlistentry>
     578            <term>Grant users access to the job agent</term>
     579            <listitem>
     580              <para>
     581                Use the regular <guilabel>Share</guilabel>
     582                functionality to specify which users/groups/projects
     583                should be able to use the job agent. You must give
     584                them at least <command>USE</command> permission.
     585              </para>
     586            </listitem>
     587          </varlistentry>
     588        </variablelist>
     589      </para>
     590    </sect2>
     591
     592  </sect1>      <!-- job agent setup -->
     593
     594
    253595  <sect1 id="installation_upgrade.installation">
    254596    <title>Installation instructions</title>
    … …  
    264606            download the JDK version (<emphasis>not</emphasis> the JRE
    265607            version). <command>Java 6 is currently not
    266             supported</command>.
     608            supported</command> (this will change starting with
     609            BASE version 2.5 whereafter only Java 6 will be supported).
    267610          </para>
    268611        </listitem>
    … …  
    400743
    401744      <varlistentry>
    402         <term>BASE (database engine)</term>
     745        <term id="installation_upgrade.installation.database">BASE (database engine)</term>
    403746        <listitem>
    404747          <para>
    … …  
    497840
    498841      <varlistentry>
    499         <term>BASE (configuration)</term>
     842        <term id="installation_upgrade.installation.configuration">BASE (configuration)</term>
    500843        <listitem>
    501844          <para>
    … …  
    522865              </listitem>
    523866            </itemizedlist>
     867            See the <xref linkend="appendix.base.config"/> for more
     868            information about the settings in
     869            the <filename>base.config</filename> file.
    524870          </para>
    525871          <para>
    … …  
    8061152  </sect1>      <!-- Migration instructions -->
    8071153
    808 
    809 
    810   <sect1 id="installation_upgrade.jobagents">
    811     <title>Installing job agents</title>
    812     <para>TODO</para>
    813   </sect1>
    814 
    8151154</chapter>
Note: See TracChangeset for help on using the changeset viewer.