Context Navigation

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

Visit:

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

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

Download in other formats: