Context Navigation

installation.xml @ 5738

Visit:

Last change on this file since 5738 was 5738, checked in by Nicklas Nordborg, 12 years ago

References #1590: Documentation cleanup

Re-orgarnized file/directory structure of documentation to make the paths a little bit shorter.

Property svn:eol-style set to native
Property svn:keywords set to Id

File size: 50.9 KB

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/doc/src/docbook/admin/installation.xml @ 5738

Download in other formats: