Context Navigation

installation_upgrade.xml @ 3811

Visit:

Last change on this file since 3811 was 3811, checked in by Nicklas Nordborg, 16 years ago

References #796: Don't create indexes on primary key columns for tables in the dynamic database

Added tool to remove indexes from dynamic db.

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

File size: 41.5 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_upgrade.xml 3811 2007-10-09 12:15:16Z nicklas $
7
8	Copyright (C) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10	This file is part of BASE - BioArray Software Environment.
11	Available at http://base.thep.lu.se/
12
13	BASE is free software; you can redistribute it and/or
14	modify it under the terms of the GNU General Public License
15	as published by the Free Software Foundation; either version 2
16	of the License, or (at your option) any later version.
17
18	BASE is distributed in the hope that it will be useful,
19	but WITHOUT ANY WARRANTY; without even the implied warranty of
20	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21	GNU General Public License for more details.
22
23	You should have received a copy of the GNU General Public License
24	along with this program; if not, write to the Free Software
25	Foundation, Inc., 59 Temple Place - Suite 330,
26	Boston, MA 02111-1307, USA.
27	-->
28
29	<chapter id="installation_upgrade">
30	<?dbhtml dir="installation_upgrade"?>
31
32	<title>Installation, setup, migration, and upgrade instructions</title>
33
34	<note>
35	These instructions apply only to the BASE release which this
36	document is a part of.
37	</note>
38
39	<para>
40	This chapter is divided into four parts. First, the process of
41	upgrading a BASE 2 server is described. Followed by set up of job
42	agents. (For these two first parts it is assumed that there is a
43	running server.) Then, the first time installation instructions
44	follows, and the chapter is concluded with information on how to
45	migrate data from a BASE 1.2.17 server to a BASE 2 server.
46	</para>
47
48	<para>
49	The first time installation is only to be performed once,
50	optionally followed by a migration. The migration can only be done
51	to a pristine (empty) BASE 2 server with one exception; The
52	migration can be restarted if it fails during the RawBioAssaysData
53	transfer, for all other failure points the migration has to be
54	restarted with an empty database. Migration from several BASE 1
55	installations to one BASE 2 server is not supported.
56	</para>
57
58	<para>
59	The instructions here assume
60	that <ulink url="http://tomcat.apache.org/">tomcat</ulink> is used
61	on the server side. Other servlet engines may work but we only
62	test tomcat.
63	</para>
64
65
66	<sect1 id="installation_upgrade.upgrade">
67	<title>Upgrade instructions</title>
68
69	<important id="dropindexes">
70	<title>Upgrading from BASE 2.4.3 or lower to 2.4.4 or higher</title>
71	<para>
72	Older releases of BASE 2 used to create indexes for many columns
73	in the dynamic database. The same columns are part of the primary
74	key for the tables so the indexes are not really needed. The
75	result is very bad performance since the database engine sometimes
76	get stuck in "index update" mode making the entire server
77	very slow. BASE 2.4.4 no longer creates the indexes. Indexes on
78	existing tables should be dropped to increase the performance.
79	Tests have shown a 50-90% decrease in execution time for some
80	plug-ins
81	(<ulink url="http://base.thep.lu.se/ticket/294">http://base.thep.lu.se/ticket/294</ulink>).
82	</para>
83	<para>
84	Removing the indexes is very simple. <emphasis>After the server
85	has been upgraded</emphasis> following the usual instructions below, issue the
86	the following commands:
87	</para>
88
89	<programlisting>
90	cd <basedir>/bin
91	./dynamicdb.sh -v -dropindexes
92	</programlisting>
93
94	<para>
95	Skip the <option>-dropindexes</option> option to do a dry
96	run without actually deleting the indexes.
97	</para>
98	</important>
99
100	<para>
101	As always, backup your database before attempting an
102	upgrade. The BASE team performs extensive testing before
103	releasing a new version of BASE but there are always a
104	possibility for unexpected events during upgrades. In upgrades
105	requiring a change in the underlying database there is no
106	(supported) way to revert to a previous version of BASE using
107	BASE tools, you need to use your backup for this use case.
108	</para>
109
110	<para>
111	The strategy here is to install the new BASE release to another
112	directory than the one in use. This requires transfer of
113	configuration settings to the new install but more on that
114	below.
115	</para>
116
117	<variablelist>
118	<varlistentry>
119	<term>Shut down the tomcat server</term>
120	<listitem>
121	<para>
122	If the BASE application is not shut down already, it is
123	time to do it now. Do something like <command>sudo
124	/etc/init.d/tomcat5.5 stop</command>
125	</para>
126	</listitem>
127	</varlistentry>
128
129	<varlistentry>
130	<term>Rename your current server</term>
131	<listitem>
132	<para>
133	Rename your current BASE 2 installation <command>mv
134	/path/to/base /path/to/base_old</command>.
135	</para>
136	</listitem>
137	</varlistentry>
138
139	<varlistentry>
140	<term>Download and unpack BASE</term>
141	<listitem>
142	<para>
143	There are several ways to download BASE. Please refer to
144	section <xref linkend="resources.home_page.download"/> for
145	information on downloading BASE, and select the item
146	matching your download option:
147	</para>
148
149	<variablelist>
150	<varlistentry>
151	<term><emphasis>Pre-compiled package</emphasis></term>
152	<listitem>
153	<para>
154	If you selected to download a pre-compiled package,
155	unpack the downloaded file with <command>tar zxpf
156	base-...tar.gz</command>.
157	</para>
158	</listitem>
159	</varlistentry>
160
161	<varlistentry>
162	<term><emphasis>Source package</emphasis></term>
163	<listitem>
164	<para>
165	If you selected to download a source package, unpack
166	the downloaded file with <command>tar zxpf
167	base-...src.tar.gz</command>. Change to the new
168	directory, and issue <command>ant
169	package.bin</command>. This will create a binary
170	package in the current directory. Unpack this new
171	package (outside of the source file hierarchy).
172	</para>
173	</listitem>
174	</varlistentry>
175
176	<varlistentry>
177	<term><emphasis>Subversion checkout</emphasis></term>
178	<listitem>
179	<para>
180	This option is for advanced users only and is not
181	covered here. Please refer to
182	<xref linkend="core_ref.build"/> for information on
183	this download option.
184	</para>
185	</listitem>
186	</varlistentry>
187
188	</variablelist>
189	</listitem>
190
191	</varlistentry>
192
193	<varlistentry>
194	<term>Transfer files and settings</term>
195	<listitem>
196	<para>
197	Settings from the previous installation must be
198	transferred to the new installation. This is most easily
199	done by comparing the configuration files from the
200	previous install with the new files. Do not just copy the
201	old files to the new install since new options may have
202	appeared.
203	</para>
204	<para>
205	In the main BASE configuration file,
206	<filename>/path/to/base/www/WEB-INF/classes/base.config</filename>,
207	fields that needs to be transferred are usually
208	<emphasis>db.username</emphasis>,
209	<emphasis>db.password</emphasis>,
210	and <emphasis>userfiles</emphasis>.
211	</para>
212	<para>
213	Local settings in the raw data
214	tables, <filename>/path/to/base/www/WEB-INF/classes/raw-data-types.xml</filename>,
215	may need to be transferred.
216	</para>
217	</listitem>
218	</varlistentry>
219
220	<varlistentry>
221	<term>Updating database schema</term>
222	<listitem>
223	<para>
224	It is recommended that you also perform an update of your
225	database schema. Running the update scripts are not
226	always necessary when upgrading BASE, but the running the
227	update scripts are safe even in cases when there is no
228	need to run them. Change directory
229	to <filename
230	class="directory">/path/to/base/bin/</filename> and issue
231	<programlisting>sh ./updatedb.sh <emphasis>base_root_password</emphasis>
232	sh ./updateindexes.sh <emphasis>base_root_password</emphasis></programlisting>
233	where <emphasis>base_root_password</emphasis> is the
234	password for the root user account within the BASE
235	application.
236	</para>
237	</listitem>
238	</varlistentry>
239
240	<varlistentry>
241	<term>Remove tomcat cache</term>
242	<listitem>
243	<para>
244	As tomcat user, remove cached files and directories. Do
245	something like
246	<programlisting>cd /usr/share/apache-tomcat-5.5.15/
247	rm -rf work/Catalina</programlisting>
248	</para>
249	</listitem>
250	</varlistentry>
251
252	<varlistentry>
253	<term>Start tomcat</term>
254	<listitem>
255	<para>
256	Start the tomcat server: <command>sudo
257	/etc/init.d/tomcat5.5 start</command>
258	</para>
259	</listitem>
260	</varlistentry>
261
262	</variablelist>
263
264	<para>
265	Done! Upgrade of BASE is finished.
266	</para>
267
268	</sect1> <!-- Upgrade instructions -->
269
270
271	<sect1 id="installation_upgrade.jobagents">
272	<title>Installing job agents</title>
273
274	<para>
275	It is important to understand that the BASE application can be
276	spread on to several computers. The main BASE application is
277	serving HTTP requests, the underlying database engine is
278	providing storage and persistence of data, and job agents can be
279	installed on computers that will serve the BASE installation
280	with computing power and perform analysis and run plug-in. In a
281	straight forward setup one computer provides all services needed
282	for running BASE. From this starting point it is easy to add
283	computers to shares load from the BASE server by installing job
284	agents on these additional computers.
285	</para>
286
287	<para>
288	A job agent is a program running on a computer regularly
289	checking the BASE job queue for jobs awaiting execution. When
290	the job agent finds a job that it is enabled to execute, it
291	loads the plugin and executes it. Job agents will in this way
292	free up resources on the BASE application server, and thus allow
293	the BASE server to concentrate on serving web pages. Job agents
294	are optional and must be installed and setup
295	separately. However, BASE is prepared for job agent setup and to
296	utilize the agents, but the agent are not required.
297	</para>
298
299	<para>
300	A job agent supports many configuration options that are not
301	supported by the internal job queue. For example, you can
302	<itemizedlist>
303	<listitem>
304	<para>
305	Specify exactly which plugins each job agent should be
306	able to execute.
307	</para>
308	</listitem>
309	<listitem>
310	<para>
311	Give some plugins higher priority than other plugins.
312	</para>
313	</listitem>
314	<listitem>
315	<para>
316	Specify which users/groups/projects should be able to use
317	a specific job agent.
318	</para>
319	</listitem>
320	<listitem>
321	<para>
322	Override memory settings and more for each plugin.
323	</para>
324	</listitem>
325	<listitem>
326	<para>
327	Execute plugins in separate processes. Thus, a misbehaving
328	plugin cannot bring the main application server down.
329	</para>
330	</listitem>
331	<listitem>
332	<para>
333	Add more computers with job agents as needed.
334	</para>
335	</listitem>
336	</itemizedlist>
337	All these options make it possible to create a very flexible
338	setup. For example one job agent can be assigned for importing
339	data only, another job agent can be assigned for running
340	analysis plugins for specific project only, and a third may be a
341	catch-all job agent that performs all low-priority jobs.
342	</para>
343
344	<sect2 id="installation_upgrade.jobagents.serverside">
345	<title>BASE application server side setup</title>
346	<para>
347	<variablelist>
348	<varlistentry>
349	<term>Disable the internal job queue</term>
350	<listitem>
351	<para>
352	It is not recommended to use the internal job queue
353	when job agents are used. The
354	setting <command>jobqueue.internal.enabled</command>
355	should be changed to <command>false</command> for the
356	BASE server. This setting is found in
357	the <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
358	file. The changes will not take effect until the
359	application server is restarted.
360	</para>
361	</listitem>
362	</varlistentry>
363	<varlistentry id="installation_upgrade.jobagent.user_account">
364	<term>Enable the job agent user account</term>
365	<listitem>
366	<para>
367	During installation of BASE a user account is created
368	for the job agent. This account is used by the job
369	agents to log on to BASE. The account is disabled by
370	default and must be enabled. Enable the account and
371	set a password. This password is set in the
372	<filename>jobagent.properties</filename> file, see
373	item
374	<xref linkend="installation_upgrade.jobagent.client.properties"/>
375	below.
376	</para>
377	</listitem>
378	</varlistentry>
379	</variablelist>
380	</para>
381	</sect2>
382
383	<sect2 id="installation_upgrade.jobagents.database">
384	<title>Database server setup</title>
385	<para>
386	<variablelist>
387	<varlistentry id="installation_upgrade.jobagent.database">
388	<term>Create a user account on the database</term>
389	<listitem>
390	<para>
391	This is the similar to granting database access for
392	the BASE server user in the in the regular BASE
393	installation, cf.
394	<xref
395	linkend="installation_upgrade.installation.database"/>.
396	You must create an account in the database that is
397	allowed to connect from the job agent server. MySQL
398	example:
399	<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
400	GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
401
402	Replace <command>job.agent.host</command> with the
403	host name of the server that is going to run the job
404	agent. You should also set password. This password is
405	used in item
406	<xref linkend="installation_upgrade.jobagent.client.config"/>
407	below in job agent server setup. You can use the same
408	database user and password as in the regular database
409	setup.
410	</para>
411	</listitem>
412	</varlistentry>
413	</variablelist>
414	</para>
415	</sect2>
416
417	<sect2 id="installation_upgrade.jobagents.client">
418	<title>Job agent client setup</title>
419	<para>
420	<variablelist>
421	<varlistentry>
422	<term>Download and unpack a regular BASE 2 distribution</term>
423	<listitem>
424	<para>
425	You <emphasis>must</emphasis> use the same version on
426	the web server and all job agents. You find the
427	downloads at
428	<ulink
429	url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
430	</para>
431	</listitem>
432	</varlistentry>
433	<varlistentry id="installation_upgrade.jobagent.client.config">
434	<term>Edit the <filename>base.config</filename> file</term>
435	<listitem>
436	<para>
437	The <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
438	file must be configured as in regular BASE
439	installation, cf.
440	<xref
441	linkend="installation_upgrade.installation.configuration"/>,
442	to use the same database as the web server
443	application. The most important settings are
444	<itemizedlist>
445	<listitem>
446	<para>
447	<command>db.username</command>: The database
448	user you created in item
449	<xref
450	linkend="installation_upgrade.jobagent.database"/>
451	above.
452	</para>
453	</listitem>
454	<listitem>
455	<para>
456	<command>db.password</command>: The password for
457	the user.
458	</para>
459	</listitem>
460	<listitem>
461	<para>
462	<command>db.url</command>: The connection url to
463	the database.
464	</para>
465	</listitem>
466	<listitem>
467	<para>
468	<command>userfile</command>: The path to the
469	directory where user files are located. This
470	directory must be accessible from all job
471	agents, i.e., by nfs or other file system
472	sharing method.
473	</para>
474	</listitem>
475	</itemizedlist>
476	See the <xref linkend="appendix.base.config"/> for
477	more information about the settings in
478	the <filename>base.config</filename> file.
479	</para>
480	</listitem>
481	</varlistentry>
482	<varlistentry id="installation_upgrade.jobagent.client.properties">
483	<term>Edit
484	the <filename>jobagent.properties</filename> file</term>
485	<listitem>
486	<para>
487	The <filename>/path/to/base/www/WEB-INF/classes/jobagent.properties</filename>
488	file contains settings for the job agent. The most
489	important ones to specify value for are
490	<itemizedlist>
491	<listitem>
492	<para>
493	<command>agent.password</command>: The password
494	you set for the job agent user account in item
495	<xref
496	linkend="installation_upgrade.jobagent.user_account"/>
497	above.
498	</para>
499	</listitem>
500	<listitem>
501	<para>
502	<command>agent.id</command>: An ID that must be
503	unique for each job agent accessing the BASE application.
504	</para>
505	</listitem>
506	<listitem>
507	<para>
508	<command>agent.remotecontrol</command>: The
509	name/ip address of the web server if you want it
510	to be able to display info about running
511	jobs. The job agent will only allow connections
512	from computers specified in this setting.
513	</para>
514	</listitem>
515	</itemizedlist>
516	</para>
517	<para>
518	The <filename>jobagent.properties</filename> file
519	contains many more configuration options. See
520	the <xref linkend="appendix.jobagent.properties"/> for
521	more information.
522	</para>
523	</listitem>
524	</varlistentry>
525	<varlistentry>
526	<term>Register the job agent</term>
527	<listitem>
528	<para>
529	From the <filename>bin</filename> directory, register
530	the job agent with
531	<programlisting>./jobagent.sh register</programlisting>
532	</para>
533	</listitem>
534	</varlistentry>
535	<varlistentry>
536	<term>Start the job agent</term>
537	<listitem>
538	<para>
539	From the <filename>bin</filename> directory, start the
540	job agent with
541	<programlisting>./jobagent.sh start &</programlisting>
542	</para>
543	<para>
544	See the <xref linkend="appendix.jobagent.sh"/>
545	reference for more information about what you can do
546	with the job agent command line interface.
547	</para>
548	</listitem>
549	</varlistentry>
550	</variablelist>
551	</para>
552	</sect2>
553
554	<sect2 id="installation_upgrade.jobagents.configuration">
555	<title>Configuring the job agent</title>
556	<para>
557	Before the job agent starts executing jobs for you it must be
558	configured. The configuration is done through the BASE web
559	interface.
560	<variablelist>
561	<varlistentry>
562	<term>Configure the plugins the job agent should handle</term>
563	<listitem>
564	<para>
565	<itemizedlist>
566	<listitem>
567	<para>
568	Go to the
569	<menuchoice>
570	<guimenu>Administrate</guimenu>
571	<guisubmenu>Plugins</guisubmenu>
572	<guimenuitem>Job agents</guimenuitem>
573	</menuchoice> menu.
574	</para>
575	</listitem>
576	<listitem>
577	<para>
578	Select the job agent and click on the &gbEdit;
579	button.
580	</para>
581	</listitem>
582	<listitem>
583	<para>
584	On the <guilabel>Plugins</guilabel> tab you can
585	specify which plugins the job agent should
586	handle. Note that if you have installed external
587	plugins on the web server, those plugins must be
588	installed on the job agent as well. It is
589	possible to specify different paths to the JAR
590	file for each job agent.
591	</para>
592	</listitem>
593	</itemizedlist>
594	</para>
595	</listitem>
596	</varlistentry>
597	<varlistentry>
598	<term>Grant users access to the job agent</term>
599	<listitem>
600	<para>
601	Use the regular <guilabel>Share</guilabel>
602	functionality to specify which users/groups/projects
603	should be able to use the job agent. You must give
604	them at least <command>USE</command> permission.
605	</para>
606	</listitem>
607	</varlistentry>
608	</variablelist>
609	</para>
610	</sect2>
611
612	</sect1> <!-- job agent setup -->
613
614
615	<sect1 id="installation_upgrade.installation">
616	<title>Installation instructions</title>
617
618	<variablelist>
619
620	<varlistentry>
621	<term>Java</term>
622	<listitem>
623	<para>
624	Download and install Java SDK 1.5, available from
625	<ulink url="http://java.sun.com/" />. Make sure that you
626	download the JDK version (<emphasis>not</emphasis> the JRE
627	version). <command>Java 6 is currently not
628	supported</command> (this will change starting with
629	BASE version 2.5 whereafter only Java 6 will be supported).
630	</para>
631	</listitem>
632	</varlistentry>
633
634	<varlistentry>
635	<term>Tomcat</term>
636	<listitem>
637	<para>
638	Download and install tomcat 5.5.16 or later, available
639	from <ulink
640	url="http://jakarta.apache.org/tomcat/" />
641	<important>
642	You MUST make sure that Tomcat uses the SERVER mode of
643	the Java run time engine
644	(see <ulink
645	url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
646	</important>
647	On Linux you do this by setting the environment variable:
648	<code>CATALINA_OPTS</code> to <code>-server</code>. It is
649	also a good idea to specify the maximum allowed memory to
650	use: <code>-server -Xmx500m</code> sets it to 500
651	megabytes. Basically add the next line close to the top of
652	the <filename>catalina.sh</filename> script that comes
653	with tomcat
654	(directory <filename
655	class="directory">bin</filename>):
656	<programlisting>CATALINA_OPTS="-server -Xmx500m"</programlisting>
657	</para>
658	<para>
659	For more information about Tomcat options see
660	<ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
661	</para>
662	</listitem>
663	</varlistentry>
664
665	<varlistentry>
666	<term>Set up SQL database</term>
667	<listitem>
668	<para>
669	BASE 2
670	utilize <ulink
671	url="http://www.hibernate.org/">Hibernate</ulink> for
672	object persistence to a relational database. Hibernate
673	supports many database engines, but so far we only work
674	with <ulink url="http://www.mysql.com">MySQL</ulink>
675	and <ulink
676	url="http://www.postgresql.org/">PostgreSQL</ulink>.
677	</para>
678
679	<variablelist>
680	<varlistentry>
681	<term>MySQL</term>
682	<listitem>
683	<para>
684	Download and install MySQL (tested with version
685	5.0), available from
686	<ulink url="http://www.mysql.com/" />. You need to
687	be able to connect to the server over TCP, so
688	the <emphasis>skip-networking</emphasis> option
689	must <command>not</command> be used. The InnoDB
690	table engine is also needed, so do not disable them
691	(not that you would) but you may want to tune the
692	InnoDB behaviour before creating BASE
693	databases. BASE comes pre-configured for MySQL so
694	there is no need to change database settings in the
695	BASE configuration files.
696	</para>
697	</listitem>
698	</varlistentry>
699	<varlistentry>
700	<term>PostgreSQL</term>
701	<listitem>
702	<para>
703	PostgreSQL 8.0 seems to be working very well with
704	BASE and Hibernate. Download and install PostgreSQL,
705	available from
706	<ulink url="http://www.postgresql.org/" />. you must
707	edit
708	your <filename>/path/to/base/www/WEB-INF/classes/base.config</filename>
709	file. Uncomment the settings for Postgres and
710	comment out the settings for MySQL.
711	</para>
712	</listitem>
713	</varlistentry>
714	</variablelist>
715
716	</listitem>
717	</varlistentry>
718
719	<varlistentry>
720	<term>BASE (download and unpacking)</term>
721	<listitem>
722	<para>
723	<ulink
724	url="http://base.thep.lu.se/wiki/DownloadPage">Download
725	BASE</ulink> and unpack the downloaded file,
726	i.e. <command>tar zxpf base-...tar.gz</command>. If you
727	prefer to have the bleeding edge version of BASE, perform
728	a checkout of the source from the subversion repository
729	(subversion checkout instructions at
730	<ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
731	trac site</ulink>).
732	</para>
733	<para>
734	If you choose to download the binary package, skip to the
735	next item. The rest of us, read on and compile BASE 2. If
736	you downloaded a source distribution, unpack the
737	downloaded file <command>tar zxpf
738	base-...src.tar.gz</command>, or you may have performed a
739	subversion checkout. Change to the 'root' base2
740	directory, and issue <command>ant
741	package.bin</command>. This will create a binary package
742	in the base2 'root' directory. Unpack this new package
743	(outside of the source file hierarchy), and from now on
744	the instructions are the same irrespective where you got
745	the binary package.
746	</para>
747	<para>
748	<emphasis>This section is intended for advanced users and
749	programmers only. In cases when you want to change the
750	BASE code and try out personalized features it may be
751	advantageous to run the tweaked BASE server against the
752	development tree. Instructions on how to accomplish this
753	is available in the
754	<ulink
755	url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
756	BASE document</ulink>. When you return back after
757	compiling in the subversion tree you can follow the
758	instruction here (with obvious changes to
759	paths).</emphasis>
760	</para>
761	</listitem>
762	</varlistentry>
763
764	<varlistentry id="installation_upgrade.installation.database">
765	<term>BASE (database engine)</term>
766	<listitem>
767	<para>
768	Instructions for MySQL and PostgreSQL are available
769	below. The database names (base2 and base2dynamic is used
770	here), the <emphasis>db_user</emphasis>, and
771	the <emphasis>db_password</emphasis> can be changed during
772	the creation of the databases. It is recommended to change
773	the <emphasis>db_password</emphasis>, the other changes
774	can be made if desired. The database names,
775	the <emphasis>db_user</emphasis>, and
776	the <emphasis>db_password</emphasis> are needed in a later
777	step below when configuring BASE.
778	</para>
779	<note>
780	Note that the <emphasis>db_user</emphasis> name
781	and <emphasis>db_password</emphasis> set here is used
782	internally by BASE in communication with the database and
783	is never used to log on to the BASE application.
784	</note>
785	<variablelist>
786	<varlistentry>
787	<term>MySQL</term>
788	<listitem>
789	<para>
790	Create a new database for BASE, and add a
791	<emphasis>db_user</emphasis> with at least
792	<emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
793	<emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
794	<emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
795	<emphasis>INDEX</emphasis>,
796	and <emphasis>ALTER</emphasis> permission for the
797	new database. To do this, connect to your MySQL
798	server and issue the next lines:
799	<programlisting>CREATE DATABASE base2;
800	CREATE DATABASE base2dynamic;
801	GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
802	GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
803	</para>
804	<para>
805	The <filename>/path/to/base/misc/sql/createdb.mysql.sql</filename>
806	file contains the above statements and can be used
807	by the <filename>mysql</filename> command-line tool
808	(remember to edit
809	the <emphasis>db_user</emphasis>,
810	<emphasis>db_password</emphasis>,
811	and the database names in the script file before
812	executing the command): <command>mysql -uroot -p
813	< ./misc/sql/createdb.mysql.sql</command>. The
814	header in the script file contains further
815	information about the script.
816	</para>
817	</listitem>
818	</varlistentry>
819	<varlistentry>
820	<term>PostgreSQL</term>
821	<listitem>
822	<para>
823	Create a new database for BASE, and add a
824	<emphasis>db_user</emphasis> with the proper
825	privileges. To do this, log in as your PostgreSQL
826	user and issue these lines (omit comments):
827	<programlisting>createuser db_user -P
828	# this will prompt for an password for the new user, and issue two
829	# more question that should be answered with character 'n' for no.
830	createdb --owner db_user --encoding UNICODE base2
831	psql base2
832	# this will start the psql command line tool. Issue the next line
833	# within the tool and quit with a '\q'.
834	CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
835	The <filename>/path/to/base/misc/sql/createdb.postgresql.sql</filename>
836	file contains the above statements and can be used
837	by the <filename>psql</filename> command-line tool:
838	<command>psql -f ./misc/sql/createdb.posgres.sql
839	template1</command> The header in the script file
840	contains further information about the script.
841	</para>
842	</listitem>
843	</varlistentry>
844	</variablelist>
845	</listitem>
846	</varlistentry>
847
848	<varlistentry>
849	<term>BASE (file storage setup)</term>
850	<listitem>
851	<para>
852	An area for file storage must be setup. Create an empty
853	directory in a proper location in your file system, and
854	set the owner to be the same as the one that the tomcat
855	server will be running as. Remember this location for
856	later use.
857	</para>
858	</listitem>
859	</varlistentry>
860
861	<varlistentry id="installation_upgrade.installation.configuration">
862	<term>BASE (configuration)</term>
863	<listitem>
864	<para>
865	Basic BASE configuration is done in
866	<filename>/path/to/base/www/WEB-INF/classes/base.config</filename>:
867	<itemizedlist>
868	<listitem>
869	Uncomment the database engine section that match your setup.
870	</listitem>
871	<listitem>
872	Modify the <emphasis>db.url</emphasis>,
873	<emphasis>db.dynamic.catalog</emphasis>,
874	<emphasis>db.username</emphasis>,
875	and <emphasis>db.password</emphasis> settings to match
876	your choice above. (<emphasis>database host and
877	database name (e.g. base2)</emphasis>,
878	<emphasis>e.g. base2dynamic</emphasis>,
879	<emphasis>db_user</emphasis>, and
880	<emphasis>db_password</emphasis>, respectively.)
881	</listitem>
882	<listitem>
883	Modify the <emphasis>userfiles</emphasis> setting to
884	match your choice above.
885	</listitem>
886	</itemizedlist>
887	See the <xref linkend="appendix.base.config"/> for more
888	information about the settings in
889	the <filename>base.config</filename> file.
890	</para>
891	<para>
892	<emphasis>Optional but recommended.</emphasis> You may want
893	to modify extended properties to fit your needs. Extended
894	properties are defined in
895	<filename>/path/to/base/www/WEB-INF/classes/extended-properties.xml</filename>.
896	There is an administrator <ulink
897	url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
898	discussing extended properties</ulink> available.
899	</para>
900	</listitem>
901	</varlistentry>
902
903	<varlistentry>
904	<term>BASE (database initialization)</term>
905	<listitem>
906	<para>
907	Change directory to
908	<filename class="directory">/path/to/base/bin</filename>
909	and run <filename>initdb.sh</filename> as
910	<programlisting>./initdb.sh base_root_password</programlisting>
911	<important>
912	The <emphasis>base_root_password</emphasis> you use here
913	is given to the BASE web application
914	user <emphasis>root</emphasis>. There is no supported way
915	to change the <emphasis>root</emphasis> account name.
916	</important>
917	If the initialisation script fail, it is most probably a
918	problem related to the underlying database. Make sure that
919	the database accepts network connection and make sure that
920	<emphasis>db_user</emphasis> has proper credentials.
921	</para>
922	</listitem>
923	</varlistentry>
924
925	<varlistentry>
926	<term>BASE and tomcat</term>
927	<listitem>
928	<para>
929	Either move the <filename
930	class="directory">/path/to/base/www</filename> directory
931	to the tomcat <filename class="directory">webapps</filename>
932	directory or create a symbolic link from the tomcat
933	<filename class="directory">webapps</filename> directory to
934	the <filename class="directory">/path/to/base/www</filename>
935	directory
936	<programlisting>cd /path/to/tomcat/webapps
937	ln -s /path_to_base/www base2</programlisting>
938	Start/restart tomcat, and try http://hostname:8080/base2
939	(change <emphasis>hostname</emphasis> to your hostname) in
940	your favourite browser. BASE log-in page should appear
941	after a few seconds.
942	</para>
943	</listitem>
944	</varlistentry>
945
946	<varlistentry>
947	<term>BASE, apache, and apache/tomcat connector</term>
948	<listitem>
949	<para>
950	<emphasis>This step is optional</emphasis>.
951	</para>
952	<para>
953	If you want run the tomcat server through the apache web
954	server, you need to install the apache version 2 web
955	server, available
956	from <ulink
957	url="http://www.apache.org/">http://www.apache.org/</ulink>,
958	and a apache-tomcat connector, available
959	from <ulink
960	url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
961	So, we got you there;-) To be honest, this step is not
962	really well documented since we previously used SuSE 9.3
963	on our demo/test server, and apache/tomcat/mod_jk comes
964	pre-installed. The current server does not use the
965	apache/tomcat connector. What you need to do is something
966	like this
967	<itemizedlist>
968	<listitem>
969	Get that tomcat server running in stand-alone
970	mode.
971	</listitem>
972	<listitem>
973	Get the apache 2 server running.
974	</listitem>
975	<listitem>
976	Install mod_jk. Note, different version are used for
977	apache 1.3 and 2. In SuSE 9.3 this step is done by
978	installing <filename>mod_jk-ap20</filename>.
979	</listitem>
980	<listitem>
981	Create a <filename>workers.properties</filename> file
982	in the
983	tomcat <filename class="directory">base</filename>
984	directory (commonly copied from a template).
985	</listitem>
986	<listitem>
987	Create a <filename>jk.conf</filename> file in the
988	apache <filename class="directory">conf</filename>
989	directory (commonly copied from a template), and make
990	sure that <emphasis>jk</emphasis> is added to the
991	modules to be loaded when apache starts.
992	</listitem>
993	<listitem>
994	In <filename>jk.conf</filename> add the lines below
995	and change paths appropriately.
996	<programlisting># The following lines makes apache aware of the location of
997	# the /base2 context
998	Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
999	<Directory "/srv/www/tomcat5/base/webapps/base2">
1000	Options Indexes FollowSymLinks
1001	allow from all
1002	</Directory>
1003	# The following lines mounts all base2 jsp files to tomcat
1004	JkMount /base2 ajp13
1005	JkMount /base2/* ajp13
1006	# The following lines prohibits users from directly accessing WEB-INF
1007	<Location "/base2/WEB-INF/">
1008	AllowOverride None
1009	deny from all
1010	</Location></programlisting>
1011	</listitem>
1012	</itemizedlist>
1013	You must restart the apache and the tomcat server after above steps.
1014	</para>
1015	</listitem>
1016	</varlistentry>
1017
1018	<varlistentry>
1019	<term>Setup done!</term>
1020	<listitem>
1021	<para>
1022	Happy BASEing. Now you can log on to your BASE 2 server as
1023	user <emphasis>root</emphasis> (use
1024	the <emphasis>base_root_password</emphasis> from the
1025	database initialization step above). You should begin with
1026	creating a couple user accounts, for more information on
1027	how to create user accounts please refer to
1028	<xref linkend="user_administration"/>.
1029	</para>
1030	<para>
1031	If you are planning to perform a migration of data from
1032	BASE 1.2.x please perform the steps in
1033	<xref linkend="installation_upgrade.migration"/> before
1034	doing anything else with your new BASE installation.
1035	</para>
1036	</listitem>
1037	</varlistentry>
1038
1039	</variablelist>
1040
1041	</sect1> <!-- Installation instructions -->
1042
1043
1044	<sect1 id="installation_upgrade.migration">
1045	<title>Migration instructions</title>
1046
1047	<caution>
1048	<title>The disclaimer section</title>
1049	<para>
1050	We have made extensive testing of the migration from BASE1.2
1051	to BASE2. To our knowledge the migration works but we cannot
1052	guarantee perfect functionality. The migration tool is
1053	supplied as is and usage is done at your risk. We are
1054	committed to solve migration problems at the level of
1055	transferring data from BASE 1.2 to 2.2.x, but cannot resolve
1056	data loss issues in a running BASE 2 server due to imperfect
1057	migration. When you start the migration tool you are required
1058	to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1059	to the <filename>migrate_from_1.2.sh</filename>
1060	script. Remember to check that the migration performed well
1061	before you decide to delete your 1.2 installation.
1062	</para>
1063	<para>
1064	Migration from the latest BASE 1.2.x release to the latest is
1065	supported.
1066	</para>
1067	</caution>
1068
1069	<para>
1070	Verify that your BASE 2 installation is up and running before
1071	attempting migration. Preferably try to log in using the root
1072	user through the web interface.
1073	</para>
1074
1075	<para>
1076	Make sure your BASE 1.2 runs with the latest
1077	(<emphasis>pristine</emphasis>) schema
1078	version, <emphasis>i.e.,</emphasis> the migration will only
1079	support an unmodified BASE 1.2 installation. If you have an out
1080	of date schema version, please upgrade to the latest schema
1081	using BASE 1.2 tools before migrating. If you have made local
1082	changes to the BASE 1.2 schema you need to patch the BASE 2
1083	schema as well as make proper changes to the migration program.
1084	</para>
1085
1086	<para>
1087	The behaviour of migration is controlled
1088	through <filename>migration.properties</filename> file (see
1089	<xref linkend="appendix.migrate.properties"/>), but you should
1090	know what you do when you change parameters in this file.
1091	</para>
1092
1093	<para>
1094	Migration can be restarted in one specific case only; If the
1095	migration fails during the RawBioAssaysData transfer simply
1096	restart the migration and the script will ask you to verify that
1097	a restart should be attempted. For all other failure points the
1098	migration has to be restarted with an empty database.
1099	</para>
1100
1101	<para>
1102	Migration is performed with the following steps:
1103	<orderedlist>
1104
1105	<listitem>
1106	<para>
1107	To transfer files from BASE 1.2 (default migration
1108	behaviour), you must have file system access to BASE 1.2
1109	files, <emphasis>i.e.,</emphasis> the <filename
1110	class="directory">/path/to/base1.2/data</filename>
1111	directory containing directories
1112	<filename class="directory">rawdata</filename>,
1113	<filename class="directory">uploads</filename>,
1114	<filename class="directory">protocols</filename>, ...
1115	</para>
1116	</listitem>
1117
1118	<listitem>
1119	<para>
1120	Change settings in the file
1121	<filename>/path/to/base/dist/www/WEB-INF/classes/migrate.properties</filename>.
1122	The available options are commented:
1123	<itemizedlist>
1124	<listitem>
1125	<para>
1126	Modify <emphasis>db1.*</emphasis> parameters to
1127	match your BASE 1.2 installation.
1128	</para>
1129	</listitem>
1130	<listitem>
1131	<para>
1132	Set <emphasis>userfiles</emphasis> (note, this is
1133	not the same parameter as
1134	in <filename>base.config</filename>) to point to the
1135	directory containing the BASE 1.2 files (defined in a
1136	previous step above).
1137	</para>
1138	</listitem>
1139	<listitem>
1140	<para>
1141	Set the <emphasis>pluginDir</emphasis> to point to
1142	the directory where your BASE 1.2 plug-ins are
1143	installed. The default is
1144	<filename
1145	class="directory">/usr/local/base/plugins</filename>.
1146	</para>
1147	</listitem>
1148	<listitem>
1149	<para>
1150	Modify <emphasis>root.password</emphasis>.
1151	</para>
1152	</listitem>
1153	<listitem>
1154	<para>
1155	Change the <emphasis>deletefiles</emphasis> setting
1156	wisely. If you
1157	set <emphasis>deletefiles=yes</emphasis> all BASE
1158	1.2 files will be physically removed when copied to
1159	BASE 2. Leave this options
1160	as <emphasis>deletefiles=no</emphasis> unless you
1161	are absolutely sure of what you are doing.
1162	</para>
1163	</listitem>
1164	</itemizedlist>
1165	</para>
1166	</listitem>
1167
1168	<listitem>
1169	<para>
1170	Run migration utility:
1171	<programlisting>cd /path_to_base/dist/bin
1172	./migrate_from_1.2.sh</programlisting>
1173	</para>
1174	<para>
1175	If the migration fails during the RawBioAssaysData
1176	transfer you can restart the migration at the point of
1177	failure. Simply restart the migration and the script will
1178	ask you to verify that a restart should be attempted. For
1179	all other failure points the migration has to be restarted
1180	with an empty database.
1181	</para>
1182	</listitem>
1183
1184	<listitem>
1185	<para>
1186	Migration done! Happy BASEing.
1187	</para>
1188	</listitem>
1189
1190	</orderedlist>
1191
1192	</para>
1193
1194	</sect1> <!-- Migration instructions -->
1195
1196	</chapter>

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

Context Navigation

source: branches/2.4-stable/doc/src/docbook/admindoc/installation_upgrade.xml @ 3811

Download in other formats: