1 | <?xml version="1.0" encoding="UTF-8"?> |
---|
2 | <!DOCTYPE chapter PUBLIC |
---|
3 | "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" |
---|
4 | "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"> |
---|
5 | <!-- |
---|
6 | $Id: installation.xml 6763 2015-03-09 08:13:04Z nicklas $ |
---|
7 | |
---|
8 | Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson |
---|
9 | Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson |
---|
10 | Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg |
---|
11 | Copyright (C) 2010, 2011, 2012 Nicklas Nordborg |
---|
12 | Copyright (C) 2013 Jari Häkkinen, Nicklas Nordborg |
---|
13 | |
---|
14 | This file is part of BASE - BioArray Software Environment. |
---|
15 | Available at http://base.thep.lu.se/ |
---|
16 | |
---|
17 | BASE is free software; you can redistribute it and/or |
---|
18 | modify it under the terms of the GNU General Public License |
---|
19 | as published by the Free Software Foundation; either version 3 |
---|
20 | of the License, or (at your option) any later version. |
---|
21 | |
---|
22 | BASE is distributed in the hope that it will be useful, |
---|
23 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
24 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
25 | GNU General Public License for more details. |
---|
26 | |
---|
27 | You should have received a copy of the GNU General Public License |
---|
28 | along with BASE. If not, see <http://www.gnu.org/licenses/>. |
---|
29 | --> |
---|
30 | |
---|
31 | <chapter id="installation"> |
---|
32 | |
---|
33 | <title>Installation and upgrade instructions</title> |
---|
34 | |
---|
35 | <note> |
---|
36 | <para> |
---|
37 | These instructions apply only to the BASE release which this |
---|
38 | document is a part of. The instructions here assume |
---|
39 | that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used |
---|
40 | on the server side. Other servlet engines may work but we only |
---|
41 | test with Tomcat. |
---|
42 | </para> |
---|
43 | </note> |
---|
44 | |
---|
45 | <sect1 id="installation.upgrade"> |
---|
46 | <title>Upgrade instructions</title> |
---|
47 | |
---|
48 | <important id="installation.upgrade.important"> |
---|
49 | <title>Important information for upgrading to the current release</title> |
---|
50 | <para> |
---|
51 | This section list some important information that may or may not |
---|
52 | apply when upgrading from the <emphasis>previous</emphasis> BASE |
---|
53 | release to the current release (eg. 3.4 to 3.5). If you are |
---|
54 | upgrading from a BASE installation that is older (3.0-3.3) |
---|
55 | you should also read <xref linkend="appendix.update_warnings" />. |
---|
56 | </para> |
---|
57 | |
---|
58 | <bridgehead>Consider updating to Java 8</bridgehead> |
---|
59 | <para> |
---|
60 | Oracle is no longer supporting Java 1.7. We are recommending Java 8 |
---|
61 | for running BASE. Java 7 is still supported, but will be removed |
---|
62 | in the next version (BASE 3.6). |
---|
63 | </para> |
---|
64 | |
---|
65 | </important> |
---|
66 | |
---|
67 | <para> |
---|
68 | As always, backup your database before attempting an |
---|
69 | upgrade. The BASE team performs extensive testing before |
---|
70 | releasing a new version of BASE but there are always a |
---|
71 | possibility for unexpected events during upgrades. In upgrades |
---|
72 | requiring a change in the underlying database there is no |
---|
73 | (supported) way to revert to a previous version of BASE using |
---|
74 | BASE tools, you need to use your backup for this use case. |
---|
75 | </para> |
---|
76 | |
---|
77 | <para> |
---|
78 | The strategy here is to install the new BASE release to another |
---|
79 | directory than the one in use. This requires transfer of |
---|
80 | configuration settings to the new install but more on that |
---|
81 | below. |
---|
82 | </para> |
---|
83 | |
---|
84 | <variablelist> |
---|
85 | <varlistentry> |
---|
86 | <term>Shut down the Tomcat server</term> |
---|
87 | <listitem> |
---|
88 | <para> |
---|
89 | If the BASE application is not shut down already, it is |
---|
90 | time to do it now. Do something like <command>sudo |
---|
91 | /etc/init.d/tomcat7.0 stop</command> |
---|
92 | </para> |
---|
93 | |
---|
94 | <tip> |
---|
95 | <title>Notify logged in users!</title> |
---|
96 | <para> |
---|
97 | If there are users logged in to your BASE server, it may |
---|
98 | be nice of you to notify them a few minutes prior to shutting |
---|
99 | down the BASE server. See <xref linkend="installation.broadcast" />. |
---|
100 | </para> |
---|
101 | </tip> |
---|
102 | </listitem> |
---|
103 | </varlistentry> |
---|
104 | |
---|
105 | <varlistentry> |
---|
106 | <term>Rename your current server</term> |
---|
107 | <listitem> |
---|
108 | <para> |
---|
109 | Rename your current BASE installation <command>mv |
---|
110 | /path/to/base /path/to/base_old</command>. |
---|
111 | </para> |
---|
112 | </listitem> |
---|
113 | </varlistentry> |
---|
114 | |
---|
115 | <varlistentry> |
---|
116 | <term>Download and unpack BASE</term> |
---|
117 | <listitem> |
---|
118 | <para> |
---|
119 | There are several ways to download BASE. Please refer to |
---|
120 | section <xref linkend="resources.home_page.download"/> for |
---|
121 | information on downloading BASE, and select the item |
---|
122 | matching your download option: |
---|
123 | </para> |
---|
124 | |
---|
125 | <variablelist> |
---|
126 | <varlistentry> |
---|
127 | <term><emphasis>Pre-compiled package</emphasis></term> |
---|
128 | <listitem> |
---|
129 | <para> |
---|
130 | If you selected to download a pre-compiled package, |
---|
131 | unpack the downloaded file with <command>tar zxpf |
---|
132 | base-...tar.gz</command>. |
---|
133 | </para> |
---|
134 | </listitem> |
---|
135 | </varlistentry> |
---|
136 | |
---|
137 | <varlistentry> |
---|
138 | <term><emphasis>Source package</emphasis></term> |
---|
139 | <listitem> |
---|
140 | <para> |
---|
141 | If you selected to download a source package, unpack |
---|
142 | the downloaded file with <command>tar zxpf |
---|
143 | base-...src.tar.gz</command>. Change to the new |
---|
144 | directory, and issue <command>ant |
---|
145 | package.bin</command>. This will create a binary |
---|
146 | package in the current directory. Unpack this new |
---|
147 | package (outside of the source file hierarchy). |
---|
148 | </para> |
---|
149 | </listitem> |
---|
150 | </varlistentry> |
---|
151 | |
---|
152 | <varlistentry> |
---|
153 | <term><emphasis>Subversion checkout</emphasis></term> |
---|
154 | <listitem> |
---|
155 | <para> |
---|
156 | This option is for advanced users only and is not |
---|
157 | covered here. Please refer to |
---|
158 | <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on |
---|
159 | this download option. |
---|
160 | </para> |
---|
161 | </listitem> |
---|
162 | </varlistentry> |
---|
163 | |
---|
164 | </variablelist> |
---|
165 | </listitem> |
---|
166 | |
---|
167 | </varlistentry> |
---|
168 | |
---|
169 | <varlistentry> |
---|
170 | <term>Transfer files and settings</term> |
---|
171 | <listitem> |
---|
172 | <para> |
---|
173 | Settings from the previous installation must be |
---|
174 | transferred to the new installation. This is most easily |
---|
175 | done by comparing the configuration files from the |
---|
176 | previous install with the new files. Do not just copy the |
---|
177 | old files to the new install since new options may have |
---|
178 | appeared. |
---|
179 | </para> |
---|
180 | <para> |
---|
181 | In the main BASE configuration file, |
---|
182 | <filename><base-dir>/www/WEB-INF/classes/base.config</filename>, |
---|
183 | fields that needs to be transferred are usually |
---|
184 | <emphasis>db.username</emphasis>, |
---|
185 | <emphasis>db.password</emphasis>, |
---|
186 | and <emphasis>userfiles</emphasis>. |
---|
187 | </para> |
---|
188 | <para> |
---|
189 | Local settings in the raw data |
---|
190 | tables, <filename><base-dir>/www/WEB-INF/classes/raw-data-types.xml</filename>, |
---|
191 | may need to be transferred. This also includes all files in |
---|
192 | the <filename><base-dir>/www/WEB-INF/classes/raw-data-types</filename> and |
---|
193 | <filename><base-dir>/www/WEB-INF/classes/extended-properties</filename> |
---|
194 | directories. |
---|
195 | </para> |
---|
196 | </listitem> |
---|
197 | </varlistentry> |
---|
198 | |
---|
199 | <varlistentry> |
---|
200 | <term>Updating database schema</term> |
---|
201 | <listitem> |
---|
202 | <para> |
---|
203 | It is recommended that you also perform an update of your |
---|
204 | database schema. Running the update scripts are not |
---|
205 | always necessary when upgrading BASE, but the running the |
---|
206 | update scripts are safe even in cases when there is no |
---|
207 | need to run them. Change directory |
---|
208 | to <filename |
---|
209 | class="directory"><base-dir>/bin/</filename> and issue |
---|
210 | <programlisting> |
---|
211 | sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis> |
---|
212 | sh ./updateindexes.sh |
---|
213 | </programlisting> |
---|
214 | where <emphasis>base_root_login</emphasis> is the login |
---|
215 | for the root user and <emphasis>base_root_password</emphasis> is the |
---|
216 | password. The login is optional. If not specified, |
---|
217 | <constant>root</constant> is used as the login. |
---|
218 | </para> |
---|
219 | </listitem> |
---|
220 | </varlistentry> |
---|
221 | |
---|
222 | <varlistentry> |
---|
223 | <term>Start Tomcat</term> |
---|
224 | <listitem> |
---|
225 | <para> |
---|
226 | Start the Tomcat server: <command>sudo |
---|
227 | /etc/init.d/tomcat7.0 start</command> |
---|
228 | </para> |
---|
229 | </listitem> |
---|
230 | </varlistentry> |
---|
231 | |
---|
232 | </variablelist> |
---|
233 | |
---|
234 | <para> |
---|
235 | Done! Upgrade of BASE is finished. |
---|
236 | </para> |
---|
237 | |
---|
238 | </sect1> <!-- Upgrade instructions --> |
---|
239 | |
---|
240 | <sect1 id="installation.main"> |
---|
241 | <title>Installation instructions</title> |
---|
242 | |
---|
243 | <variablelist> |
---|
244 | |
---|
245 | <varlistentry> |
---|
246 | <term>Java</term> |
---|
247 | <listitem> |
---|
248 | <para> |
---|
249 | Download and install Java SE 8, available from |
---|
250 | <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />. |
---|
251 | You can select either the JDK or the JRE version. |
---|
252 | </para> |
---|
253 | |
---|
254 | <note> |
---|
255 | <para> |
---|
256 | As of BASE 3.5 Java SE 8 is recommended. Support for Java SE 7 |
---|
257 | will be dropped in BASE 3.6. Java SE 6 or lower is not supported. |
---|
258 | </para> |
---|
259 | </note> |
---|
260 | |
---|
261 | </listitem> |
---|
262 | </varlistentry> |
---|
263 | |
---|
264 | <varlistentry> |
---|
265 | <term>Set up an SQL database</term> |
---|
266 | <listitem> |
---|
267 | <para> |
---|
268 | BASE |
---|
269 | utilise <ulink |
---|
270 | url="http://www.hibernate.org/">Hibernate</ulink> for |
---|
271 | object persistence to a relational database. Hibernate |
---|
272 | supports many database engines, but so far we only work |
---|
273 | with <ulink url="http://www.mysql.com">MySQL</ulink> |
---|
274 | and <ulink |
---|
275 | url="http://www.postgresql.org/">PostgreSQL</ulink>. |
---|
276 | </para> |
---|
277 | |
---|
278 | <variablelist> |
---|
279 | <varlistentry> |
---|
280 | <term>MySQL</term> |
---|
281 | <listitem> |
---|
282 | <para> |
---|
283 | Download and install MySQL (tested with version |
---|
284 | 5.5), available from |
---|
285 | <ulink url="http://www.mysql.com/" />. You need to |
---|
286 | be able to connect to the server over TCP, so |
---|
287 | the <emphasis>skip-networking</emphasis> option |
---|
288 | must <command>not</command> be used. The InnoDB |
---|
289 | table engine is also needed, so do not disable them |
---|
290 | (not that you would) but you may want to tune the |
---|
291 | InnoDB behaviour before creating BASE |
---|
292 | databases. BASE comes pre-configured for MySQL so |
---|
293 | there is no need to change database settings in the |
---|
294 | BASE configuration files. |
---|
295 | </para> |
---|
296 | </listitem> |
---|
297 | </varlistentry> |
---|
298 | <varlistentry> |
---|
299 | <term>PostgreSQL</term> |
---|
300 | <listitem> |
---|
301 | <para> |
---|
302 | PostgreSQL 9.3 seems to be working very well with |
---|
303 | BASE and Hibernate. Download and install PostgreSQL, |
---|
304 | available from |
---|
305 | <ulink url="http://www.postgresql.org/" />. You must edit |
---|
306 | your <filename><base-dir>/www/WEB-INF/classes/base.config</filename> |
---|
307 | file. Uncomment the settings for PostgreSQL and |
---|
308 | comment out the settings for MySQL. |
---|
309 | </para> |
---|
310 | </listitem> |
---|
311 | </varlistentry> |
---|
312 | </variablelist> |
---|
313 | |
---|
314 | </listitem> |
---|
315 | </varlistentry> |
---|
316 | |
---|
317 | <varlistentry id="installation.main.database"> |
---|
318 | <term>BASE (database engine)</term> |
---|
319 | <listitem> |
---|
320 | <para> |
---|
321 | The database names (base2 and base2dynamic are used here), |
---|
322 | the <emphasis>db_user</emphasis>, and the |
---|
323 | <emphasis>db_password</emphasis> can be changed during the |
---|
324 | creation of the databases. It is recommended to change the |
---|
325 | <emphasis>db_password</emphasis>, the other changes are |
---|
326 | optional and can be made if desired. The database names, |
---|
327 | the <emphasis>db_user</emphasis>, and the |
---|
328 | <emphasis>db_password</emphasis> are needed below when |
---|
329 | configuring BASE. |
---|
330 | </para> |
---|
331 | <note> |
---|
332 | Note that the <emphasis>db_user</emphasis> name and |
---|
333 | <emphasis>db_password</emphasis> set here is used |
---|
334 | internally by BASE in communication with the database and |
---|
335 | is never used to log on to the BASE application. |
---|
336 | </note> |
---|
337 | <important> |
---|
338 | <title>The database must use the UTF-8 character set</title> |
---|
339 | <para> |
---|
340 | Otherwise there will be a problem with storing values |
---|
341 | that uses characters outside the normal Latin1 range, |
---|
342 | for example unit-related such as µ (micro) and Ω (ohm). |
---|
343 | </para> |
---|
344 | </important> |
---|
345 | <variablelist> |
---|
346 | <varlistentry> |
---|
347 | <term>MySQL</term> |
---|
348 | <listitem> |
---|
349 | <para> |
---|
350 | Create a new database for BASE, and add a |
---|
351 | <emphasis>db_user</emphasis> with at least |
---|
352 | <emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>, |
---|
353 | <emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>, |
---|
354 | <emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>, |
---|
355 | <emphasis>INDEX</emphasis>, |
---|
356 | and <emphasis>ALTER</emphasis> permission for the |
---|
357 | new database. To do this, connect to your MySQL |
---|
358 | server and issue the next lines: |
---|
359 | <programlisting>CREATE DATABASE base2 DEFAULT CHARACTER SET utf8; |
---|
360 | CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8; |
---|
361 | GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password'; |
---|
362 | GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting> |
---|
363 | </para> |
---|
364 | <para> |
---|
365 | If you download BASE (instructions below) you find a file |
---|
366 | <filename><base-dir>/misc/sql/createdb.mysql.sql</filename> |
---|
367 | that contains the above statements and can be used |
---|
368 | by the <filename>mysql</filename> command-line tool |
---|
369 | (remember to edit the <emphasis>db_user</emphasis>, |
---|
370 | <emphasis>db_password</emphasis>, and the database |
---|
371 | names in the script file before executing the |
---|
372 | command): <command>mysql -uroot -p < |
---|
373 | <base-dir>/misc/sql/createdb.mysql.sql</command>. The |
---|
374 | header in the script file contains further |
---|
375 | information about the script. |
---|
376 | </para> |
---|
377 | </listitem> |
---|
378 | </varlistentry> |
---|
379 | <varlistentry> |
---|
380 | <term>PostgreSQL</term> |
---|
381 | <listitem> |
---|
382 | <para> |
---|
383 | Create a new database for BASE, and add a |
---|
384 | <emphasis>db_user</emphasis> with the proper |
---|
385 | privileges. To do this, log in as your PostgreSQL |
---|
386 | user and issue these lines (omit comments): |
---|
387 | <programlisting>createuser db_user -P |
---|
388 | # this will prompt for an password for the new user, and issue two |
---|
389 | # more question that should be answered with character 'n' for no. |
---|
390 | createdb --owner db_user --encoding UTF8 base2 |
---|
391 | psql base2 |
---|
392 | # this will start the psql command line tool. Issue the next line |
---|
393 | # within the tool and quit with a '\q'. |
---|
394 | CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting> |
---|
395 | |
---|
396 | If you download BASE (instructions below) you find a file |
---|
397 | <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename> |
---|
398 | that contains the above statements and can be used |
---|
399 | by the <filename>psql</filename> command-line tool: |
---|
400 | <command>psql -f |
---|
401 | <base-dir>/misc/sql/createdb.posgres.sql |
---|
402 | template1</command> The header in the script file |
---|
403 | contains further information about the script. |
---|
404 | </para> |
---|
405 | </listitem> |
---|
406 | </varlistentry> |
---|
407 | </variablelist> |
---|
408 | </listitem> |
---|
409 | </varlistentry> |
---|
410 | |
---|
411 | <varlistentry> |
---|
412 | <term>BASE (download and unpacking)</term> |
---|
413 | <listitem> |
---|
414 | <para> |
---|
415 | <ulink |
---|
416 | url="http://base.thep.lu.se/wiki/DownloadPage">Download |
---|
417 | BASE</ulink> and unpack the downloaded file, |
---|
418 | i.e. <command>tar zxpf base-...tar.gz</command>. If you |
---|
419 | prefer to have the bleeding edge version of BASE, perform |
---|
420 | a checkout of the source from the subversion repository |
---|
421 | (subversion checkout instructions at |
---|
422 | <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE |
---|
423 | trac site</ulink>). |
---|
424 | </para> |
---|
425 | <para> |
---|
426 | If you choose to download the binary package, skip to the |
---|
427 | next item. The rest of us, read on and compile BASE. If |
---|
428 | you downloaded a source distribution, unpack the |
---|
429 | downloaded file <command>tar zxpf |
---|
430 | base-...src.tar.gz</command>, or you may have performed a |
---|
431 | subversion checkout. Change to the 'root' base2 |
---|
432 | directory, and issue <command>ant |
---|
433 | package.bin</command>. This will create a binary package |
---|
434 | in the base2 'root' directory. Unpack this new package |
---|
435 | (outside of the source file hierarchy), and from now on |
---|
436 | the instructions are the same irrespective where you got |
---|
437 | the binary package. |
---|
438 | </para> |
---|
439 | <para> |
---|
440 | <emphasis>This section is intended for advanced users and |
---|
441 | programmers only. In cases when you want to change the |
---|
442 | BASE code and try out personalised features it may be |
---|
443 | advantageous to run the tweaked BASE server against the |
---|
444 | development tree. Instructions on how to accomplish this |
---|
445 | is available in the |
---|
446 | <ulink |
---|
447 | url="http://base.thep.lu.se/wiki/BuildingBase">building |
---|
448 | BASE document</ulink>. When you return back after |
---|
449 | compiling in the subversion tree you can follow the |
---|
450 | instruction here (with obvious changes to |
---|
451 | paths).</emphasis> |
---|
452 | </para> |
---|
453 | </listitem> |
---|
454 | </varlistentry> |
---|
455 | |
---|
456 | <varlistentry> |
---|
457 | <term>BASE (file storage setup)</term> |
---|
458 | <listitem> |
---|
459 | <para> |
---|
460 | An area for file storage must be setup. Create an empty |
---|
461 | directory in a proper location in your file system. Set |
---|
462 | the owner of the created directory to the user the Tomcat |
---|
463 | server will be running as. Tomcat server set up |
---|
464 | instructions will follow below. Remember this location for |
---|
465 | later use. The default location is <filename>/usr/local/base2/files</filename>. |
---|
466 | </para> |
---|
467 | </listitem> |
---|
468 | </varlistentry> |
---|
469 | |
---|
470 | <varlistentry> |
---|
471 | <term>BASE (plug-in setup)</term> |
---|
472 | <listitem> |
---|
473 | <para> |
---|
474 | An area for plug-in and extensions installation must be setup. |
---|
475 | Create an empty directory in a proper location in your file system, |
---|
476 | and make sure that the user that the Tomcat |
---|
477 | server will be running as has read permission in this |
---|
478 | directory. Tomcat server set up instructions will follow |
---|
479 | below. Remember this location for |
---|
480 | later use. The default location is <filename>/usr/local/base2/plugins</filename>. |
---|
481 | </para> |
---|
482 | </listitem> |
---|
483 | </varlistentry> |
---|
484 | |
---|
485 | <varlistentry id="installation.main.configuration"> |
---|
486 | <term>BASE (configuration)</term> |
---|
487 | <listitem> |
---|
488 | <para> |
---|
489 | Basic BASE configuration is done in |
---|
490 | <filename><base-dir>/www/WEB-INF/classes/base.config</filename>: |
---|
491 | <itemizedlist> |
---|
492 | <listitem> |
---|
493 | Uncomment the database engine section that match your setup. |
---|
494 | </listitem> |
---|
495 | <listitem> |
---|
496 | Modify the <emphasis>db.url</emphasis>, |
---|
497 | <emphasis>db.dynamic.catalog</emphasis>, |
---|
498 | <emphasis>db.username</emphasis>, |
---|
499 | and <emphasis>db.password</emphasis> settings to match |
---|
500 | your choice above. (<emphasis>database host and |
---|
501 | database name (e.g. base2)</emphasis>, |
---|
502 | <emphasis>e.g. base2dynamic</emphasis>, |
---|
503 | <emphasis>db_user</emphasis>, and |
---|
504 | <emphasis>db_password</emphasis>, respectively.) |
---|
505 | </listitem> |
---|
506 | <listitem> |
---|
507 | Modify the <emphasis>userfiles</emphasis> setting to |
---|
508 | match your choice in file storage setup above. |
---|
509 | </listitem> |
---|
510 | <listitem> |
---|
511 | Modify the <emphasis>plugins.dir</emphasis> setting to |
---|
512 | match your choice in plug-in setup above. |
---|
513 | </listitem> |
---|
514 | </itemizedlist> |
---|
515 | See the <xref linkend="appendix.base.config"/> for more |
---|
516 | information about the settings in |
---|
517 | the <filename>base.config</filename> file. |
---|
518 | </para> |
---|
519 | <para> |
---|
520 | <emphasis>Optional but recommended.</emphasis> You may want |
---|
521 | to modify extended properties to fit your needs. Extended |
---|
522 | properties are defined in |
---|
523 | <filename><base-dir>/www/WEB-INF/classes/extended-properties.xml</filename>. |
---|
524 | There is an |
---|
525 | administrator <ulink |
---|
526 | url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document |
---|
527 | discussing extended properties</ulink> available. If you |
---|
528 | plan to perform a migration of a BASE version 1.2 database you |
---|
529 | should probably not remove any extended properties |
---|
530 | columns (this is not tested so the outcome is currently |
---|
531 | undefined). However, adding columns does not affect |
---|
532 | migration. |
---|
533 | </para> |
---|
534 | </listitem> |
---|
535 | </varlistentry> |
---|
536 | |
---|
537 | <varlistentry> |
---|
538 | <term>BASE (database initialisation)</term> |
---|
539 | <listitem> |
---|
540 | <para> |
---|
541 | Change directory to |
---|
542 | <filename class="directory"><base-dir>/bin</filename> |
---|
543 | and execute the following commands: |
---|
544 | <programlisting> |
---|
545 | sudo ./initdb.sh [base_root_login] base_root_password |
---|
546 | ./updateindexes.sh |
---|
547 | </programlisting> |
---|
548 | </para> |
---|
549 | |
---|
550 | <para> |
---|
551 | In the first command sudo is required because a file will |
---|
552 | be created in the directory defined by |
---|
553 | <emphasis>userfiles</emphasis> above. If the directory is |
---|
554 | writable by you then sudo is not needed. |
---|
555 | </para> |
---|
556 | |
---|
557 | <para> |
---|
558 | The second command is important since |
---|
559 | the Hibernate database initialisation utility is not always |
---|
560 | able to create all required indexes. In some cases, Hibernate |
---|
561 | will also create a new index, even if one already exists. |
---|
562 | The command ensures that missing indexes are created and |
---|
563 | that duplicates are removed. BASE will work without the |
---|
564 | indexes but performance is impaired. |
---|
565 | </para> |
---|
566 | |
---|
567 | <important> |
---|
568 | <para> |
---|
569 | The <emphasis>base_root_login</emphasis> and |
---|
570 | <emphasis>base_root_password</emphasis> you use here |
---|
571 | is given to the BASE web application root user account. |
---|
572 | The <emphasis>base_root_login</emphasis> is optional. If |
---|
573 | not specified, <constant>root</constant> is used for |
---|
574 | the login. |
---|
575 | </para> |
---|
576 | </important> |
---|
577 | |
---|
578 | <para> |
---|
579 | If the initialisation script fails, it is probably a |
---|
580 | problem related to the underlying database. Make sure that |
---|
581 | the database accepts network connection and make sure that |
---|
582 | <emphasis>db_user</emphasis> has proper credentials. You |
---|
583 | may also get a <emphasis>Permission denied</emphasis> on |
---|
584 | file <filename>extension-settings.xml</filename> if you do |
---|
585 | not have write permission to the directory defined by |
---|
586 | variable <emphasis>userfiles</emphasis> in file |
---|
587 | <filename>base.config</filename>. If the initialisation |
---|
588 | fails on <filename>extension-settings.xml</filename> you |
---|
589 | must drop the database and recreate the database as |
---|
590 | described in <xref linkend="installation.main.database"/>. |
---|
591 | </para> |
---|
592 | </listitem> |
---|
593 | </varlistentry> |
---|
594 | |
---|
595 | <varlistentry> |
---|
596 | <term>Tomcat</term> |
---|
597 | <listitem> |
---|
598 | <para> |
---|
599 | Download and install Apache Tomcat 7.0.30 or any later 7.x |
---|
600 | release, available from <ulink url="http://tomcat.apache.org" />. |
---|
601 | </para> |
---|
602 | |
---|
603 | <important> |
---|
604 | <para> |
---|
605 | As of BASE 3.3 Tomcat 7 is required. BASE will no longer |
---|
606 | run on Tomcat 6 or lower. |
---|
607 | </para> |
---|
608 | </important> |
---|
609 | |
---|
610 | <para> |
---|
611 | There are a few configuration options that are needed to |
---|
612 | make Tomcat work properly with BASE. The options are set in the |
---|
613 | <code>CATALINA_OPTS</code> environment variable. |
---|
614 | </para> |
---|
615 | |
---|
616 | <itemizedlist> |
---|
617 | <listitem> |
---|
618 | <para> |
---|
619 | Increase the amount of memory that Tomcat is allowed to use. The default setting is |
---|
620 | usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>. |
---|
621 | </para> |
---|
622 | </listitem> |
---|
623 | <listitem> |
---|
624 | <para> |
---|
625 | Disable strict parsing of JSP files. |
---|
626 | <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code> |
---|
627 | </para> |
---|
628 | </listitem> |
---|
629 | <listitem> |
---|
630 | <para> |
---|
631 | Unless you have manually downloaded and installed JAI (Java Advanced |
---|
632 | Imaging) native acceleration libraries (see <ulink |
---|
633 | url="http://java.sun.com/javase/technologies/desktop/media/jai/" />) |
---|
634 | it is a good idea to disable the native acceleration of JAI. |
---|
635 | <code>-Dcom.sun.media.jai.disableMediaLib=true</code> |
---|
636 | </para> |
---|
637 | </listitem> |
---|
638 | <listitem> |
---|
639 | <para> |
---|
640 | Enable headless mode if your are setting up a server which doesn't have |
---|
641 | a display device connected to it. <code>-Djava.awt.headless=true</code>. |
---|
642 | </para> |
---|
643 | </listitem> |
---|
644 | </itemizedlist> |
---|
645 | |
---|
646 | <para> |
---|
647 | Depending on your system there are probably several ways to set the |
---|
648 | the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following |
---|
649 | line (as a single line) close to the top of the <filename>catalina.sh</filename> |
---|
650 | script that comes with Tomcat (directory <filename |
---|
651 | class="directory">bin</filename>): |
---|
652 | <programlisting>CATALINA_OPTS="-Xmx1G |
---|
653 | -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false |
---|
654 | -Dcom.sun.media.jai.disableMediaLib=true |
---|
655 | -Djava.awt.headless=true"</programlisting> |
---|
656 | </para> |
---|
657 | <para> |
---|
658 | For more information about Tomcat options see |
---|
659 | <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />. |
---|
660 | </para> |
---|
661 | </listitem> |
---|
662 | </varlistentry> |
---|
663 | |
---|
664 | <varlistentry> |
---|
665 | <term>BASE and Tomcat</term> |
---|
666 | <listitem> |
---|
667 | <para> |
---|
668 | Do the following: |
---|
669 | <itemizedlist> |
---|
670 | <listitem> |
---|
671 | <para> |
---|
672 | Either move the <filename |
---|
673 | class="directory"><base-dir>/www</filename> |
---|
674 | directory to the Tomcat <filename |
---|
675 | class="directory">webapps</filename> directory or |
---|
676 | create a symbolic link from the Tomcat <filename |
---|
677 | class="directory">webapps</filename> directory to |
---|
678 | the <filename |
---|
679 | class="directory"><base-dir>/www</filename> |
---|
680 | directory |
---|
681 | <programlisting>cd /path/to/tomcat/webapps |
---|
682 | ln -s /path_to_base/www base2</programlisting> |
---|
683 | </para> |
---|
684 | </listitem> |
---|
685 | <listitem> |
---|
686 | <para> |
---|
687 | Make sure that user Tomcat is running as can read |
---|
688 | all objects in the directory defined by |
---|
689 | <emphasis>plugins.dir</emphasis> in file |
---|
690 | <filename>base.config</filename>. |
---|
691 | </para> |
---|
692 | </listitem> |
---|
693 | <listitem> |
---|
694 | <para> |
---|
695 | Make sure that user Tomcat is running as owns (i.e., |
---|
696 | can read, write, delete and create) all objects in |
---|
697 | the directory, as well as the directory itself, |
---|
698 | defined by <emphasis>userfiles</emphasis> in file |
---|
699 | <filename>base.config</filename>. |
---|
700 | </para> |
---|
701 | </listitem> |
---|
702 | <listitem> |
---|
703 | <para> |
---|
704 | If you plan to install extensions you should make |
---|
705 | sure that the <filename |
---|
706 | class="directory"><base-dir>/www/extensions</filename> |
---|
707 | directory is writable by the user account Tomcat is |
---|
708 | running as. |
---|
709 | </para> |
---|
710 | </listitem> |
---|
711 | </itemizedlist> |
---|
712 | </para> |
---|
713 | <para> |
---|
714 | and finalise with start, or restart, Tomcat, and try |
---|
715 | http://hostname:8080/base2 (change |
---|
716 | <emphasis>hostname</emphasis> to your hostname and |
---|
717 | <emphasis>base2</emphasis> if you selected another name |
---|
718 | for the BASE Tomcat application) in your favourite |
---|
719 | browser. The BASE log-in page should appear after a few |
---|
720 | seconds. |
---|
721 | </para> |
---|
722 | </listitem> |
---|
723 | </varlistentry> |
---|
724 | |
---|
725 | <varlistentry> |
---|
726 | <term>BASE, Apache, and Apache/Tomcat connector</term> |
---|
727 | <listitem> |
---|
728 | <para> |
---|
729 | <emphasis>This step is optional</emphasis>. |
---|
730 | </para> |
---|
731 | <para> |
---|
732 | If you want run the Tomcat server through the Apache web |
---|
733 | server, you need to install the Apache version 2 web |
---|
734 | server, available |
---|
735 | from <ulink url="http://httpd.apache.org/" />, |
---|
736 | and a apache-tomcat connector, available |
---|
737 | from <ulink |
---|
738 | url="http://tomcat.apache.org/connectors-doc/index.html" /> |
---|
739 | </para> |
---|
740 | </listitem> |
---|
741 | </varlistentry> |
---|
742 | |
---|
743 | <varlistentry> |
---|
744 | <term>Setup done!</term> |
---|
745 | <listitem> |
---|
746 | <para> |
---|
747 | Happy BASEing. Now you can log on to your BASE server as |
---|
748 | user <emphasis>root</emphasis> (use |
---|
749 | the <emphasis>base_root_password</emphasis> from the |
---|
750 | database initialisation step above). You should begin with |
---|
751 | creating a couple user accounts, for more information on |
---|
752 | how to create user accounts please refer to |
---|
753 | <xref linkend="accounts"/>. |
---|
754 | </para> |
---|
755 | </listitem> |
---|
756 | </varlistentry> |
---|
757 | |
---|
758 | </variablelist> |
---|
759 | |
---|
760 | </sect1> <!-- Installation instructions --> |
---|
761 | |
---|
762 | <sect1 id="installation.jobagents"> |
---|
763 | <title>Installing job agents</title> |
---|
764 | |
---|
765 | <para> |
---|
766 | It is important to understand that the BASE application can be |
---|
767 | spread on to several computers. The main BASE application is |
---|
768 | serving HTTP requests, the underlying database engine is |
---|
769 | providing storage and persistence of data, and job agents can be |
---|
770 | installed on computers that will serve the BASE installation |
---|
771 | with computing power and perform analysis and run plug-ins. In a |
---|
772 | straight forward setup one computer provides all services needed |
---|
773 | for running BASE. From this starting point it is easy to add |
---|
774 | computers to shares load from the BASE server by installing job |
---|
775 | agents on these additional computers. |
---|
776 | </para> |
---|
777 | |
---|
778 | <para> |
---|
779 | A job agent is a program running on a computer regularly |
---|
780 | checking the BASE job queue for jobs awaiting execution. When |
---|
781 | the job agent finds a job that it is enabled to execute, it |
---|
782 | loads the plug-in and executes it. Job agents will in this way |
---|
783 | free up resources on the BASE application server, and thus allow |
---|
784 | the BASE server to concentrate on serving web pages. Job agents |
---|
785 | are optional and must be installed and setup |
---|
786 | separately. However, BASE is prepared for job agent setup and to |
---|
787 | utilise the agents, but the agent are not required. |
---|
788 | </para> |
---|
789 | |
---|
790 | <para> |
---|
791 | A job agent supports many configuration options that are not |
---|
792 | supported by the internal job queue. For example, you can |
---|
793 | <itemizedlist> |
---|
794 | <listitem> |
---|
795 | <para> |
---|
796 | Specify exactly which plug-ins each job agent should be |
---|
797 | able to execute. |
---|
798 | </para> |
---|
799 | </listitem> |
---|
800 | <listitem> |
---|
801 | <para> |
---|
802 | Give some plug-ins higher priority than other plug-ins. |
---|
803 | </para> |
---|
804 | </listitem> |
---|
805 | <listitem> |
---|
806 | <para> |
---|
807 | Specify which users/groups/projects should be able to use |
---|
808 | a specific job agent. |
---|
809 | </para> |
---|
810 | </listitem> |
---|
811 | <listitem> |
---|
812 | <para> |
---|
813 | Override memory settings and more for each plug-in. |
---|
814 | </para> |
---|
815 | </listitem> |
---|
816 | <listitem> |
---|
817 | <para> |
---|
818 | Execute plug-ins in separate processes. Thus, a misbehaving |
---|
819 | plug-in cannot bring the main application server down. |
---|
820 | </para> |
---|
821 | </listitem> |
---|
822 | <listitem> |
---|
823 | <para> |
---|
824 | Add more computers with job agents as needed. |
---|
825 | </para> |
---|
826 | </listitem> |
---|
827 | </itemizedlist> |
---|
828 | All these options make it possible to create a very flexible |
---|
829 | setup. For example one job agent can be assigned for importing |
---|
830 | data only, another job agent can be assigned for running |
---|
831 | analysis plug-ins for specific project only, and a third may be a |
---|
832 | catch-all job agent that performs all low-priority jobs. |
---|
833 | </para> |
---|
834 | |
---|
835 | <sect2 id="installation.jobagents.serverside"> |
---|
836 | <title>BASE application server side setup</title> |
---|
837 | <para> |
---|
838 | <variablelist> |
---|
839 | <varlistentry> |
---|
840 | <term>Make sure the internal job queue doesn't execute all plug-ins</term> |
---|
841 | <listitem> |
---|
842 | <para> |
---|
843 | The setting <command>jobqueue.internal.runallplugins</command> |
---|
844 | should be set to <command>false</command> for the |
---|
845 | BASE server. This setting is found in |
---|
846 | the <filename><base-dir>/www/WEB-INF/classes/base.config</filename> |
---|
847 | file. The changes will not take effect until the |
---|
848 | application server is restarted. |
---|
849 | </para> |
---|
850 | |
---|
851 | </listitem> |
---|
852 | </varlistentry> |
---|
853 | <varlistentry id="installation.jobagent.user_account"> |
---|
854 | <term>Enable the job agent user account</term> |
---|
855 | <listitem> |
---|
856 | <para> |
---|
857 | During installation of BASE a user account is created |
---|
858 | for the job agent. This account is used by the job |
---|
859 | agents to log on to BASE. The account is disabled by |
---|
860 | default and must be enabled. Enable the account and |
---|
861 | set a password using the BASE web interface. |
---|
862 | The same password must also be set in the |
---|
863 | <filename>jobagent.properties</filename> file, see |
---|
864 | item |
---|
865 | <xref linkend="installation.jobagent.client.properties"/> |
---|
866 | below. |
---|
867 | </para> |
---|
868 | </listitem> |
---|
869 | </varlistentry> |
---|
870 | </variablelist> |
---|
871 | </para> |
---|
872 | </sect2> |
---|
873 | |
---|
874 | <sect2 id="installation.jobagents.database"> |
---|
875 | <title>Database server setup</title> |
---|
876 | <para> |
---|
877 | <variablelist> |
---|
878 | <varlistentry id="installation.jobagent.database"> |
---|
879 | <term>Create a user account on the database</term> |
---|
880 | <listitem> |
---|
881 | <para> |
---|
882 | This is the similar to granting database access for |
---|
883 | the BASE server user in the in the regular BASE |
---|
884 | installation, cf. |
---|
885 | <xref |
---|
886 | linkend="installation.main.database"/>. |
---|
887 | You must create an account in the database that is |
---|
888 | allowed to connect from the job agent server. MySQL |
---|
889 | example: |
---|
890 | <programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password'; |
---|
891 | GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting> |
---|
892 | |
---|
893 | Replace <command>job.agent.host</command> with the |
---|
894 | host name of the server that is going to run the job |
---|
895 | agent. You should also set password. This password is |
---|
896 | used in item |
---|
897 | <xref linkend="installation.jobagent.client.config"/> |
---|
898 | below in job agent server setup. You can use the same |
---|
899 | database user and password as in the regular database |
---|
900 | setup. |
---|
901 | </para> |
---|
902 | </listitem> |
---|
903 | </varlistentry> |
---|
904 | </variablelist> |
---|
905 | </para> |
---|
906 | </sect2> |
---|
907 | |
---|
908 | <sect2 id="installation.jobagents.client"> |
---|
909 | <title>Job agent client setup</title> |
---|
910 | <para> |
---|
911 | <variablelist> |
---|
912 | <varlistentry> |
---|
913 | <term>Download and unpack a regular BASE distribution</term> |
---|
914 | <listitem> |
---|
915 | <para> |
---|
916 | You <emphasis>must</emphasis> use the same version on |
---|
917 | the web server and all job agents. You find the |
---|
918 | downloads at |
---|
919 | <ulink |
---|
920 | url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink> |
---|
921 | </para> |
---|
922 | </listitem> |
---|
923 | </varlistentry> |
---|
924 | <varlistentry id="installation.jobagent.client.config"> |
---|
925 | <term>Edit the <filename>base.config</filename> file</term> |
---|
926 | <listitem> |
---|
927 | <para> |
---|
928 | The <filename><base-dir>/www/WEB-INF/classes/base.config</filename> |
---|
929 | file must be configured as in regular BASE |
---|
930 | installation, cf. |
---|
931 | <xref |
---|
932 | linkend="installation.main.configuration"/>, |
---|
933 | to use the same database as the web server |
---|
934 | application. The most important settings are |
---|
935 | <itemizedlist> |
---|
936 | <listitem> |
---|
937 | <para> |
---|
938 | <command>db.username</command>: The database |
---|
939 | user you created in item |
---|
940 | <xref |
---|
941 | linkend="installation.jobagent.database"/> |
---|
942 | above. |
---|
943 | </para> |
---|
944 | </listitem> |
---|
945 | <listitem> |
---|
946 | <para> |
---|
947 | <command>db.password</command>: The password for |
---|
948 | the user. |
---|
949 | </para> |
---|
950 | </listitem> |
---|
951 | <listitem> |
---|
952 | <para> |
---|
953 | <command>db.url</command>: The connection url to |
---|
954 | the database. |
---|
955 | </para> |
---|
956 | </listitem> |
---|
957 | <listitem> |
---|
958 | <para> |
---|
959 | <command>userfiles</command>: The path to the |
---|
960 | directory where user files are located. This |
---|
961 | directory must be accessible from all job |
---|
962 | agents, i.e., by nfs or other file system |
---|
963 | sharing method. |
---|
964 | </para> |
---|
965 | </listitem> |
---|
966 | <listitem> |
---|
967 | <para> |
---|
968 | <command>plugins.dir</command>: The path to the |
---|
969 | directory where plug-ins are located. This |
---|
970 | directory must be accessible from all job |
---|
971 | agents, i.e., by nfs or other file system |
---|
972 | sharing method. |
---|
973 | </para> |
---|
974 | </listitem> |
---|
975 | </itemizedlist> |
---|
976 | See the <xref linkend="appendix.base.config"/> for |
---|
977 | more information about the settings in |
---|
978 | the <filename>base.config</filename> file. |
---|
979 | </para> |
---|
980 | </listitem> |
---|
981 | </varlistentry> |
---|
982 | <varlistentry id="installation.jobagent.client.properties"> |
---|
983 | <term>Edit |
---|
984 | the <filename>jobagent.properties</filename> file</term> |
---|
985 | <listitem> |
---|
986 | <para> |
---|
987 | The <filename><base-dir>/www/WEB-INF/classes/jobagent.properties</filename> |
---|
988 | file contains settings for the job agent. The most |
---|
989 | important ones to specify value for are |
---|
990 | <itemizedlist> |
---|
991 | <listitem> |
---|
992 | <para> |
---|
993 | <command>agent.password</command>: The password |
---|
994 | you set for the job agent user account in item |
---|
995 | <xref |
---|
996 | linkend="installation.jobagent.user_account"/> |
---|
997 | above. |
---|
998 | </para> |
---|
999 | </listitem> |
---|
1000 | <listitem> |
---|
1001 | <para> |
---|
1002 | <command>agent.id</command>: An ID that must be |
---|
1003 | unique for each job agent accessing the BASE application. |
---|
1004 | </para> |
---|
1005 | </listitem> |
---|
1006 | <listitem> |
---|
1007 | <para> |
---|
1008 | <command>agent.remotecontrol</command>: The |
---|
1009 | name or ip address of the web server if you want it |
---|
1010 | to be able to display info about running |
---|
1011 | jobs. The job agent will only allow connections |
---|
1012 | from computers specified in this setting. |
---|
1013 | </para> |
---|
1014 | </listitem> |
---|
1015 | </itemizedlist> |
---|
1016 | </para> |
---|
1017 | <para> |
---|
1018 | The <filename>jobagent.properties</filename> file |
---|
1019 | contains many more configuration options. See |
---|
1020 | the <xref linkend="appendix.jobagent.properties"/> for |
---|
1021 | more information. |
---|
1022 | </para> |
---|
1023 | </listitem> |
---|
1024 | </varlistentry> |
---|
1025 | <varlistentry> |
---|
1026 | <term>Register the job agent</term> |
---|
1027 | <listitem> |
---|
1028 | <para> |
---|
1029 | From the <filename>bin</filename> directory, register |
---|
1030 | the job agent with |
---|
1031 | <programlisting>./jobagent.sh register</programlisting> |
---|
1032 | </para> |
---|
1033 | </listitem> |
---|
1034 | </varlistentry> |
---|
1035 | <varlistentry> |
---|
1036 | <term>Start the job agent</term> |
---|
1037 | <listitem> |
---|
1038 | <para> |
---|
1039 | From the <filename>bin</filename> directory, start the |
---|
1040 | job agent with |
---|
1041 | <programlisting>./jobagent.sh start &</programlisting> |
---|
1042 | </para> |
---|
1043 | <para> |
---|
1044 | See the <xref linkend="appendix.jobagent.sh"/> |
---|
1045 | for more information about what you can do |
---|
1046 | with the job agent command line interface. |
---|
1047 | </para> |
---|
1048 | </listitem> |
---|
1049 | </varlistentry> |
---|
1050 | </variablelist> |
---|
1051 | </para> |
---|
1052 | </sect2> |
---|
1053 | |
---|
1054 | |
---|
1055 | <sect2 id="installation.jobagents.configuration"> |
---|
1056 | <title>Configuring the job agent</title> |
---|
1057 | |
---|
1058 | <para> |
---|
1059 | A job agent will not execute a plug-in unless the administrator |
---|
1060 | has configured the job agent to do so. There are two things that |
---|
1061 | must be done: |
---|
1062 | </para> |
---|
1063 | |
---|
1064 | <itemizedlist> |
---|
1065 | <listitem> |
---|
1066 | <para> |
---|
1067 | Share the job agent to the users, groups and project that should be |
---|
1068 | able to use it. If the job agent is not shared, only the owner of |
---|
1069 | job agent is allowed to use it. Use the regular <guilabel>Share</guilabel> |
---|
1070 | functionality to specify which users/groups/projects |
---|
1071 | should be able to use the job agent. You must give |
---|
1072 | them at least <command>USE</command> permission. |
---|
1073 | To give all users permission to the job agent share it |
---|
1074 | to the <command>EVERYONE</command> group. |
---|
1075 | </para> |
---|
1076 | </listitem> |
---|
1077 | |
---|
1078 | <listitem> |
---|
1079 | <para> |
---|
1080 | Selecting plug-ins that the job agent should handle. This can be |
---|
1081 | done either from the plug-in pages or from the job agent pages. To register |
---|
1082 | a plug-in with one or more job agents from the plug-in pages, go |
---|
1083 | to the edit view of the plug-in and select the <guilabel>Job |
---|
1084 | agents</guilabel> tab. To do the same from the job agent pages, |
---|
1085 | go to the edit view of the job agent and select |
---|
1086 | the <guilabel>Plugins</guilabel> tab. The registration dialogues |
---|
1087 | are very similar but only the plug-in side of registration is |
---|
1088 | described here. The major difference is that it is not possible |
---|
1089 | to enable/disable the internal job queue for plug-in when using |
---|
1090 | the jobagent side of the registration. |
---|
1091 | </para> |
---|
1092 | </listitem> |
---|
1093 | </itemizedlist> |
---|
1094 | |
---|
1095 | <figure id="plugins.figures.jobagents"> |
---|
1096 | <title>Select job agents for a plug-in</title> |
---|
1097 | <screenshot> |
---|
1098 | <mediaobject> |
---|
1099 | <imageobject><imagedata |
---|
1100 | scalefit="1" width="100%" |
---|
1101 | fileref="figures/plugin_jobagents.png" format="PNG" |
---|
1102 | /></imageobject> |
---|
1103 | </mediaobject> |
---|
1104 | </screenshot> |
---|
1105 | </figure> |
---|
1106 | |
---|
1107 | <helptext external_id="plugindefinition.jobagents" |
---|
1108 | title="Job agents"> |
---|
1109 | |
---|
1110 | <para> |
---|
1111 | Use this tab to specify which job agents the plug-in is |
---|
1112 | installed and allowed to be executed on. |
---|
1113 | </para> |
---|
1114 | |
---|
1115 | <variablelist> |
---|
1116 | <varlistentry> |
---|
1117 | <term><guilabel>Run this plugin on</guilabel></term> |
---|
1118 | <listitem> |
---|
1119 | <para> |
---|
1120 | You may select if the internal job queue should execute the |
---|
1121 | plug-in or not. |
---|
1122 | </para> |
---|
1123 | </listitem> |
---|
1124 | </varlistentry> |
---|
1125 | <varlistentry> |
---|
1126 | <term><guilabel>Job agents</guilabel></term> |
---|
1127 | <listitem> |
---|
1128 | <para> |
---|
1129 | A list with the job agents where the plug-in is installed and |
---|
1130 | allowed to be executed. Select a job agent in this list to display |
---|
1131 | more configuration options for the plug-in. |
---|
1132 | </para> |
---|
1133 | </listitem> |
---|
1134 | </varlistentry> |
---|
1135 | <varlistentry> |
---|
1136 | <term><guilabel>Add job agents</guilabel></term> |
---|
1137 | <listitem> |
---|
1138 | <para> |
---|
1139 | Use this button to open a pop-up window for selecting |
---|
1140 | job agents. |
---|
1141 | </para> |
---|
1142 | </listitem> |
---|
1143 | </varlistentry> |
---|
1144 | <varlistentry> |
---|
1145 | <term><guilabel>Remove</guilabel></term> |
---|
1146 | <listitem> |
---|
1147 | <para> |
---|
1148 | Remove the selected plug-in from the list. |
---|
1149 | </para> |
---|
1150 | </listitem> |
---|
1151 | </varlistentry> |
---|
1152 | </variablelist> |
---|
1153 | |
---|
1154 | <para> |
---|
1155 | The following properties are only displayed when a |
---|
1156 | job agent has been selected in the list. Each job agent may have it's |
---|
1157 | own settings of these properties. If you leave the values unspecified |
---|
1158 | the job agent will use the default values specified on the |
---|
1159 | <guilabel>Plugin</guilabel> tab. |
---|
1160 | </para> |
---|
1161 | |
---|
1162 | <variablelist> |
---|
1163 | <varlistentry> |
---|
1164 | <term><guilabel>Max memory</guilabel></term> |
---|
1165 | <listitem> |
---|
1166 | <para> |
---|
1167 | The maximum amount of memory the plug-in is allowed to use. |
---|
1168 | Add around 40MB for the Java run-time environment and BASE. |
---|
1169 | If not specified Java will choose it's default value which is 64MB. |
---|
1170 | </para> |
---|
1171 | </listitem> |
---|
1172 | </varlistentry> |
---|
1173 | <varlistentry> |
---|
1174 | <term><guilabel>Trusted</guilabel></term> |
---|
1175 | <listitem> |
---|
1176 | <para> |
---|
1177 | If the plug-in should be executed in a protected or |
---|
1178 | unprotected environment. Currently, BASE only supports |
---|
1179 | running plug-ins in an unprotected environment. |
---|
1180 | </para> |
---|
1181 | </listitem> |
---|
1182 | </varlistentry> |
---|
1183 | <varlistentry> |
---|
1184 | <term><guilabel>Priority boost</guilabel></term> |
---|
1185 | <listitem> |
---|
1186 | <para> |
---|
1187 | Used to give a plug-in higher priority in the job queue. |
---|
1188 | Values between 0 and 10 are allowed. A higher value will |
---|
1189 | give the plug-in higher priority. The priority boost is useful |
---|
1190 | if we, for example, want to use one server mainly for importing |
---|
1191 | data. By giving all import plugins a priority boost they will |
---|
1192 | be executed before all other jobs, which will have to wait |
---|
1193 | until there are no more waiting imports. |
---|
1194 | </para> |
---|
1195 | </listitem> |
---|
1196 | </varlistentry> |
---|
1197 | </variablelist> |
---|
1198 | |
---|
1199 | <seeother> |
---|
1200 | <other external_id="plugindefinition.edit">Plug-in properties</other> |
---|
1201 | <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other> |
---|
1202 | </seeother> |
---|
1203 | </helptext> |
---|
1204 | </sect2> |
---|
1205 | |
---|
1206 | </sect1> <!-- job agent setup --> |
---|
1207 | |
---|
1208 | <sect1 id="installation.serverconfigurations"> |
---|
1209 | <title>Server configurations</title> |
---|
1210 | <para> |
---|
1211 | Some server configurations can be done when the installation process is finished and |
---|
1212 | BASE is up and running. Log into BASE with administration rights and then |
---|
1213 | open the configuration dialog from menu |
---|
1214 | <menuchoice> |
---|
1215 | <guimenu>Administrate</guimenu> |
---|
1216 | <guimenuitem>Server settings</guimenuitem> |
---|
1217 | </menuchoice>. |
---|
1218 | Each tab in the configuration dialog-window is described below. |
---|
1219 | </para> |
---|
1220 | |
---|
1221 | <figure id="installation.figures.serverconfiguration"> |
---|
1222 | <title>Server configuration</title> |
---|
1223 | <screenshot> |
---|
1224 | <mediaobject> |
---|
1225 | <imageobject><imagedata |
---|
1226 | fileref="figures/server_configuration.png" format="PNG" |
---|
1227 | /></imageobject> |
---|
1228 | </mediaobject> |
---|
1229 | </screenshot> |
---|
1230 | </figure> |
---|
1231 | |
---|
1232 | <variablelist> |
---|
1233 | <varlistentry> |
---|
1234 | <term> |
---|
1235 | <guilabel>File transfer</guilabel> |
---|
1236 | </term> |
---|
1237 | <listitem> |
---|
1238 | <helptext external_id="serverconfig.filetransfer" title="File transfer rate"> |
---|
1239 | <variablelist> |
---|
1240 | <varlistentry> |
---|
1241 | <term><guilabel>Max upload rate</guilabel></term> |
---|
1242 | <listitem> |
---|
1243 | <para> |
---|
1244 | This is a limit of how many bytes of data that should be |
---|
1245 | transferred per second when uploading files to BASE. Prefixes |
---|
1246 | like k, M or G can be used for larger values, just like |
---|
1247 | described in the tab. The limit is per ongoing upload |
---|
1248 | and the default value is 100MB/s. |
---|
1249 | </para> |
---|
1250 | </listitem> |
---|
1251 | </varlistentry> |
---|
1252 | <varlistentry> |
---|
1253 | <term><guilabel>Max download rate</guilabel></term> |
---|
1254 | <listitem> |
---|
1255 | <para> |
---|
1256 | This is a limit of how many bytes of data that should be |
---|
1257 | transferred per second when downloading files from BASE. Prefixes |
---|
1258 | like k, M or G can be used for larger values. The limit is per ongoing |
---|
1259 | download and the default value is unlimited. |
---|
1260 | </para> |
---|
1261 | </listitem> |
---|
1262 | </varlistentry> |
---|
1263 | <varlistentry> |
---|
1264 | <term><guilabel>Unlimited</guilabel></term> |
---|
1265 | <listitem> |
---|
1266 | <para> |
---|
1267 | Check one or both to not limit the upload/download transfer rate. |
---|
1268 | In this case, the Internet connection of the server is the limit. |
---|
1269 | </para> |
---|
1270 | </listitem> |
---|
1271 | </varlistentry> |
---|
1272 | </variablelist> |
---|
1273 | </helptext> |
---|
1274 | </listitem> |
---|
1275 | </varlistentry> |
---|
1276 | <varlistentry> |
---|
1277 | <term> |
---|
1278 | <guilabel>About</guilabel> |
---|
1279 | </term> |
---|
1280 | <listitem> |
---|
1281 | <helptext external_id="serverconfig.about" |
---|
1282 | title="Information about the server"> |
---|
1283 | <variablelist> |
---|
1284 | <varlistentry> |
---|
1285 | <term><guilabel>Administrator name</guilabel></term> |
---|
1286 | <listitem> |
---|
1287 | <para> |
---|
1288 | Name of the responsible administrator. The name is displayed |
---|
1289 | at the bottom of each page in BASE and in the about-dialog. |
---|
1290 | </para> |
---|
1291 | </listitem> |
---|
1292 | </varlistentry> |
---|
1293 | <varlistentry> |
---|
1294 | <term><guilabel>Administrator email</guilabel></term> |
---|
1295 | <listitem> |
---|
1296 | <para> |
---|
1297 | An email which the administrator can be contacted on. The |
---|
1298 | administrator name, visible at the bottom of each page, will |
---|
1299 | be linked to this email address. |
---|
1300 | </para> |
---|
1301 | </listitem> |
---|
1302 | </varlistentry> |
---|
1303 | <varlistentry> |
---|
1304 | <term><guilabel>About</guilabel></term> |
---|
1305 | <listitem> |
---|
1306 | <para> |
---|
1307 | Text written in this field is displayed in the |
---|
1308 | <guilabel>About this server</guilabel> section on the login |
---|
1309 | page and in the about-dialog window. We recommend changing the |
---|
1310 | default Latin text to something meaningful, or remove it |
---|
1311 | to hide the section completely. |
---|
1312 | </para> |
---|
1313 | </listitem> |
---|
1314 | </varlistentry> |
---|
1315 | </variablelist> |
---|
1316 | </helptext> |
---|
1317 | </listitem> |
---|
1318 | </varlistentry> |
---|
1319 | <varlistentry> |
---|
1320 | <term> |
---|
1321 | <guilabel>Get account</guilabel> |
---|
1322 | </term> |
---|
1323 | <listitem> |
---|
1324 | <helptext external_id="serverconfig.getaccount" |
---|
1325 | title="Instructions to get an account"> |
---|
1326 | <para> |
---|
1327 | A description what a user should do to get |
---|
1328 | an account on the particular BASE server. This text is linked |
---|
1329 | to the <guilabel>Get an account!</guilabel> link on the login |
---|
1330 | page. We recommend that the Latin text is replaced with some useful |
---|
1331 | information, or that it is removed to hide the link. |
---|
1332 | </para> |
---|
1333 | </helptext> |
---|
1334 | </listitem> |
---|
1335 | </varlistentry> |
---|
1336 | <varlistentry> |
---|
1337 | <term> |
---|
1338 | <guilabel>Forgotten password</guilabel> |
---|
1339 | </term> |
---|
1340 | <listitem> |
---|
1341 | <helptext external_id="serverconfig.password" |
---|
1342 | title="Instructions when password is forgotten."> |
---|
1343 | <para> |
---|
1344 | A description what a user should do if the password is forgotten. |
---|
1345 | This text is linked |
---|
1346 | to the <guilabel>Forgot your password?</guilabel> link on the login |
---|
1347 | page. We recommend that the Latin text is replaced with some useful |
---|
1348 | information, or that it is removed to hide the link. |
---|
1349 | </para> |
---|
1350 | </helptext> |
---|
1351 | </listitem> |
---|
1352 | </varlistentry> |
---|
1353 | <varlistentry> |
---|
1354 | <term> |
---|
1355 | <guilabel>Links</guilabel> |
---|
1356 | </term> |
---|
1357 | <listitem> |
---|
1358 | <helptext external_id="serverconfig.links" title="Configurable links"> |
---|
1359 | <para> |
---|
1360 | External configurable link-types inside BASE. |
---|
1361 | <note> |
---|
1362 | <para> |
---|
1363 | Only link-types that have been set will be visible in the web |
---|
1364 | client. |
---|
1365 | </para> |
---|
1366 | </note> |
---|
1367 | </para> |
---|
1368 | <variablelist> |
---|
1369 | <varlistentry> |
---|
1370 | <term><guilabel>Help</guilabel></term> |
---|
1371 | <listitem> |
---|
1372 | <para> |
---|
1373 | Links to where the help text is located. By default |
---|
1374 | this is set to the documentation for the latest released |
---|
1375 | BASE version on the BASE web site, |
---|
1376 | <ulink |
---|
1377 | url="http://base.thep.lu.se/chrome/site/doc/html/index.html"> |
---|
1378 | http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>. |
---|
1379 | |
---|
1380 | If you want the documentation for a specific version you will |
---|
1381 | have to setup a site for that yourself and then change the link |
---|
1382 | to that site. The documentation is included in the downloaded package |
---|
1383 | in the directory <filename><basedir>/doc/html</filename>. |
---|
1384 | </para> |
---|
1385 | </listitem> |
---|
1386 | </varlistentry> |
---|
1387 | <varlistentry> |
---|
1388 | <term> |
---|
1389 | <guilabel>FAQ</guilabel> |
---|
1390 | </term> |
---|
1391 | <listitem> |
---|
1392 | <para>Where frequently asked questions can be found. Empty by default.</para> |
---|
1393 | </listitem> |
---|
1394 | </varlistentry> |
---|
1395 | <varlistentry> |
---|
1396 | <term> |
---|
1397 | <guilabel>Report a bug</guilabel> |
---|
1398 | </term> |
---|
1399 | <listitem> |
---|
1400 | <para> |
---|
1401 | Where the user could report bugs, feature request or |
---|
1402 | perhaps other feedback that concerns the program. As default |
---|
1403 | this is set to the feedback section on BASE web site, |
---|
1404 | <ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>. |
---|
1405 | Note that users must login in order to submit information. |
---|
1406 | </para> |
---|
1407 | </listitem> |
---|
1408 | </varlistentry> |
---|
1409 | </variablelist> |
---|
1410 | </helptext> |
---|
1411 | </listitem> |
---|
1412 | </varlistentry> |
---|
1413 | </variablelist> |
---|
1414 | |
---|
1415 | <sect2 id="installation.broadcast"> |
---|
1416 | <title>Sending a broadcast message to logged in users</title> |
---|
1417 | |
---|
1418 | <para> |
---|
1419 | It is possible to send a message to all logged in user. |
---|
1420 | Open the |
---|
1421 | <menuchoice> |
---|
1422 | <guimenu>Administrate</guimenu> |
---|
1423 | <guimenuitem>Broadcast message</guimenuitem> |
---|
1424 | </menuchoice> dialog box. |
---|
1425 | </para> |
---|
1426 | |
---|
1427 | <figure id="installation.figures.broadcast"> |
---|
1428 | <title>Broadcast message</title> |
---|
1429 | <screenshot> |
---|
1430 | <mediaobject> |
---|
1431 | <imageobject><imagedata |
---|
1432 | fileref="figures/broadcast_message.png" format="PNG" |
---|
1433 | /></imageobject> |
---|
1434 | </mediaobject> |
---|
1435 | </screenshot> |
---|
1436 | </figure> |
---|
1437 | |
---|
1438 | <helptext external_id="broadcast.message" title="Broadcast message"> |
---|
1439 | <para> |
---|
1440 | This dialog allows you to specify a message that is sent to all |
---|
1441 | logged in users as well as on the login form. It is also possible |
---|
1442 | to "disable" login. |
---|
1443 | </para> |
---|
1444 | <variablelist> |
---|
1445 | <varlistentry> |
---|
1446 | <term><guilabel>Title</guilabel></term> |
---|
1447 | <listitem> |
---|
1448 | <para> |
---|
1449 | The title of the message. It should be a short and concise to |
---|
1450 | avoid confusion. The title will be displayed on a lot of places |
---|
1451 | and a user may have to click on it to read the more detailed |
---|
1452 | message. |
---|
1453 | </para> |
---|
1454 | </listitem> |
---|
1455 | </varlistentry> |
---|
1456 | <varlistentry> |
---|
1457 | <term><guilabel>Disable login</guilabel></term> |
---|
1458 | <listitem> |
---|
1459 | <para> |
---|
1460 | Mark this check-box to try to prevent new users from logging in. To |
---|
1461 | avoid problems that can be caused by blocking the server admin out, |
---|
1462 | the login is not completely disabled. Any user can still login but |
---|
1463 | only after by-passing several warnings. |
---|
1464 | </para> |
---|
1465 | </listitem> |
---|
1466 | </varlistentry> |
---|
1467 | <varlistentry> |
---|
1468 | <term><guilabel>Message</guilabel></term> |
---|
1469 | <listitem> |
---|
1470 | <para> |
---|
1471 | If needed, a longer message giving more information. Users may |
---|
1472 | have to click on a link to be able to see the complete message. |
---|
1473 | </para> |
---|
1474 | </listitem> |
---|
1475 | </varlistentry> |
---|
1476 | </variablelist> |
---|
1477 | |
---|
1478 | <note> |
---|
1479 | The message will be enabled until it is manually removed by saving |
---|
1480 | an empty form, or until the Tomcat server is restarted. Since the |
---|
1481 | message is only kept in memory, a restart will always remove it. |
---|
1482 | </note> |
---|
1483 | |
---|
1484 | </helptext> |
---|
1485 | |
---|
1486 | </sect2> |
---|
1487 | |
---|
1488 | </sect1> |
---|
1489 | |
---|
1490 | <sect1 id="installation.migrate"> |
---|
1491 | <title>Migrating from MySQL to PostgreSQL</title> |
---|
1492 | |
---|
1493 | <para> |
---|
1494 | It is possible to migrate a BASE installation on a MySQL database to a |
---|
1495 | PostgreSQL database. In a real-world scenario a migration is probably coupled |
---|
1496 | with a hardware upgrade, i.e. the MySQL installation is on one (the old) server |
---|
1497 | and the PostgreSQL installation is on another (the new) server. While |
---|
1498 | this is not any problem per se, it requires a few extra steps to ensure that |
---|
1499 | everything has been moved to the new server. There are three main steps involved: |
---|
1500 | </para> |
---|
1501 | |
---|
1502 | <variablelist> |
---|
1503 | <varlistentry> |
---|
1504 | <term>Export</term> |
---|
1505 | <listitem> |
---|
1506 | <para> |
---|
1507 | The first step is to export all data in the existing database. Use |
---|
1508 | the following procedure: |
---|
1509 | </para> |
---|
1510 | |
---|
1511 | <orderedlist> |
---|
1512 | <listitem> |
---|
1513 | <para> |
---|
1514 | Upgrade to the latest BASE release. This is recommended since |
---|
1515 | it probably has fewer bugs. |
---|
1516 | </para> |
---|
1517 | </listitem> |
---|
1518 | |
---|
1519 | <listitem> |
---|
1520 | <para> |
---|
1521 | Make sure that no other processes are writing to the database |
---|
1522 | when the export is running. Shut down Tomcat and all job agents. |
---|
1523 | It may also be a good idea to ensure that no backup scripts or |
---|
1524 | other external programs are reading from the database at the same |
---|
1525 | time. If the database is large, this may affect performance due to |
---|
1526 | increased disk I/O. |
---|
1527 | </para> |
---|
1528 | </listitem> |
---|
1529 | |
---|
1530 | <listitem> |
---|
1531 | <para> |
---|
1532 | Create a temporary working directory in a suitable |
---|
1533 | location. This directory will be used for storing the |
---|
1534 | exported data. Disk I/O performance may be better if |
---|
1535 | this directory is on a different disk than what the |
---|
1536 | database is using. Ensure that the location has enough |
---|
1537 | free space to hold all data from the BASE database. The dump |
---|
1538 | typically uses less than 10% of the disk space used by the |
---|
1539 | MySQL tables. |
---|
1540 | </para> |
---|
1541 | </listitem> |
---|
1542 | |
---|
1543 | <listitem> |
---|
1544 | <para> |
---|
1545 | Make sure that you have configured migration-specific settings |
---|
1546 | in the <filename>base.config</filename> file. In most cases the |
---|
1547 | default settings should be good, but if you are experiencing |
---|
1548 | performance problems it may be necessary to change some settings. |
---|
1549 | See <xref linkend="appendix.base.config.migrate" /> for more |
---|
1550 | information. |
---|
1551 | </para> |
---|
1552 | </listitem> |
---|
1553 | |
---|
1554 | <listitem> |
---|
1555 | <para> |
---|
1556 | Start the export by changing to the <filename |
---|
1557 | class="directory"><base-dir>/bin/</filename> |
---|
1558 | directory and execute: |
---|
1559 | </para> |
---|
1560 | <programlisting> |
---|
1561 | ./migrate.sh export <replaceable>/path/to/migration/dir</replaceable> |
---|
1562 | </programlisting> |
---|
1563 | <para> |
---|
1564 | where <replaceable>/path/to/migration/dir</replaceable> |
---|
1565 | is replaced with the path to the working directory created above. |
---|
1566 | Depending on the size of the BASE installation the export may |
---|
1567 | take a long time. |
---|
1568 | </para> |
---|
1569 | </listitem> |
---|
1570 | </orderedlist> |
---|
1571 | |
---|
1572 | <note> |
---|
1573 | <para> |
---|
1574 | Make sure that the migration working directory is empty to perform |
---|
1575 | a full export. Existing files in the directory causes the corresponding |
---|
1576 | tables to be skipped. This can be useful when debugging and after a |
---|
1577 | server crash, since the export will resume where it stopped. Just make |
---|
1578 | sure that the database hasn't been modified in the meantime. |
---|
1579 | </para> |
---|
1580 | </note> |
---|
1581 | <warning> |
---|
1582 | <para> |
---|
1583 | When exporting, make sure that no other process is updating the |
---|
1584 | database since that may create an inconsistent snapshot. The |
---|
1585 | export process does not lock the database or take any other means |
---|
1586 | to protect it against concurrent modifications. |
---|
1587 | </para> |
---|
1588 | </warning> |
---|
1589 | </listitem> |
---|
1590 | </varlistentry> |
---|
1591 | |
---|
1592 | <varlistentry> |
---|
1593 | <term>Moving data</term> |
---|
1594 | <listitem> |
---|
1595 | <para> |
---|
1596 | This step is about moving the data from the old BASE server to the |
---|
1597 | new BASE server. If the migration is taking place on a single server, |
---|
1598 | this step can probably be skipped. |
---|
1599 | </para> |
---|
1600 | |
---|
1601 | <orderedlist> |
---|
1602 | <listitem> |
---|
1603 | <para> |
---|
1604 | Download and unpack the BASE software on the new server. Make sure that you are |
---|
1605 | using the same version as on the old server. It is also important that |
---|
1606 | the database is identically configured. Pay special attention |
---|
1607 | to the <filename>extended-properties.xml</filename> and |
---|
1608 | <filename>raw-data-types.xml</filename> files and any files |
---|
1609 | in the <filename |
---|
1610 | class="directory"><base-dir>/WEB-INF/classes/extended-properties</filename> |
---|
1611 | and <filename |
---|
1612 | class="directory"><base-dir>/WEB-INF/classes/raw-data-types</filename> |
---|
1613 | directories. |
---|
1614 | The import program protects against some mistakes by comparing |
---|
1615 | the column names from the export with the column names in the new |
---|
1616 | database, but it will, for example, not check that data types match. |
---|
1617 | </para> |
---|
1618 | |
---|
1619 | <tip> |
---|
1620 | The easiest way to do this is to simply copy the BASE installation |
---|
1621 | from the old server to the new server. Then, go through the |
---|
1622 | configuration files and make sure that paths are correct. |
---|
1623 | </tip> |
---|
1624 | |
---|
1625 | </listitem> |
---|
1626 | |
---|
1627 | <listitem> |
---|
1628 | <para> |
---|
1629 | Move user files from the old server to the new server. Make sure that |
---|
1630 | the <property>userfiles</property> setting in <filename>base.config</filename> |
---|
1631 | is correct. |
---|
1632 | </para> |
---|
1633 | </listitem> |
---|
1634 | |
---|
1635 | <listitem> |
---|
1636 | <para> |
---|
1637 | Move plug-ins from the old server to the new server. Make sure that |
---|
1638 | the <property>plugins.dir</property> setting in <filename>base.config</filename> |
---|
1639 | is correct. |
---|
1640 | </para> |
---|
1641 | </listitem> |
---|
1642 | |
---|
1643 | <listitem> |
---|
1644 | <para> |
---|
1645 | Check other settings in <filename>base.config</filename> and |
---|
1646 | other configuration files for settings that may be affected by |
---|
1647 | the move. |
---|
1648 | </para> |
---|
1649 | </listitem> |
---|
1650 | |
---|
1651 | </orderedlist> |
---|
1652 | |
---|
1653 | </listitem> |
---|
1654 | </varlistentry> |
---|
1655 | |
---|
1656 | <varlistentry> |
---|
1657 | <term>Import</term> |
---|
1658 | <listitem> |
---|
1659 | <para> |
---|
1660 | When everything has been moved and is properly configured it is |
---|
1661 | time to start with the import. |
---|
1662 | </para> |
---|
1663 | |
---|
1664 | <orderedlist> |
---|
1665 | <listitem> |
---|
1666 | <para> |
---|
1667 | Create a new empty database following the |
---|
1668 | instructions in <xref linkend="installation.main.database" />. |
---|
1669 | Make the corresponding changes in <filename>base.config</filename> |
---|
1670 | so that the BASE installation points to the new database. |
---|
1671 | Also, make sure that you have configured migration-specific settings |
---|
1672 | in the <filename>base.config</filename> file. In most cases the |
---|
1673 | default settings should be good, but if you are experiencing |
---|
1674 | performance problems it may be necessary to change some settings. |
---|
1675 | See <xref linkend="appendix.base.config.migrate" /> for more |
---|
1676 | information. |
---|
1677 | </para> |
---|
1678 | </listitem> |
---|
1679 | |
---|
1680 | <listitem> |
---|
1681 | <para> |
---|
1682 | Read the |
---|
1683 | <ulink url="http://www.postgresql.org/docs/9.1/interactive/populate.html">http://www.postgresql.org/docs/9.1/interactive/populate.html</ulink> |
---|
1684 | document from the PostgreSQL documentation and consider implementing some |
---|
1685 | of the tips. The migration script makes sure that no indexes or foreign |
---|
1686 | key constraints are active during the data import, but the tips about memory, |
---|
1687 | checkpoint intervals, WAL archiving, etc. (section 14.4.5 and on) can be useful. |
---|
1688 | It may also be a good idea to turn off the auto-vacuum daemon during the import. |
---|
1689 | </para> |
---|
1690 | </listitem> |
---|
1691 | |
---|
1692 | <listitem> |
---|
1693 | <para> |
---|
1694 | Start the import by changing to the <filename |
---|
1695 | class="directory"><base-dir>/bin/</filename> |
---|
1696 | directory and execute: |
---|
1697 | </para> |
---|
1698 | <programlisting> |
---|
1699 | ./migrate.sh import <replaceable>/path/to/migration/dir</replaceable> |
---|
1700 | </programlisting> |
---|
1701 | <para> |
---|
1702 | where <replaceable>/path/to/migration/dir</replaceable> |
---|
1703 | is replaced with the path to the directory where |
---|
1704 | the exported data is stored. Depending on |
---|
1705 | the size of the BASE installation this may take a long time. |
---|
1706 | </para> |
---|
1707 | |
---|
1708 | <para> |
---|
1709 | When the import has been completed, run this command |
---|
1710 | to create the last missing indexes: |
---|
1711 | </para> |
---|
1712 | <programlisting> |
---|
1713 | ./updateindexes.sh |
---|
1714 | </programlisting> |
---|
1715 | |
---|
1716 | <note> |
---|
1717 | <title>Installations with separate web and database servers</title> |
---|
1718 | <para> |
---|
1719 | Both export and import may be executed against remote MySQL/PostgreSQL |
---|
1720 | servers without limitation. The migration working directory need only |
---|
1721 | to be accessible by the BASE migration program. |
---|
1722 | </para> |
---|
1723 | </note> |
---|
1724 | |
---|
1725 | </listitem> |
---|
1726 | |
---|
1727 | <listitem> |
---|
1728 | <para> |
---|
1729 | Restart Tomcat and verify that the migration was successful. Eg. |
---|
1730 | check that you can log in to BASE, that you can access files, |
---|
1731 | that plug-ins are working, etc. Then, shut everything down again. |
---|
1732 | </para> |
---|
1733 | </listitem> |
---|
1734 | |
---|
1735 | <listitem> |
---|
1736 | <para> |
---|
1737 | Setup backup procedures for the new server. Verify that the |
---|
1738 | backup is working before starting up Tomcat again. |
---|
1739 | Restart any job agents (make sure that the are configured to use |
---|
1740 | the new server). When everything is up and running again, the |
---|
1741 | <replaceable>/path/to/migration/dir</replaceable> directory |
---|
1742 | and all files can be deleted. |
---|
1743 | </para> |
---|
1744 | </listitem> |
---|
1745 | </orderedlist> |
---|
1746 | |
---|
1747 | </listitem> |
---|
1748 | </varlistentry> |
---|
1749 | </variablelist> |
---|
1750 | |
---|
1751 | </sect1> |
---|
1752 | |
---|
1753 | </chapter> |
---|