Context Navigation

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

Visit:

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

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

Download in other formats: