source: trunk/doc/admin/jobagent.html @ 3675

Last change on this file since 3675 was 3675, checked in by Jari Häkkinen, 15 years ago

Fixing copyright statements. Fixing svn properties.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 8.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
3<!--
4    $Id: jobagent.html 3675 2007-08-16 14:16:43Z jari $
5
6    Copyright (C) 2006 Nicklas Nordborg
7
8    This file is part of BASE - BioArray Software Environment.
9    Available at http://base.thep.lu.se/
10
11    BASE is free software; you can redistribute it and/or modify it
12    under the terms of the GNU General Public License as published by
13    the Free Software Foundation; either version 2 of the License, or
14    (at your option) any later version.
15
16    BASE is distributed in the hope that it will be useful, but
17    WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    General Public License for more details.
20
21    You should have received a copy of the GNU General Public License
22    along with this program; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24    02111-1307, USA.
25-->
26
27<html>
28  <head>
29    <title>BASE 2.0 - Administrator documentation: Adding job agents</title>
30  <link rel=stylesheet type="text/css" href="../styles.css">
31  </head>
32<body>
33
34<div class="navigation">
35  <a href="../index.html">BASE</a>
36  <img src="../next.gif">
37  <a href="index.html">Administrator documentation</a>
38  <img src="../next.gif">
39  Adding job agents
40</div>
41
42<h1>BASE 2.0 - Administrator documentation: Adding job agents</h1>
43
44<div class="abstract">
45
46  <p>
47  This document describes how to configure and install job agents.
48  </p>
49
50  <b>Contents</b><br>
51  <ol>
52  <li><a href="#whatisit">What is a job agent?</a>
53  <li><a href="#install">How to install a job agent</a>
54    <ol>
55    <li><a href="#doweb">Things to do on the web server</a>
56    <li><a href="#dodatabase">Things to do on the database server</a>
57    <li><a href="#doagent">Things to do on the job agent server</a>
58    </ol>
59  <li><a href="#configure">Configuring the job agent</a>
60  </ol>
61
62  <b>See also</b>
63  <ul>
64  <li><a href="jobagent.properties.html">jobagent.properties reference</a>
65  <li><a href="jobagent.sh.html">jobagent.sh reference</a>
66  <li><a href="base.config.html">base.config reference</a>
67  </ul>
68
69
70  <p class="authors">
71  <b>Last updated:</b> $Date: 2007-08-16 14:16:43 +0000 (Thu, 16 Aug 2007) $<br>
72  <b>Copyright &copy;</b> 2006 The respective authors. All rights reserved.
73  </p>
74
75</div>
76
77  <a name="whatisit"></a>
78  <h2>1. What is a job agent?</h2>
79 
80  <p>
81    A job agent is a program running on another computer that is regularly
82    checking the BASE job queue for jobs that are awaiting execution. When
83    the job agent finds a job that it is able to execute it loads the plugin
84    and executes it.
85  </p>
86 
87  <p>
88    A job agent supports lots of configuration options that are not supported
89    by the internal job queue. For example, you can:
90  </p>
91 
92  <ul>
93  <li>Specify exactly which plugins each job agent should be able to execute.
94  <li>Give some plugins higher priority than others.
95  <li>Specify which users/groups/projects that should be able to use the job
96    agent.
97  <li>Override memory settings, etc. for each plugin.
98  <li>Execute plugins in separate processes. Thus, a misbehaving plugin doesn't
99    bring the web server down with it.
100  <li>Add more computers with more job agents if the need arises.
101  </ul>
102 
103  <p>
104    All these options make it possible to create a very flexible setup. For
105    example one job agent can be assigned for importing data only. Another job
106    agent can be assigned for running analysis plugins for specific project
107    only. A third may be a catch-all job agent that does all low-priority jobs.
108  </p>
109 
110
111  <a name="install"></a>
112  <h2>2. How to install a job agent</h2>
113 
114  <p>
115    It is not very difficult to install a job agent, but it requires some
116    manual configuration. Therefore, no job agent is installed by default.
117    Here is how to do it:
118  </p>
119
120  <a name="doweb"></a>
121  <h3>2.1 Things to do on the web server</h3>
122
123  <dl>
124  <dt>1. Disable the internal job queue on the web server</dt>
125  <dd>
126    We don't recommend using the internal job queue at the same time
127    as job agents. The setting <code>jobqueue.internal.enabled</code>
128    should be changed to <code>false</code> for the web server. This setting
129    is found in the <code>www/WEB-INF/classes/base.config</code> file. After
130    you have changed the setting the web server must be restarted.
131  </dd>
132 
133  <dt>2. Enable the job agent user account</dt>
134  <dd>
135    The default installation creates a user account that the job agent
136    uses to log in to BASE. This user account is disabled by default. You must
137    enable the account and give it a password. This password goes into the
138    <code>jobagent.properties</code> file in step 2.3.3 below.
139  </dd>
140  </dl>
141 
142  <a name="dodatabase"></a>
143  <h3>2.2 Things to do on the database server</h3>
144
145  <dl>
146  <dt>1. Create a user account on the database</dt>
147  <dd>
148    This is the same step as step iv) in the regular BASE installation. You must
149    create an account in the database that is allowed to connect from the
150    job agent server. MySQL example:
151   
152    <pre class="code">
153GRANT ALL ON base2.* TO base2user@job.agent.host IDENTIFIED BY 'password';
154GRANT ALL ON base2dynamic.* TO base2user@job.agent.host;
155</pre>
156
157    Replace <code>job.agent.host</code> with the host name of the
158    server that is going to run the job agent. You should also change the
159    password. This password goes into the <code>base.config</code> file
160    in step 2.3.2 below.
161  </dd>
162  </dl>
163
164  <a name="doagent"></a>
165  <h3>2.3 Things to do on the job agent server</h3>
166
167  <dl>
168  <dt>1. Download and unpack the regular BASE 2 distribution</dt>
169  <dd>
170    You must use the same version on the web server and all
171    job agents. You find the downloads here:
172    <a href="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</a>
173  </dd>
174
175  <dt>2. Edit the <code>base.config</code> file</dt>
176  <dd>
177    The <code>www/WEB-INF/classes/base.config</code> file must be configured
178    to use the same database as the web server application. The most
179    important settings are:
180    <ul>
181    <li>db.username: The database user you added in step 2.2.1
182    <li>db.password: The password for the user
183    <li>db.url: The connection url to the database
184    <li>userfile: The path to the directory where user files are located. This directory
185      must be accessible from all job agents.
186    </ul>
187   
188    See the <a href="base.config.html">base.config reference</a>
189    for more information about the settings in this file.
190  </dd>
191 
192  <dt>3. Edit the <code>jobagent.properties</code> file</dt>
193  <dd>
194    The <code>www/WEB-INF/classes/jobagent.properties</code> file contains settings for
195    the job agent. The most important ones to specify value for are:
196   
197    <ul>
198    <li>agent.password: The password you gave to the job agent user account in step 2.1.2
199      above.
200    <li>agent.id: An ID that must be unique for each job agent
201    <li>agent.remotecontrol: The name/ip address of the web server if you want it to be
202      able to display info about running jobs. The job agent will only allow connections
203      from computers specified in this setting.
204    </ul>
205   
206    <p>
207      The <code>jobagent.properties</code> file contains many more configuration
208      options. See the <a href="jobagent.properties.html"><code>jobagent.properties</code>
209      reference</a> for more information.
210    </p>
211   
212  </dd>
213 
214  <dt>4. Register the job agent</dt>
215  <dd>
216    From the <code>bin</code> directory, register the job agent with
217    <pre class="code">
218./jobagent.sh register
219</pre>
220  </dd>
221 
222  <dt>5. Start the job agent</dt>
223  <dd>
224    From the <code>bin</code> directory, start the job agent with
225    <pre class="code">
226./jobagent.sh start &
227</pre>
228
229  <p>
230    See the <a href="jobagent.sh.html">jobagent.sh reference</a> for
231    more information about what you can do with the command line
232    interface.
233  </p>
234   
235  </dd>
236  </dl>
237 
238  <a name="configure"></a>
239  <h2>3. Configuring the job agent</h2>
240 
241  <p>
242    Before the job agent starts executing jobs for you it must be configured.
243    The configuration is done through the web interface.
244  </p>
245 
246  <dl>
247  <dt>1. Configure the plugins the job agent should handle</dt>
248  <dd>
249    <ul>
250    <li>Go to the <code>Administrate -> Plugins -> Job agents</code> menu.
251    <li>Select the job agent and click on the <code>Edit</code> button.
252    <li>On the <code>Plugins</code> tab you can specify which plugins the
253      job agent should handle. Note that if you have installed external
254      plugins on the web server, those plugins must be installed on the
255      job agent as well. It is possible to specify different paths to the
256      JAR file for each job agent.
257    </ul>
258  </dd>
259 
260  <dt>2. Give users access to the job agent</dt>
261  <dd>
262    Use the regular <code>Share</code> functionality to specify
263    which users/groups/projects should be able to use the job agent.
264    You must give them at least <code>USE</code> permission.
265  </dd>
266  </dl>
267
268</body>
269</html>
Note: See TracBrowser for help on using the repository browser.