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

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

Removed links to deleted files.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 8.4 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 3687 2007-08-20 10:02:40Z 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="base.config.html">base.config reference</a>
65  </ul>
66
67
68  <p class="authors">
69  <b>Last updated:</b> $Date: 2007-08-20 10:02:40 +0000 (Mon, 20 Aug 2007) $<br>
70  <b>Copyright &copy;</b> 2006 The respective authors. All rights reserved.
71  </p>
72
73</div>
74
75  <a name="whatisit"></a>
76  <h2>1. What is a job agent?</h2>
77 
78  <p>
79    A job agent is a program running on another computer that is regularly
80    checking the BASE job queue for jobs that are awaiting execution. When
81    the job agent finds a job that it is able to execute it loads the plugin
82    and executes it.
83  </p>
84 
85  <p>
86    A job agent supports lots of configuration options that are not supported
87    by the internal job queue. For example, you can:
88  </p>
89 
90  <ul>
91  <li>Specify exactly which plugins each job agent should be able to execute.
92  <li>Give some plugins higher priority than others.
93  <li>Specify which users/groups/projects that should be able to use the job
94    agent.
95  <li>Override memory settings, etc. for each plugin.
96  <li>Execute plugins in separate processes. Thus, a misbehaving plugin doesn't
97    bring the web server down with it.
98  <li>Add more computers with more job agents if the need arises.
99  </ul>
100 
101  <p>
102    All these options make it possible to create a very flexible setup. For
103    example one job agent can be assigned for importing data only. Another job
104    agent can be assigned for running analysis plugins for specific project
105    only. A third may be a catch-all job agent that does all low-priority jobs.
106  </p>
107 
108
109  <a name="install"></a>
110  <h2>2. How to install a job agent</h2>
111 
112  <p>
113    It is not very difficult to install a job agent, but it requires some
114    manual configuration. Therefore, no job agent is installed by default.
115    Here is how to do it:
116  </p>
117
118  <a name="doweb"></a>
119  <h3>2.1 Things to do on the web server</h3>
120
121  <dl>
122  <dt>1. Disable the internal job queue on the web server</dt>
123  <dd>
124    We don't recommend using the internal job queue at the same time
125    as job agents. The setting <code>jobqueue.internal.enabled</code>
126    should be changed to <code>false</code> for the web server. This setting
127    is found in the <code>www/WEB-INF/classes/base.config</code> file. After
128    you have changed the setting the web server must be restarted.
129  </dd>
130 
131  <dt>2. Enable the job agent user account</dt>
132  <dd>
133    The default installation creates a user account that the job agent
134    uses to log in to BASE. This user account is disabled by default. You must
135    enable the account and give it a password. This password goes into the
136    <code>jobagent.properties</code> file in step 2.3.3 below.
137  </dd>
138  </dl>
139 
140  <a name="dodatabase"></a>
141  <h3>2.2 Things to do on the database server</h3>
142
143  <dl>
144  <dt>1. Create a user account on the database</dt>
145  <dd>
146    This is the same step as step iv) in the regular BASE installation. You must
147    create an account in the database that is allowed to connect from the
148    job agent server. MySQL example:
149   
150    <pre class="code">
151GRANT ALL ON base2.* TO base2user@job.agent.host IDENTIFIED BY 'password';
152GRANT ALL ON base2dynamic.* TO base2user@job.agent.host;
153</pre>
154
155    Replace <code>job.agent.host</code> with the host name of the
156    server that is going to run the job agent. You should also change the
157    password. This password goes into the <code>base.config</code> file
158    in step 2.3.2 below.
159  </dd>
160  </dl>
161
162  <a name="doagent"></a>
163  <h3>2.3 Things to do on the job agent server</h3>
164
165  <dl>
166  <dt>1. Download and unpack the regular BASE 2 distribution</dt>
167  <dd>
168    You must use the same version on the web server and all
169    job agents. You find the downloads here:
170    <a href="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</a>
171  </dd>
172
173  <dt>2. Edit the <code>base.config</code> file</dt>
174  <dd>
175    The <code>www/WEB-INF/classes/base.config</code> file must be configured
176    to use the same database as the web server application. The most
177    important settings are:
178    <ul>
179    <li>db.username: The database user you added in step 2.2.1
180    <li>db.password: The password for the user
181    <li>db.url: The connection url to the database
182    <li>userfile: The path to the directory where user files are located. This directory
183      must be accessible from all job agents.
184    </ul>
185   
186    See the <a href="base.config.html">base.config reference</a>
187    for more information about the settings in this file.
188  </dd>
189 
190  <dt>3. Edit the <code>jobagent.properties</code> file</dt>
191  <dd>
192    The <code>www/WEB-INF/classes/jobagent.properties</code> file contains settings for
193    the job agent. The most important ones to specify value for are:
194   
195    <ul>
196    <li>agent.password: The password you gave to the job agent user account in step 2.1.2
197      above.
198    <li>agent.id: An ID that must be unique for each job agent
199    <li>agent.remotecontrol: The name/ip address of the web server if you want it to be
200      able to display info about running jobs. The job agent will only allow connections
201      from computers specified in this setting.
202    </ul>
203   
204    <p>
205      The <code>jobagent.properties</code> file contains many more configuration
206      options. See the <a href="jobagent.properties.html"><code>jobagent.properties</code>
207      reference</a> for more information.
208    </p>
209   
210  </dd>
211 
212  <dt>4. Register the job agent</dt>
213  <dd>
214    From the <code>bin</code> directory, register the job agent with
215    <pre class="code">
216./jobagent.sh register
217</pre>
218  </dd>
219 
220  <dt>5. Start the job agent</dt>
221  <dd>
222    From the <code>bin</code> directory, start the job agent with
223    <pre class="code">
224./jobagent.sh start &
225</pre>
226
227  <p>
228    See the <a href="jobagent.sh.html">jobagent.sh reference</a> for
229    more information about what you can do with the command line
230    interface.
231  </p>
232   
233  </dd>
234  </dl>
235 
236  <a name="configure"></a>
237  <h2>3. Configuring the job agent</h2>
238 
239  <p>
240    Before the job agent starts executing jobs for you it must be configured.
241    The configuration is done through the web interface.
242  </p>
243 
244  <dl>
245  <dt>1. Configure the plugins the job agent should handle</dt>
246  <dd>
247    <ul>
248    <li>Go to the <code>Administrate -> Plugins -> Job agents</code> menu.
249    <li>Select the job agent and click on the <code>Edit</code> button.
250    <li>On the <code>Plugins</code> tab you can specify which plugins the
251      job agent should handle. Note that if you have installed external
252      plugins on the web server, those plugins must be installed on the
253      job agent as well. It is possible to specify different paths to the
254      JAR file for each job agent.
255    </ul>
256  </dd>
257 
258  <dt>2. Give users access to the job agent</dt>
259  <dd>
260    Use the regular <code>Share</code> functionality to specify
261    which users/groups/projects should be able to use the job agent.
262    You must give them at least <code>USE</code> permission.
263  </dd>
264  </dl>
265
266</body>
267</html>
Note: See TracBrowser for help on using the repository browser.