Context Navigation

installation_upgrade.xml @ 3992

Visit:

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

Fixes #728: jobagent.sh should accept command status

Also made the jobagent log into it's own file (jobagent.log) instead of stdout

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

File size: 43.7 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE chapter PUBLIC
3	"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4	"../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5	<!--
6	$Id: installation_upgrade.xml 3992 2007-11-22 13:19:37Z 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><base-dir>/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><base-dir>/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"><base-dir>/bin/</filename> and issue
231	<programlisting>
232	sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
233	sh ./updateindexes.sh <emphasis>base_root_password</emphasis>
234	</programlisting>
235	where <emphasis>base_root_login</emphasis> is the login
236	for the root user and <emphasis>base_root_password</emphasis> is the
237	password. The login is optional. If not specified,
238	<constant>root</constant> is used as the login.
239	</para>
240	</listitem>
241	</varlistentry>
242
243	<varlistentry>
244	<term>Remove tomcat cache</term>
245	<listitem>
246	<para>
247	As tomcat user, remove cached files and directories. Do
248	something like
249	<programlisting>cd /usr/share/apache-tomcat-5.5.15/
250	rm -rf work/Catalina</programlisting>
251	</para>
252	</listitem>
253	</varlistentry>
254
255	<varlistentry>
256	<term>Start tomcat</term>
257	<listitem>
258	<para>
259	Start the tomcat server: <command>sudo
260	/etc/init.d/tomcat5.5 start</command>
261	</para>
262	</listitem>
263	</varlistentry>
264
265	</variablelist>
266
267	<para>
268	Done! Upgrade of BASE is finished.
269	</para>
270
271	</sect1> <!-- Upgrade instructions -->
272
273
274	<sect1 id="installation_upgrade.jobagents">
275	<title>Installing job agents</title>
276
277	<para>
278	It is important to understand that the BASE application can be
279	spread on to several computers. The main BASE application is
280	serving HTTP requests, the underlying database engine is
281	providing storage and persistence of data, and job agents can be
282	installed on computers that will serve the BASE installation
283	with computing power and perform analysis and run plug-in. In a
284	straight forward setup one computer provides all services needed
285	for running BASE. From this starting point it is easy to add
286	computers to shares load from the BASE server by installing job
287	agents on these additional computers.
288	</para>
289
290	<para>
291	A job agent is a program running on a computer regularly
292	checking the BASE job queue for jobs awaiting execution. When
293	the job agent finds a job that it is enabled to execute, it
294	loads the plug-in and executes it. Job agents will in this way
295	free up resources on the BASE application server, and thus allow
296	the BASE server to concentrate on serving web pages. Job agents
297	are optional and must be installed and setup
298	separately. However, BASE is prepared for job agent setup and to
299	utilize the agents, but the agent are not required.
300	</para>
301
302	<para>
303	A job agent supports many configuration options that are not
304	supported by the internal job queue. For example, you can
305	<itemizedlist>
306	<listitem>
307	<para>
308	Specify exactly which plug-ins each job agent should be
309	able to execute.
310	</para>
311	</listitem>
312	<listitem>
313	<para>
314	Give some plug-ins higher priority than other plug-ins.
315	</para>
316	</listitem>
317	<listitem>
318	<para>
319	Specify which users/groups/projects should be able to use
320	a specific job agent.
321	</para>
322	</listitem>
323	<listitem>
324	<para>
325	Override memory settings and more for each plug-in.
326	</para>
327	</listitem>
328	<listitem>
329	<para>
330	Execute plug-ins in separate processes. Thus, a misbehaving
331	plug-in cannot bring the main application server down.
332	</para>
333	</listitem>
334	<listitem>
335	<para>
336	Add more computers with job agents as needed.
337	</para>
338	</listitem>
339	</itemizedlist>
340	All these options make it possible to create a very flexible
341	setup. For example one job agent can be assigned for importing
342	data only, another job agent can be assigned for running
343	analysis plug-ins for specific project only, and a third may be a
344	catch-all job agent that performs all low-priority jobs.
345	</para>
346
347	<sect2 id="installation_upgrade.jobagents.serverside">
348	<title>BASE application server side setup</title>
349	<para>
350	<variablelist>
351	<varlistentry>
352	<term>Make sure the internal job queue doesn't execute all plug-ins</term>
353	<listitem>
354	<para>
355	The setting <command>jobqueue.internal.runallplugins</command>
356	should be set to <command>false</command> for the
357	BASE server. This setting is found in
358	the <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
359	file. The changes will not take effect until the
360	application server is restarted.
361	</para>
362
363	<note>
364	Prior to BASE 2.5 the internal job queue had to be disabled
365	completely. This is no longer the case since it is possible to
366	enable/disable the internal job queue separately for
367	each plug-in.
368	</note>
369
370	</listitem>
371	</varlistentry>
372	<varlistentry id="installation_upgrade.jobagent.user_account">
373	<term>Enable the job agent user account</term>
374	<listitem>
375	<para>
376	During installation of BASE a user account is created
377	for the job agent. This account is used by the job
378	agents to log on to BASE. The account is disabled by
379	default and must be enabled. Enable the account and
380	set a password using the BASE web interface.
381	The same password must also be set in the
382	<filename>jobagent.properties</filename> file, see
383	item
384	<xref linkend="installation_upgrade.jobagent.client.properties"/>
385	below.
386	</para>
387	</listitem>
388	</varlistentry>
389	</variablelist>
390	</para>
391	</sect2>
392
393	<sect2 id="installation_upgrade.jobagents.database">
394	<title>Database server setup</title>
395	<para>
396	<variablelist>
397	<varlistentry id="installation_upgrade.jobagent.database">
398	<term>Create a user account on the database</term>
399	<listitem>
400	<para>
401	This is the similar to granting database access for
402	the BASE server user in the in the regular BASE
403	installation, cf.
404	<xref
405	linkend="installation_upgrade.installation.database"/>.
406	You must create an account in the database that is
407	allowed to connect from the job agent server. MySQL
408	example:
409	<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
410	GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
411
412	Replace <command>job.agent.host</command> with the
413	host name of the server that is going to run the job
414	agent. You should also set password. This password is
415	used in item
416	<xref linkend="installation_upgrade.jobagent.client.config"/>
417	below in job agent server setup. You can use the same
418	database user and password as in the regular database
419	setup.
420	</para>
421	</listitem>
422	</varlistentry>
423	</variablelist>
424	</para>
425	</sect2>
426
427	<sect2 id="installation_upgrade.jobagents.client">
428	<title>Job agent client setup</title>
429	<para>
430	<variablelist>
431	<varlistentry>
432	<term>Download and unpack a regular BASE 2 distribution</term>
433	<listitem>
434	<para>
435	You <emphasis>must</emphasis> use the same version on
436	the web server and all job agents. You find the
437	downloads at
438	<ulink
439	url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
440	</para>
441	</listitem>
442	</varlistentry>
443	<varlistentry id="installation_upgrade.jobagent.client.config">
444	<term>Edit the <filename>base.config</filename> file</term>
445	<listitem>
446	<para>
447	The <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
448	file must be configured as in regular BASE
449	installation, cf.
450	<xref
451	linkend="installation_upgrade.installation.configuration"/>,
452	to use the same database as the web server
453	application. The most important settings are
454	<itemizedlist>
455	<listitem>
456	<para>
457	<command>db.username</command>: The database
458	user you created in item
459	<xref
460	linkend="installation_upgrade.jobagent.database"/>
461	above.
462	</para>
463	</listitem>
464	<listitem>
465	<para>
466	<command>db.password</command>: The password for
467	the user.
468	</para>
469	</listitem>
470	<listitem>
471	<para>
472	<command>db.url</command>: The connection url to
473	the database.
474	</para>
475	</listitem>
476	<listitem>
477	<para>
478	<command>userfiles</command>: The path to the
479	directory where user files are located. This
480	directory must be accessible from all job
481	agents, i.e., by nfs or other file system
482	sharing method.
483	</para>
484	</listitem>
485	</itemizedlist>
486	See the <xref linkend="appendix.base.config"/> for
487	more information about the settings in
488	the <filename>base.config</filename> file.
489	</para>
490	</listitem>
491	</varlistentry>
492	<varlistentry id="installation_upgrade.jobagent.client.properties">
493	<term>Edit
494	the <filename>jobagent.properties</filename> file</term>
495	<listitem>
496	<para>
497	The <filename><base-dir>/www/WEB-INF/classes/jobagent.properties</filename>
498	file contains settings for the job agent. The most
499	important ones to specify value for are
500	<itemizedlist>
501	<listitem>
502	<para>
503	<command>agent.password</command>: The password
504	you set for the job agent user account in item
505	<xref
506	linkend="installation_upgrade.jobagent.user_account"/>
507	above.
508	</para>
509	</listitem>
510	<listitem>
511	<para>
512	<command>agent.id</command>: An ID that must be
513	unique for each job agent accessing the BASE application.
514	</para>
515	</listitem>
516	<listitem>
517	<para>
518	<command>agent.remotecontrol</command>: The
519	name/ip address of the web server if you want it
520	to be able to display info about running
521	jobs. The job agent will only allow connections
522	from computers specified in this setting.
523	</para>
524	</listitem>
525	</itemizedlist>
526	</para>
527	<para>
528	The <filename>jobagent.properties</filename> file
529	contains many more configuration options. See
530	the <xref linkend="appendix.jobagent.properties"/> for
531	more information.
532	</para>
533	</listitem>
534	</varlistentry>
535	<varlistentry>
536	<term>Register the job agent</term>
537	<listitem>
538	<para>
539	From the <filename>bin</filename> directory, register
540	the job agent with
541	<programlisting>./jobagent.sh register</programlisting>
542	</para>
543	</listitem>
544	</varlistentry>
545	<varlistentry>
546	<term>Start the job agent</term>
547	<listitem>
548	<para>
549	From the <filename>bin</filename> directory, start the
550	job agent with
551	<programlisting>./jobagent.sh start &</programlisting>
552	</para>
553	<para>
554	See the <xref linkend="appendix.jobagent.sh"/>
555	for more information about what you can do
556	with the job agent command line interface.
557	</para>
558	</listitem>
559	</varlistentry>
560	</variablelist>
561	</para>
562	</sect2>
563
564	<sect2 id="installation_upgrade.jobagents.configuration">
565	<title>Configuring the job agent</title>
566	<para>
567	Before the job agent starts executing jobs for you it must be
568	configured. The configuration is done through the BASE web
569	interface. See <xref linkend="plugins.jobagents" />
570	<variablelist>
571	<varlistentry>
572	<term>Configure the plug-ins the job agent should handle</term>
573	<listitem>
574	<para>
575	<itemizedlist>
576	<listitem>
577	<para>
578	Go to the
579	<menuchoice>
580	<guimenu>Administrate</guimenu>
581	<guisubmenu>Plugins</guisubmenu>
582	<guimenuitem>Job agents</guimenuitem>
583	</menuchoice> menu.
584	</para>
585	</listitem>
586	<listitem>
587	<para>
588	Select the job agent and click on the &gbEdit;
589	button.
590	</para>
591	</listitem>
592	<listitem>
593	<para>
594	On the <guilabel>Plugins</guilabel> tab you can
595	specify which plug-ins the job agent should
596	handle. Note that if you have installed external
597	plug-ins on the web server, those plug-ins must be
598	installed on the job agent as well. It is
599	possible to specify different paths to the JAR
600	file for each job agent.
601	</para>
602	</listitem>
603	</itemizedlist>
604	</para>
605	</listitem>
606	</varlistentry>
607	<varlistentry>
608	<term>Grant users access to the job agent</term>
609	<listitem>
610	<para>
611	Use the regular <guilabel>Share</guilabel>
612	functionality to specify which users/groups/projects
613	should be able to use the job agent. You must give
614	them at least <command>USE</command> permission.
615	</para>
616	</listitem>
617	</varlistentry>
618	</variablelist>
619	</para>
620	</sect2>
621
622	</sect1> <!-- job agent setup -->
623
624
625	<sect1 id="installation_upgrade.installation">
626	<title>Installation instructions</title>
627
628	<variablelist>
629
630	<varlistentry>
631	<term>Java</term>
632	<listitem>
633	<para>
634	Download and install Java SDK 1.5, available from
635	<ulink url="http://java.sun.com/" />. Make sure that you
636	download the JDK version (<emphasis>not</emphasis> the JRE
637	version). <command>Java 6 is currently not
638	supported</command> (this will change starting with
639	BASE version 2.5 whereafter only Java 6 will be supported).
640	</para>
641	</listitem>
642	</varlistentry>
643
644	<varlistentry>
645	<term>Tomcat</term>
646	<listitem>
647	<para>
648	Download and install tomcat 5.5.16 or later, available
649	from <ulink
650	url="http://jakarta.apache.org/tomcat/" />
651	<important>
652	You MUST make sure that Tomcat uses the SERVER mode of
653	the Java run time engine
654	(see <ulink
655	url="http://lev.thep.lu.se/trac/base/ticket/99">ticket:99</ulink>).
656	</important>
657	On Linux you do this by setting the environment variable:
658	<code>CATALINA_OPTS</code> to <code>-server</code>. It is
659	also a good idea to specify the maximum allowed memory to
660	use: <code>-server -Xmx500m</code> sets it to 500
661	megabytes. Basically add the next line close to the top of
662	the <filename>catalina.sh</filename> script that comes
663	with tomcat
664	(directory <filename
665	class="directory">bin</filename>):
666	<programlisting>CATALINA_OPTS="-server -Xmx500m"</programlisting>
667	</para>
668	<para>
669	For more information about Tomcat options see
670	<ulink url="http://www.chemaxon.com/jchem/doc/admin/tomcat.html" />.
671	</para>
672	</listitem>
673	</varlistentry>
674
675	<varlistentry>
676	<term>Set up SQL database</term>
677	<listitem>
678	<para>
679	BASE 2
680	utilize <ulink
681	url="http://www.hibernate.org/">Hibernate</ulink> for
682	object persistence to a relational database. Hibernate
683	supports many database engines, but so far we only work
684	with <ulink url="http://www.mysql.com">MySQL</ulink>
685	and <ulink
686	url="http://www.postgresql.org/">PostgreSQL</ulink>.
687	</para>
688
689	<variablelist>
690	<varlistentry>
691	<term>MySQL</term>
692	<listitem>
693	<para>
694	Download and install MySQL (tested with version
695	5.0), available from
696	<ulink url="http://www.mysql.com/" />. You need to
697	be able to connect to the server over TCP, so
698	the <emphasis>skip-networking</emphasis> option
699	must <command>not</command> be used. The InnoDB
700	table engine is also needed, so do not disable them
701	(not that you would) but you may want to tune the
702	InnoDB behaviour before creating BASE
703	databases. BASE comes pre-configured for MySQL so
704	there is no need to change database settings in the
705	BASE configuration files.
706	</para>
707	</listitem>
708	</varlistentry>
709	<varlistentry>
710	<term>PostgreSQL</term>
711	<listitem>
712	<para>
713	PostgreSQL 8.2 seems to be working very well with
714	BASE and Hibernate. Download and install PostgreSQL,
715	available from
716	<ulink url="http://www.postgresql.org/" />. you must
717	edit
718	your <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
719	file. Uncomment the settings for Postgres and
720	comment out the settings for MySQL.
721	</para>
722
723	<note>
724	<para>
725	Postgres versions prior to 8.2 have a non-optimal solution
726	for locking rows in certain situations. This may cause two
727	seemingly independent transactions to lock if they just
728	reference a common database row. This may happen, for example,
729	when importing raw data that have references to the same
730	reporters. The problem has been solved in Postgres 8.2.
731	</para>
732	</note>
733
734	</listitem>
735	</varlistentry>
736	</variablelist>
737
738	</listitem>
739	</varlistentry>
740
741	<varlistentry>
742	<term>BASE (download and unpacking)</term>
743	<listitem>
744	<para>
745	<ulink
746	url="http://base.thep.lu.se/wiki/DownloadPage">Download
747	BASE</ulink> and unpack the downloaded file,
748	i.e. <command>tar zxpf base-...tar.gz</command>. If you
749	prefer to have the bleeding edge version of BASE, perform
750	a checkout of the source from the subversion repository
751	(subversion checkout instructions at
752	<ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
753	trac site</ulink>).
754	</para>
755	<para>
756	If you choose to download the binary package, skip to the
757	next item. The rest of us, read on and compile BASE 2. If
758	you downloaded a source distribution, unpack the
759	downloaded file <command>tar zxpf
760	base-...src.tar.gz</command>, or you may have performed a
761	subversion checkout. Change to the 'root' base2
762	directory, and issue <command>ant
763	package.bin</command>. This will create a binary package
764	in the base2 'root' directory. Unpack this new package
765	(outside of the source file hierarchy), and from now on
766	the instructions are the same irrespective where you got
767	the binary package.
768	</para>
769	<para>
770	<emphasis>This section is intended for advanced users and
771	programmers only. In cases when you want to change the
772	BASE code and try out personalized features it may be
773	advantageous to run the tweaked BASE server against the
774	development tree. Instructions on how to accomplish this
775	is available in the
776	<ulink
777	url="http://base.thep.lu.se/chrome/site/doc/development/build.html">building
778	BASE document</ulink>. When you return back after
779	compiling in the subversion tree you can follow the
780	instruction here (with obvious changes to
781	paths).</emphasis>
782	</para>
783	</listitem>
784	</varlistentry>
785
786	<varlistentry id="installation_upgrade.installation.database">
787	<term>BASE (database engine)</term>
788	<listitem>
789	<para>
790	Instructions for MySQL and PostgreSQL are available
791	below. The database names (base2 and base2dynamic is used
792	here), the <emphasis>db_user</emphasis>, and
793	the <emphasis>db_password</emphasis> can be changed during
794	the creation of the databases. It is recommended to change
795	the <emphasis>db_password</emphasis>, the other changes
796	can be made if desired. The database names,
797	the <emphasis>db_user</emphasis>, and
798	the <emphasis>db_password</emphasis> are needed in a later
799	step below when configuring BASE.
800	</para>
801	<note>
802	Note that the <emphasis>db_user</emphasis> name
803	and <emphasis>db_password</emphasis> set here is used
804	internally by BASE in communication with the database and
805	is never used to log on to the BASE application.
806	</note>
807	<variablelist>
808	<varlistentry>
809	<term>MySQL</term>
810	<listitem>
811	<para>
812	Create a new database for BASE, and add a
813	<emphasis>db_user</emphasis> with at least
814	<emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
815	<emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
816	<emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
817	<emphasis>INDEX</emphasis>,
818	and <emphasis>ALTER</emphasis> permission for the
819	new database. To do this, connect to your MySQL
820	server and issue the next lines:
821	<programlisting>CREATE DATABASE base2;
822	CREATE DATABASE base2dynamic;
823	GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
824	GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
825	</para>
826	<para>
827	The <filename><base-dir>/misc/sql/createdb.mysql.sql</filename>
828	file contains the above statements and can be used
829	by the <filename>mysql</filename> command-line tool
830	(remember to edit
831	the <emphasis>db_user</emphasis>,
832	<emphasis>db_password</emphasis>,
833	and the database names in the script file before
834	executing the command): <command>mysql -uroot -p
835	< ./misc/sql/createdb.mysql.sql</command>. The
836	header in the script file contains further
837	information about the script.
838	</para>
839	</listitem>
840	</varlistentry>
841	<varlistentry>
842	<term>PostgreSQL</term>
843	<listitem>
844	<para>
845	Create a new database for BASE, and add a
846	<emphasis>db_user</emphasis> with the proper
847	privileges. To do this, log in as your PostgreSQL
848	user and issue these lines (omit comments):
849	<programlisting>createuser db_user -P
850	# this will prompt for an password for the new user, and issue two
851	# more question that should be answered with character 'n' for no.
852	createdb --owner db_user --encoding UNICODE base2
853	psql base2
854	# this will start the psql command line tool. Issue the next line
855	# within the tool and quit with a '\q'.
856	CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
857	The <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename>
858	file contains the above statements and can be used
859	by the <filename>psql</filename> command-line tool:
860	<command>psql -f ./misc/sql/createdb.posgres.sql
861	template1</command> The header in the script file
862	contains further information about the script.
863	</para>
864	</listitem>
865	</varlistentry>
866	</variablelist>
867	</listitem>
868	</varlistentry>
869
870	<varlistentry>
871	<term>BASE (file storage setup)</term>
872	<listitem>
873	<para>
874	An area for file storage must be setup. Create an empty
875	directory in a proper location in your file system, and
876	set the owner to be the same as the one that the tomcat
877	server will be running as. Remember this location for
878	later use.
879	</para>
880	</listitem>
881	</varlistentry>
882
883	<varlistentry id="installation_upgrade.installation.configuration">
884	<term>BASE (configuration)</term>
885	<listitem>
886	<para>
887	Basic BASE configuration is done in
888	<filename><base-dir>/www/WEB-INF/classes/base.config</filename>:
889	<itemizedlist>
890	<listitem>
891	Uncomment the database engine section that match your setup.
892	</listitem>
893	<listitem>
894	Modify the <emphasis>db.url</emphasis>,
895	<emphasis>db.dynamic.catalog</emphasis>,
896	<emphasis>db.username</emphasis>,
897	and <emphasis>db.password</emphasis> settings to match
898	your choice above. (<emphasis>database host and
899	database name (e.g. base2)</emphasis>,
900	<emphasis>e.g. base2dynamic</emphasis>,
901	<emphasis>db_user</emphasis>, and
902	<emphasis>db_password</emphasis>, respectively.)
903	</listitem>
904	<listitem>
905	Modify the <emphasis>userfiles</emphasis> setting to
906	match your choice above.
907	</listitem>
908	</itemizedlist>
909	See the <xref linkend="appendix.base.config"/> for more
910	information about the settings in
911	the <filename>base.config</filename> file.
912	</para>
913	<para>
914	<emphasis>Optional but recommended.</emphasis> You may want
915	to modify extended properties to fit your needs. Extended
916	properties are defined in
917	<filename><base-dir>/www/WEB-INF/classes/extended-properties.xml</filename>.
918	There is an
919	administrator <ulink
920	url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html">document
921	discussing extended properties</ulink> available. If you
922	plan to perform a migration of a BASE 1.2 database you
923	should probably not remove any extended properties
924	columns (this is not tested so the outcome is currently
925	undefined). However, adding columns does not affect
926	migration.
927	</para>
928	</listitem>
929	</varlistentry>
930
931	<varlistentry>
932	<term>BASE (database initialization)</term>
933	<listitem>
934	<para>
935	Change directory to
936	<filename class="directory"><base-dir>/bin</filename>
937	and run <filename>initdb.sh</filename> as
938	<programlisting>./initdb.sh [base_root_login] base_root_password</programlisting>
939
940	<important>
941	<para>
942	The <emphasis>base_root_login</emphasis> and
943	<emphasis>base_root_password</emphasis> you use here
944	is given to the BASE web application root user account.
945	The <emphasis>base_root_login</emphasis> is optional. If
946	not specified, <constant>root</constant> is used for
947	the login.
948	</para>
949	</important>
950	If the initialisation script fail, it is most probably a
951	problem related to the underlying database. Make sure that
952	the database accepts network connection and make sure that
953	<emphasis>db_user</emphasis> has proper credentials.
954	</para>
955	</listitem>
956	</varlistentry>
957
958	<varlistentry>
959	<term>BASE and tomcat</term>
960	<listitem>
961	<para>
962	Either move the <filename
963	class="directory"><base-dir>/www</filename> directory
964	to the tomcat <filename class="directory">webapps</filename>
965	directory or create a symbolic link from the tomcat
966	<filename class="directory">webapps</filename> directory to
967	the <filename class="directory"><base-dir>/www</filename>
968	directory
969	<programlisting>cd /path/to/tomcat/webapps
970	ln -s /path_to_base/www base2</programlisting>
971	Start/restart tomcat, and try http://hostname:8080/base2
972	(change <emphasis>hostname</emphasis> to your hostname) in
973	your favourite browser. BASE log-in page should appear
974	after a few seconds.
975	</para>
976	</listitem>
977	</varlistentry>
978
979	<varlistentry>
980	<term>BASE, apache, and apache/tomcat connector</term>
981	<listitem>
982	<para>
983	<emphasis>This step is optional</emphasis>.
984	</para>
985	<para>
986	If you want run the tomcat server through the apache web
987	server, you need to install the apache version 2 web
988	server, available
989	from <ulink
990	url="http://www.apache.org/">http://www.apache.org/</ulink>,
991	and a apache-tomcat connector, available
992	from <ulink
993	url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
994	So, we got you there;-) To be honest, this step is not
995	really well documented since we previously used SuSE 9.3
996	on our demo/test server, and apache/tomcat/mod_jk comes
997	pre-installed. The current server does not use the
998	apache/tomcat connector. What you need to do is something
999	like this
1000	<itemizedlist>
1001	<listitem>
1002	Get that tomcat server running in stand-alone
1003	mode.
1004	</listitem>
1005	<listitem>
1006	Get the apache 2 server running.
1007	</listitem>
1008	<listitem>
1009	Install mod_jk. Note, different version are used for
1010	apache 1.3 and 2. In SuSE 9.3 this step is done by
1011	installing <filename>mod_jk-ap20</filename>.
1012	</listitem>
1013	<listitem>
1014	Create a <filename>workers.properties</filename> file
1015	in the
1016	tomcat <filename class="directory">base</filename>
1017	directory (commonly copied from a template).
1018	</listitem>
1019	<listitem>
1020	Create a <filename>jk.conf</filename> file in the
1021	apache <filename class="directory">conf</filename>
1022	directory (commonly copied from a template), and make
1023	sure that <emphasis>jk</emphasis> is added to the
1024	modules to be loaded when apache starts.
1025	</listitem>
1026	<listitem>
1027	In <filename>jk.conf</filename> add the lines below
1028	and change paths appropriately.
1029	<programlisting># The following lines makes apache aware of the location of
1030	# the /base2 context
1031	Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
1032	<Directory "/srv/www/tomcat5/base/webapps/base2">
1033	Options Indexes FollowSymLinks
1034	allow from all
1035	</Directory>
1036	# The following lines mounts all base2 jsp files to tomcat
1037	JkMount /base2 ajp13
1038	JkMount /base2/* ajp13
1039	# The following lines prohibits users from directly accessing WEB-INF
1040	<Location "/base2/WEB-INF/">
1041	AllowOverride None
1042	deny from all
1043	</Location></programlisting>
1044	</listitem>
1045	</itemizedlist>
1046	You must restart the apache and the tomcat server after above steps.
1047	</para>
1048	</listitem>
1049	</varlistentry>
1050
1051	<varlistentry>
1052	<term>Setup done!</term>
1053	<listitem>
1054	<para>
1055	Happy BASEing. Now you can log on to your BASE 2 server as
1056	user <emphasis>root</emphasis> (use
1057	the <emphasis>base_root_password</emphasis> from the
1058	database initialization step above). You should begin with
1059	creating a couple user accounts, for more information on
1060	how to create user accounts please refer to
1061	<xref linkend="user_administration"/>.
1062	</para>
1063	<para>
1064	If you are planning to perform a migration of data from
1065	BASE 1.2.x please perform the steps in
1066	<xref linkend="installation_upgrade.migration"/> before
1067	doing anything else with your new BASE installation.
1068	</para>
1069	</listitem>
1070	</varlistentry>
1071
1072	</variablelist>
1073
1074	</sect1> <!-- Installation instructions -->
1075
1076
1077	<sect1 id="installation_upgrade.migration">
1078	<title>Migration instructions</title>
1079
1080	<caution>
1081	<title>The disclaimer section</title>
1082	<para>
1083	We have made extensive testing of the migration from BASE1.2
1084	to BASE2. To our knowledge the migration works but we cannot
1085	guarantee perfect functionality. The migration tool is
1086	supplied as is and usage is done at your risk. We are
1087	committed to solve migration problems at the level of
1088	transferring data from BASE 1.2 to 2.2.x, but cannot resolve
1089	data loss issues in a running BASE 2 server due to imperfect
1090	migration. When you start the migration tool you are required
1091	to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1092	to the <filename>migrate_from_1.2.sh</filename>
1093	script. Remember to check that the migration performed well
1094	before you decide to delete your 1.2 installation.
1095	</para>
1096	<para>
1097	Migration from the latest BASE 1.2.x release to the latest is
1098	supported.
1099	</para>
1100	</caution>
1101
1102	<para>
1103	Verify that your BASE 2 installation is up and running before
1104	attempting migration. Preferably try to log in using the root
1105	user through the web interface.
1106	</para>
1107
1108	<para>
1109	Make sure your BASE 1.2 runs with the latest
1110	(<emphasis>pristine</emphasis>) schema
1111	version, <emphasis>i.e.,</emphasis> the migration will only
1112	support an unmodified BASE 1.2 installation. If you have an out
1113	of date schema version, please upgrade to the latest schema
1114	using BASE 1.2 tools before migrating. If you have made local
1115	changes to the BASE 1.2 schema you need to patch the BASE 2
1116	schema as well as make proper changes to the migration program.
1117	If there are added columns to the reporter table in your BASE
1118	1.2 database you need to transfer the additional information
1119	after migration (even if you modified the BASE
1120	2 <filename>extended-properties.xml</filename> file).
1121	</para>
1122
1123	<para>
1124	The behaviour of migration is controlled
1125	through <filename>migration.properties</filename> file (see
1126	<xref linkend="appendix.migrate.properties"/>), but you should
1127	know what you do when you change parameters in this file.
1128	</para>
1129
1130	<para>
1131	Migration can be restarted in one specific case only; If the
1132	migration fails during the RawBioAssaysData transfer simply
1133	restart the migration and the script will ask you to verify that
1134	a restart should be attempted. For all other failure points the
1135	migration has to be restarted with an empty database.
1136	</para>
1137
1138	<para>
1139	Migration is performed with the following steps:
1140	<orderedlist>
1141
1142	<listitem>
1143	<para>
1144	To transfer files from BASE 1.2 (default migration
1145	behaviour), you must have file system access to BASE 1.2
1146	files, <emphasis>i.e.,</emphasis> the <filename
1147	class="directory">/ 1.2/data</filename>
1148	directory containing directories
1149	<filename class="directory">rawdata</filename>,
1150	<filename class="directory">uploads</filename>,
1151	<filename class="directory">protocols</filename>, ...
1152	</para>
1153	</listitem>
1154
1155	<listitem>
1156	<para>
1157	Change settings in the file
1158	<filename><base-dir>/dist/www/WEB-INF/classes/migrate.properties</filename>.
1159	The available options are commented:
1160	<itemizedlist>
1161	<listitem>
1162	<para>
1163	Modify <emphasis>db1.*</emphasis> parameters to
1164	match your BASE 1.2 installation.
1165	</para>
1166	</listitem>
1167	<listitem>
1168	<para>
1169	Set <emphasis>userfiles</emphasis> (note, this is
1170	not the same parameter as
1171	in <filename>base.config</filename>) to point to the
1172	directory containing the BASE 1.2 files (defined in a
1173	previous step above).
1174	</para>
1175	</listitem>
1176	<listitem>
1177	<para>
1178	Set the <emphasis>pluginDir</emphasis> to point to
1179	the directory where your BASE 1.2 plug-ins are
1180	installed. The default is
1181	<filename
1182	class="directory">/usr/local/base/plugins</filename>.
1183	</para>
1184	</listitem>
1185	<listitem>
1186	<para>
1187	Modify <emphasis>root.password</emphasis>.
1188	</para>
1189	</listitem>
1190	<listitem>
1191	<para>
1192	Change the <emphasis>deletefiles</emphasis> setting
1193	wisely. If you
1194	set <emphasis>deletefiles=yes</emphasis> all BASE
1195	1.2 files will be physically removed when copied to
1196	BASE 2. Leave this options
1197	as <emphasis>deletefiles=no</emphasis> unless you
1198	are absolutely sure of what you are doing.
1199	</para>
1200	</listitem>
1201	</itemizedlist>
1202	</para>
1203	</listitem>
1204
1205	<listitem>
1206	<para>
1207	Run migration utility:
1208	<programlisting>cd /path_to_base/dist/bin
1209	./migrate_from_1.2.sh</programlisting>
1210	</para>
1211	<para>
1212	If the migration fails during the RawBioAssaysData
1213	transfer you can restart the migration at the point of
1214	failure. Simply restart the migration and the script will
1215	ask you to verify that a restart should be attempted. For
1216	all other failure points the migration has to be restarted
1217	with an empty database.
1218	</para>
1219	</listitem>
1220
1221	<listitem>
1222	<para>
1223	<emphasis>Optional, depends on your BASE 1.2 reporter
1224	table.</emphasis> Additional columns (as compared with a
1225	pristine database schema) in the reporter table in the
1226	BASE 1.2 schema are not transferred during migration. You
1227	have to perform the transfer manually after
1228	migration. Simply export the reporter information from
1229	BASE 1.2, and import the data into BASE 2. In BASE 1.2: i)
1230	View the reporters, ii) Use `Get as tab-separated text` to
1231	create a tab separated file (right click and save). In
1232	BASE 2, to import the file follow the instructions in
1233	<xref linkend="reporters.import"/>.
1234	</para>
1235	</listitem>
1236
1237	<listitem>
1238	<para>
1239	Migration done! Happy BASEing.
1240	</para>
1241	</listitem>
1242
1243	</orderedlist>
1244
1245	</para>
1246
1247	</sect1> <!-- Migration instructions -->
1248
1249	</chapter>

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

Context Navigation

source: trunk/doc/src/docbook/admindoc/installation_upgrade.xml @ 3992

Download in other formats: