Context Navigation

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

Visit:

Last change on this file since 3775 was 3775, checked in by Johan Enell, 16 years ago

Merged the 2.4.2 release

log:branches/2.4-stable#3694:3770

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

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

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

Download in other formats: