Context Navigation

installation_upgrade.xml @ 5031

Visit:

Last change on this file since 5031 was 5031, checked in by Nicklas Nordborg, 14 years ago

References #1353: Update to latest version of 3-rd party software

Updated JAI: 1.1.2 --> 1.1.3

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

File size: 54.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 5031 2009-07-28 12:53:57Z nicklas $
7
8	Copyright (C) 2007 Jari Häkkinen, 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 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25	-->
26
27	<chapter id="installation_upgrade">
28	<?dbhtml dir="installation_upgrade"?>
29
30	<title>Installation, setup, migration, and upgrade instructions</title>
31
32	<note>
33	These instructions apply only to the BASE release which this
34	document is a part of.
35	</note>
36
37	<para>
38	This chapter is divided into four parts. First, the process of
39	upgrading a BASE server is described. Followed by set up of job
40	agents. (For these two first parts it is assumed that there is a
41	running server.) Then, the first time installation instructions
42	follows, and the chapter is concluded with information on how to
43	migrate data from a BASE 1.2.17 server to a current BASE server.
44	</para>
45
46	<para>
47	The first time installation is only to be performed once,
48	optionally followed by a migration. The migration can only be done
49	to a pristine (empty) BASE version 2 server with one exception; The
50	migration can be restarted if it fails during the RawBioAssaysData
51	transfer. For all other failure points the migration has to be
52	restarted with an empty database. Migration from several BASE
53	version 1 installations to one BASE server is not supported.
54	</para>
55
56	<para>
57	The instructions here assume
58	that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used
59	on the server side. Other servlet engines may work but we only
60	test with Tomcat.
61	</para>
62
63
64	<sect1 id="installation_upgrade.upgrade">
65	<title>Upgrade instructions</title>
66
67	<important id="installation_upgrade.upgrade.important">
68	<title>Important information for upgrading to the current release</title>
69	<para>
70	This section list some important information that may or may not
71	apply when upgrading from the <emphasis>previous</emphasis> BASE
72	release to the current release (eg. 2.8.x to 2.9.x). If you are
73	upgrading from a BASE installation that is older (eg. 2.7.x to 2.9.x)
74	you should also read <xref linkend="appendix.update_warnings" />.
75	</para>
76
77	<bridgehead>BASE 2.9 must use a database that supports UTF-8</bridgehead>
78	<para>
79	If you are upgrading from BASE 2.8 or lower and your existing
80	database is not using UTF-8 you must convert the database to
81	UTF-8 <emphasis>before you execute the <code>./updatedb.sh</code></emphasis>
82	script.
83	</para>
84	<para>
85	BASE 2.9 includes a utility that can convert an existing MySQL
86	database. After installing the BASE 2.9 files, but <emphasis>before</emphasis>
87	running the <code>./updatedb.sh</code> script, execute the following
88	on the command line:
89	</para>
90	<programlisting>
91	<![CDATA[
92	cd <base-dir>/bin
93	./onetimefix.sh utf8 -x
94	]]>
95	</programlisting>
96
97	<para>
98	The <code>-x</code> option makes the script update the database immediately.
99	You can leave this option out to have it generate a SQL script file
100	(<filename>convert-to-utf8.sql</filename>) instead. The script will by default
101	not try to convert tables that it already thinks are using UTF-8. If the script
102	for some reason is incorrect when detecting this, you can use the option
103	<code>-f</code> to force conversion of all tables.
104	</para>
105
106	<para>
107	The conversion utility only works with MySQL. PostgreSQL users should
108	instead use a backup and restore using as described in the
109	<ulink url="http://www.postgresql.org/docs/8.1/static/backup.html">PostgreSQL manual</ulink>.
110	Eg. dump the existing BASE database, create a new database that uses UTF8 and
111	restore the backup into the new database.
112	</para>
113
114	</important>
115
116	<para>
117	As always, backup your database before attempting an
118	upgrade. The BASE team performs extensive testing before
119	releasing a new version of BASE but there are always a
120	possibility for unexpected events during upgrades. In upgrades
121	requiring a change in the underlying database there is no
122	(supported) way to revert to a previous version of BASE using
123	BASE tools, you need to use your backup for this use case.
124	</para>
125
126	<para>
127	The strategy here is to install the new BASE release to another
128	directory than the one in use. This requires transfer of
129	configuration settings to the new install but more on that
130	below.
131	</para>
132
133	<variablelist>
134	<varlistentry>
135	<term>Shut down the Tomcat server</term>
136	<listitem>
137	<para>
138	If the BASE application is not shut down already, it is
139	time to do it now. Do something like <command>sudo
140	/etc/init.d/tomcat6.0 stop</command>
141	</para>
142
143	<tip>
144	<title>Notify logged in users!</title>
145	<para>
146	If there are users logged in to your BASE server, it may
147	be nice of you to notify them a few minutes prior to shutting
148	down the BASE server. See <xref linkend="installation_upgrade.broadcast" />.
149	</para>
150	</tip>
151	</listitem>
152	</varlistentry>
153
154	<varlistentry>
155	<term>Rename your current server</term>
156	<listitem>
157	<para>
158	Rename your current BASE installation <command>mv
159	/path/to/base /path/to/base_old</command>.
160	</para>
161	</listitem>
162	</varlistentry>
163
164	<varlistentry>
165	<term>Download and unpack BASE</term>
166	<listitem>
167	<para>
168	There are several ways to download BASE. Please refer to
169	section <xref linkend="resources.home_page.download"/> for
170	information on downloading BASE, and select the item
171	matching your download option:
172	</para>
173
174	<variablelist>
175	<varlistentry>
176	<term><emphasis>Pre-compiled package</emphasis></term>
177	<listitem>
178	<para>
179	If you selected to download a pre-compiled package,
180	unpack the downloaded file with <command>tar zxpf
181	base-...tar.gz</command>.
182	</para>
183	</listitem>
184	</varlistentry>
185
186	<varlistentry>
187	<term><emphasis>Source package</emphasis></term>
188	<listitem>
189	<para>
190	If you selected to download a source package, unpack
191	the downloaded file with <command>tar zxpf
192	base-...src.tar.gz</command>. Change to the new
193	directory, and issue <command>ant
194	package.bin</command>. This will create a binary
195	package in the current directory. Unpack this new
196	package (outside of the source file hierarchy).
197	</para>
198	</listitem>
199	</varlistentry>
200
201	<varlistentry>
202	<term><emphasis>Subversion checkout</emphasis></term>
203	<listitem>
204	<para>
205	This option is for advanced users only and is not
206	covered here. Please refer to
207	<xref linkend="core_ref.build"/> for information on
208	this download option.
209	</para>
210	</listitem>
211	</varlistentry>
212
213	</variablelist>
214	</listitem>
215
216	</varlistentry>
217
218	<varlistentry>
219	<term>Transfer files and settings</term>
220	<listitem>
221	<para>
222	Settings from the previous installation must be
223	transferred to the new installation. This is most easily
224	done by comparing the configuration files from the
225	previous install with the new files. Do not just copy the
226	old files to the new install since new options may have
227	appeared.
228	</para>
229	<para>
230	In the main BASE configuration file,
231	<filename><base-dir>/www/WEB-INF/classes/base.config</filename>,
232	fields that needs to be transferred are usually
233	<emphasis>db.username</emphasis>,
234	<emphasis>db.password</emphasis>,
235	and <emphasis>userfiles</emphasis>.
236	</para>
237	<para>
238	Local settings in the raw data
239	tables, <filename><base-dir>/www/WEB-INF/classes/raw-data-types.xml</filename>,
240	may need to be transferred. This also includes all files in
241	the <filename><base-dir>/www/WEB-INF/classes/raw-data-types</filename> and
242	<filename><base-dir>/www/WEB-INF/classes/extended-properties</filename>
243	directories.
244	</para>
245	</listitem>
246	</varlistentry>
247
248	<varlistentry>
249	<term>Updating database schema</term>
250	<listitem>
251	<para>
252	It is recommended that you also perform an update of your
253	database schema. Running the update scripts are not
254	always necessary when upgrading BASE, but the running the
255	update scripts are safe even in cases when there is no
256	need to run them. Change directory
257	to <filename
258	class="directory"><base-dir>/bin/</filename> and issue
259	<programlisting>
260	sh ./updatedb.sh [base_root_login] <emphasis>base_root_password</emphasis>
261	sh ./updateindexes.sh
262	</programlisting>
263	where <emphasis>base_root_login</emphasis> is the login
264	for the root user and <emphasis>base_root_password</emphasis> is the
265	password. The login is optional. If not specified,
266	<constant>root</constant> is used as the login.
267	</para>
268	</listitem>
269	</varlistentry>
270
271	<varlistentry>
272	<term>Remove Tomcat cache</term>
273	<listitem>
274	<para>
275	As Tomcat user, remove cached files and directories. Do
276	something like
277	<programlisting>cd /usr/share/apache-tomcat-6.0/
278	rm -rf work/Catalina</programlisting>
279	</para>
280	</listitem>
281	</varlistentry>
282
283	<varlistentry>
284	<term>Start Tomcat</term>
285	<listitem>
286	<para>
287	Start the Tomcat server: <command>sudo
288	/etc/init.d/tomcat6.0 start</command>
289	</para>
290	</listitem>
291	</varlistentry>
292
293	</variablelist>
294
295	<para>
296	Done! Upgrade of BASE is finished.
297	</para>
298
299	</sect1> <!-- Upgrade instructions -->
300
301
302	<sect1 id="installation_upgrade.jobagents">
303	<title>Installing job agents</title>
304
305	<para>
306	It is important to understand that the BASE application can be
307	spread on to several computers. The main BASE application is
308	serving HTTP requests, the underlying database engine is
309	providing storage and persistence of data, and job agents can be
310	installed on computers that will serve the BASE installation
311	with computing power and perform analysis and run plug-in. In a
312	straight forward setup one computer provides all services needed
313	for running BASE. From this starting point it is easy to add
314	computers to shares load from the BASE server by installing job
315	agents on these additional computers.
316	</para>
317
318	<para>
319	A job agent is a program running on a computer regularly
320	checking the BASE job queue for jobs awaiting execution. When
321	the job agent finds a job that it is enabled to execute, it
322	loads the plug-in and executes it. Job agents will in this way
323	free up resources on the BASE application server, and thus allow
324	the BASE server to concentrate on serving web pages. Job agents
325	are optional and must be installed and setup
326	separately. However, BASE is prepared for job agent setup and to
327	utilize the agents, but the agent are not required.
328	</para>
329
330	<para>
331	A job agent supports many configuration options that are not
332	supported by the internal job queue. For example, you can
333	<itemizedlist>
334	<listitem>
335	<para>
336	Specify exactly which plug-ins each job agent should be
337	able to execute.
338	</para>
339	</listitem>
340	<listitem>
341	<para>
342	Give some plug-ins higher priority than other plug-ins.
343	</para>
344	</listitem>
345	<listitem>
346	<para>
347	Specify which users/groups/projects should be able to use
348	a specific job agent.
349	</para>
350	</listitem>
351	<listitem>
352	<para>
353	Override memory settings and more for each plug-in.
354	</para>
355	</listitem>
356	<listitem>
357	<para>
358	Execute plug-ins in separate processes. Thus, a misbehaving
359	plug-in cannot bring the main application server down.
360	</para>
361	</listitem>
362	<listitem>
363	<para>
364	Add more computers with job agents as needed.
365	</para>
366	</listitem>
367	</itemizedlist>
368	All these options make it possible to create a very flexible
369	setup. For example one job agent can be assigned for importing
370	data only, another job agent can be assigned for running
371	analysis plug-ins for specific project only, and a third may be a
372	catch-all job agent that performs all low-priority jobs.
373	</para>
374
375	<sect2 id="installation_upgrade.jobagents.serverside">
376	<title>BASE application server side setup</title>
377	<para>
378	<variablelist>
379	<varlistentry>
380	<term>Make sure the internal job queue doesn't execute all plug-ins</term>
381	<listitem>
382	<para>
383	The setting <command>jobqueue.internal.runallplugins</command>
384	should be set to <command>false</command> for the
385	BASE server. This setting is found in
386	the <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
387	file. The changes will not take effect until the
388	application server is restarted.
389	</para>
390
391	<note>
392	Prior to BASE 2.5 the internal job queue had to be disabled
393	completely. This is no longer the case since it is possible to
394	enable/disable the internal job queue separately for
395	each plug-in.
396	</note>
397
398	</listitem>
399	</varlistentry>
400	<varlistentry id="installation_upgrade.jobagent.user_account">
401	<term>Enable the job agent user account</term>
402	<listitem>
403	<para>
404	During installation of BASE a user account is created
405	for the job agent. This account is used by the job
406	agents to log on to BASE. The account is disabled by
407	default and must be enabled. Enable the account and
408	set a password using the BASE web interface.
409	The same password must also be set in the
410	<filename>jobagent.properties</filename> file, see
411	item
412	<xref linkend="installation_upgrade.jobagent.client.properties"/>
413	below.
414	</para>
415	</listitem>
416	</varlistentry>
417	</variablelist>
418	</para>
419	</sect2>
420
421	<sect2 id="installation_upgrade.jobagents.database">
422	<title>Database server setup</title>
423	<para>
424	<variablelist>
425	<varlistentry id="installation_upgrade.jobagent.database">
426	<term>Create a user account on the database</term>
427	<listitem>
428	<para>
429	This is the similar to granting database access for
430	the BASE server user in the in the regular BASE
431	installation, cf.
432	<xref
433	linkend="installation_upgrade.installation.database"/>.
434	You must create an account in the database that is
435	allowed to connect from the job agent server. MySQL
436	example:
437	<programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password';
438	GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting>
439
440	Replace <command>job.agent.host</command> with the
441	host name of the server that is going to run the job
442	agent. You should also set password. This password is
443	used in item
444	<xref linkend="installation_upgrade.jobagent.client.config"/>
445	below in job agent server setup. You can use the same
446	database user and password as in the regular database
447	setup.
448	</para>
449	</listitem>
450	</varlistentry>
451	</variablelist>
452	</para>
453	</sect2>
454
455	<sect2 id="installation_upgrade.jobagents.client">
456	<title>Job agent client setup</title>
457	<para>
458	<variablelist>
459	<varlistentry>
460	<term>Download and unpack a regular BASE distribution</term>
461	<listitem>
462	<para>
463	You <emphasis>must</emphasis> use the same version on
464	the web server and all job agents. You find the
465	downloads at
466	<ulink
467	url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink>
468	</para>
469	</listitem>
470	</varlistentry>
471	<varlistentry id="installation_upgrade.jobagent.client.config">
472	<term>Edit the <filename>base.config</filename> file</term>
473	<listitem>
474	<para>
475	The <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
476	file must be configured as in regular BASE
477	installation, cf.
478	<xref
479	linkend="installation_upgrade.installation.configuration"/>,
480	to use the same database as the web server
481	application. The most important settings are
482	<itemizedlist>
483	<listitem>
484	<para>
485	<command>db.username</command>: The database
486	user you created in item
487	<xref
488	linkend="installation_upgrade.jobagent.database"/>
489	above.
490	</para>
491	</listitem>
492	<listitem>
493	<para>
494	<command>db.password</command>: The password for
495	the user.
496	</para>
497	</listitem>
498	<listitem>
499	<para>
500	<command>db.url</command>: The connection url to
501	the database.
502	</para>
503	</listitem>
504	<listitem>
505	<para>
506	<command>userfiles</command>: The path to the
507	directory where user files are located. This
508	directory must be accessible from all job
509	agents, i.e., by nfs or other file system
510	sharing method.
511	</para>
512	</listitem>
513	</itemizedlist>
514	See the <xref linkend="appendix.base.config"/> for
515	more information about the settings in
516	the <filename>base.config</filename> file.
517	</para>
518	</listitem>
519	</varlistentry>
520	<varlistentry id="installation_upgrade.jobagent.client.properties">
521	<term>Edit
522	the <filename>jobagent.properties</filename> file</term>
523	<listitem>
524	<para>
525	The <filename><base-dir>/www/WEB-INF/classes/jobagent.properties</filename>
526	file contains settings for the job agent. The most
527	important ones to specify value for are
528	<itemizedlist>
529	<listitem>
530	<para>
531	<command>agent.password</command>: The password
532	you set for the job agent user account in item
533	<xref
534	linkend="installation_upgrade.jobagent.user_account"/>
535	above.
536	</para>
537	</listitem>
538	<listitem>
539	<para>
540	<command>agent.id</command>: An ID that must be
541	unique for each job agent accessing the BASE application.
542	</para>
543	</listitem>
544	<listitem>
545	<para>
546	<command>agent.remotecontrol</command>: The
547	name/ip address of the web server if you want it
548	to be able to display info about running
549	jobs. The job agent will only allow connections
550	from computers specified in this setting.
551	</para>
552	</listitem>
553	</itemizedlist>
554	</para>
555	<para>
556	The <filename>jobagent.properties</filename> file
557	contains many more configuration options. See
558	the <xref linkend="appendix.jobagent.properties"/> for
559	more information.
560	</para>
561	</listitem>
562	</varlistentry>
563	<varlistentry>
564	<term>Register the job agent</term>
565	<listitem>
566	<para>
567	From the <filename>bin</filename> directory, register
568	the job agent with
569	<programlisting>./jobagent.sh register</programlisting>
570	</para>
571	</listitem>
572	</varlistentry>
573	<varlistentry>
574	<term>Start the job agent</term>
575	<listitem>
576	<para>
577	From the <filename>bin</filename> directory, start the
578	job agent with
579	<programlisting>./jobagent.sh start &</programlisting>
580	</para>
581	<para>
582	See the <xref linkend="appendix.jobagent.sh"/>
583	for more information about what you can do
584	with the job agent command line interface.
585	</para>
586	</listitem>
587	</varlistentry>
588	</variablelist>
589	</para>
590	</sect2>
591
592	<sect2 id="installation_upgrade.jobagents.configuration">
593	<title>Configuring the job agent</title>
594	<para>
595	Before the job agent starts executing jobs for you it must be
596	configured. The configuration is done through the BASE web
597	interface. See <xref linkend="plugins.jobagents" />
598	<variablelist>
599	<varlistentry>
600	<term>Configure the plug-ins the job agent should handle</term>
601	<listitem>
602	<para>
603	<itemizedlist>
604	<listitem>
605	<para>
606	Go to the
607	<menuchoice>
608	<guimenu>Administrate</guimenu>
609	<guisubmenu>Plugins</guisubmenu>
610	<guimenuitem>Job agents</guimenuitem>
611	</menuchoice> menu.
612	</para>
613	</listitem>
614	<listitem>
615	<para>
616	Select the job agent and click on the &gbEdit;
617	button.
618	</para>
619	</listitem>
620	<listitem>
621	<para>
622	On the <guilabel>Plugins</guilabel> tab you can
623	specify which plug-ins the job agent should
624	handle. Note that if you have installed external
625	plug-ins on the web server, those plug-ins must be
626	installed on the job agent as well. It is
627	possible to specify different paths to the JAR
628	file for each job agent.
629	</para>
630	</listitem>
631	</itemizedlist>
632	</para>
633	</listitem>
634	</varlistentry>
635	<varlistentry>
636	<term>Grant users access to the job agent</term>
637	<listitem>
638	<para>
639	Use the regular <guilabel>Share</guilabel>
640	functionality to specify which users/groups/projects
641	should be able to use the job agent. You must give
642	them at least <command>USE</command> permission.
643	</para>
644	</listitem>
645	</varlistentry>
646	</variablelist>
647	</para>
648	</sect2>
649
650	</sect1> <!-- job agent setup -->
651
652
653	<sect1 id="installation_upgrade.installation">
654	<title>Installation instructions</title>
655
656	<variablelist>
657
658	<varlistentry>
659	<term>Java</term>
660	<listitem>
661	<para>
662	Download and install Java SDK 1.6 (aka Java 6), available from
663	<ulink url="http://java.sun.com/" />.
664	</para>
665	</listitem>
666	</varlistentry>
667
668	<varlistentry>
669	<term>Tomcat</term>
670	<listitem>
671	<para>
672	Download and install Apache Tomcat 6.0.14 or later, available
673	from <ulink
674	url="http://tomcat.apache.org" />.
675
676	It is a good idea to specify the maximum allowed memory
677	that Tomcat can use. The default setting is usually not
678	large enough. If you are using Tomcat 6.0.18 or higher
679	you also need to disable strict parsing of JSP files.
680	</para>
681
682	<para>
683	Unless you have manually downloaded and installed JAI (Java Advanced
684	Imaging) native acceleration libraries (see <ulink
685	url="https://jai.dev.java.net/">https://jai.dev.java.net/</ulink>)
686	it is also a good idea to disable the native acceleration of JAI.
687	</para>
688	<para>
689	All of the above is done by setting Java startup options for
690	Tomcat in the <code>CATALINA_OPTS</code> environment variable.
691
692	Basically add the next line (as a single line) close to the top of
693	the <filename>catalina.sh</filename> script that comes
694	with Tomcat
695	(directory <filename
696	class="directory">bin</filename>):
697	<programlisting>CATALINA_OPTS="-Xmx500m
698	-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
699	-Dcom.sun.media.jai.disableMediaLib=true"</programlisting>
700	</para>
701	<para>
702	For more information about Tomcat options see
703	<ulink url="http://tomcat.apache.org/tomcat-6.0-doc/index.html" />.
704	</para>
705	</listitem>
706	</varlistentry>
707
708	<varlistentry>
709	<term>Set up SQL database</term>
710	<listitem>
711	<para>
712	BASE
713	utilize <ulink
714	url="http://www.hibernate.org/">Hibernate</ulink> for
715	object persistence to a relational database. Hibernate
716	supports many database engines, but so far we only work
717	with <ulink url="http://www.mysql.com">MySQL</ulink>
718	and <ulink
719	url="http://www.postgresql.org/">PostgreSQL</ulink>.
720	</para>
721
722	<variablelist>
723	<varlistentry>
724	<term>MySQL</term>
725	<listitem>
726	<para>
727	Download and install MySQL (tested with version
728	5.0), available from
729	<ulink url="http://www.mysql.com/" />. You need to
730	be able to connect to the server over TCP, so
731	the <emphasis>skip-networking</emphasis> option
732	must <command>not</command> be used. The InnoDB
733	table engine is also needed, so do not disable them
734	(not that you would) but you may want to tune the
735	InnoDB behaviour before creating BASE
736	databases. BASE comes pre-configured for MySQL so
737	there is no need to change database settings in the
738	BASE configuration files.
739	</para>
740	</listitem>
741	</varlistentry>
742	<varlistentry>
743	<term>PostgreSQL</term>
744	<listitem>
745	<para>
746	PostgreSQL 8.2 seems to be working very well with
747	BASE and Hibernate. Download and install PostgreSQL,
748	available from
749	<ulink url="http://www.postgresql.org/" />. you must
750	edit
751	your <filename><base-dir>/www/WEB-INF/classes/base.config</filename>
752	file. Uncomment the settings for PostgreSQL and
753	comment out the settings for MySQL.
754	</para>
755
756	<note>
757	<para>
758	PostgreSQL versions prior to 8.2 have a non-optimal solution
759	for locking rows in certain situations. This may cause two
760	seemingly independent transactions to lock if they just
761	reference a common database row. This may happen, for example,
762	when importing raw data that have references to the same
763	reporters. The problem has been solved in PostgreSQL 8.2.
764	</para>
765	</note>
766
767	</listitem>
768	</varlistentry>
769	</variablelist>
770
771	</listitem>
772	</varlistentry>
773
774	<varlistentry>
775	<term>BASE (download and unpacking)</term>
776	<listitem>
777	<para>
778	<ulink
779	url="http://base.thep.lu.se/wiki/DownloadPage">Download
780	BASE</ulink> and unpack the downloaded file,
781	i.e. <command>tar zxpf base-...tar.gz</command>. If you
782	prefer to have the bleeding edge version of BASE, perform
783	a checkout of the source from the subversion repository
784	(subversion checkout instructions at
785	<ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE
786	trac site</ulink>).
787	</para>
788	<para>
789	If you choose to download the binary package, skip to the
790	next item. The rest of us, read on and compile BASE. If
791	you downloaded a source distribution, unpack the
792	downloaded file <command>tar zxpf
793	base-...src.tar.gz</command>, or you may have performed a
794	subversion checkout. Change to the 'root' base2
795	directory, and issue <command>ant
796	package.bin</command>. This will create a binary package
797	in the base2 'root' directory. Unpack this new package
798	(outside of the source file hierarchy), and from now on
799	the instructions are the same irrespective where you got
800	the binary package.
801	</para>
802	<para>
803	<emphasis>This section is intended for advanced users and
804	programmers only. In cases when you want to change the
805	BASE code and try out personalized features it may be
806	advantageous to run the tweaked BASE server against the
807	development tree. Instructions on how to accomplish this
808	is available in the
809	<ulink
810	url="http://base.thep.lu.se/chrome/site/doc/historical/development/build.html">building
811	BASE document</ulink>. When you return back after
812	compiling in the subversion tree you can follow the
813	instruction here (with obvious changes to
814	paths).</emphasis>
815	</para>
816	</listitem>
817	</varlistentry>
818
819	<varlistentry id="installation_upgrade.installation.database">
820	<term>BASE (database engine)</term>
821	<listitem>
822	<para>
823	Instructions for MySQL and PostgreSQL are available
824	below. The database names (base2 and base2dynamic is used
825	here), the <emphasis>db_user</emphasis>, and
826	the <emphasis>db_password</emphasis> can be changed during
827	the creation of the databases. It is recommended to change
828	the <emphasis>db_password</emphasis>, the other changes
829	can be made if desired. The database names,
830	the <emphasis>db_user</emphasis>, and
831	the <emphasis>db_password</emphasis> are needed in a later
832	step below when configuring BASE.
833	</para>
834	<note>
835	Note that the <emphasis>db_user</emphasis> name
836	and <emphasis>db_password</emphasis> set here is used
837	internally by BASE in communication with the database and
838	is never used to log on to the BASE application.
839	</note>
840	<important>
841	<title>The database must use the UTF-8 character set</title>
842	<para>
843	Otherwise there will be a problem with storing values
844	that uses characters outside the normal Latin1 range, for
845	example unit-related such as µ (micro) and Ω (ohm).
846	</para>
847	</important>
848	<variablelist>
849	<varlistentry>
850	<term>MySQL</term>
851	<listitem>
852	<para>
853	Create a new database for BASE, and add a
854	<emphasis>db_user</emphasis> with at least
855	<emphasis>SELECT</emphasis>, <emphasis>INSERT</emphasis>,
856	<emphasis>UPDATE</emphasis>, <emphasis>DELETE</emphasis>,
857	<emphasis>CREATE</emphasis>, <emphasis>DROP</emphasis>,
858	<emphasis>INDEX</emphasis>,
859	and <emphasis>ALTER</emphasis> permission for the
860	new database. To do this, connect to your MySQL
861	server and issue the next lines:
862	<programlisting>CREATE DATABASE base2 DEFAULT CHARACTER SET utf8;
863	CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
864	GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
865	GRANT ALL ON base2dynamic.* TO db_user@localhost;</programlisting>
866	</para>
867	<para>
868	The <filename><base-dir>/misc/sql/createdb.mysql.sql</filename>
869	file contains the above statements and can be used
870	by the <filename>mysql</filename> command-line tool
871	(remember to edit
872	the <emphasis>db_user</emphasis>,
873	<emphasis>db_password</emphasis>,
874	and the database names in the script file before
875	executing the command): <command>mysql -uroot -p
876	< ./misc/sql/createdb.mysql.sql</command>. The
877	header in the script file contains further
878	information about the script.
879	</para>
880	</listitem>
881	</varlistentry>
882	<varlistentry>
883	<term>PostgreSQL</term>
884	<listitem>
885	<para>
886	Create a new database for BASE, and add a
887	<emphasis>db_user</emphasis> with the proper
888	privileges. To do this, log in as your PostgreSQL
889	user and issue these lines (omit comments):
890	<programlisting>createuser db_user -P
891	# this will prompt for an password for the new user, and issue two
892	# more question that should be answered with character 'n' for no.
893	createdb --owner db_user --encoding UTF8 base2
894	psql base2
895	# this will start the psql command line tool. Issue the next line
896	# within the tool and quit with a '\q'.
897	CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting>
898	The <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename>
899	file contains the above statements and can be used
900	by the <filename>psql</filename> command-line tool:
901	<command>psql -f ./misc/sql/createdb.posgres.sql
902	template1</command> The header in the script file
903	contains further information about the script.
904	</para>
905	</listitem>
906	</varlistentry>
907	</variablelist>
908	</listitem>
909	</varlistentry>
910
911	<varlistentry>
912	<term>BASE (file storage setup)</term>
913	<listitem>
914	<para>
915	An area for file storage must be setup. Create an empty
916	directory in a proper location in your file system, and
917	set the owner to be the same as the one that the Tomcat
918	server will be running as. Remember this location for
919	later use.
920	</para>
921	</listitem>
922	</varlistentry>
923
924	<varlistentry id="installation_upgrade.installation.configuration">
925	<term>BASE (configuration)</term>
926	<listitem>
927	<para>
928	Basic BASE configuration is done in
929	<filename><base-dir>/www/WEB-INF/classes/base.config</filename>:
930	<itemizedlist>
931	<listitem>
932	Uncomment the database engine section that match your setup.
933	</listitem>
934	<listitem>
935	Modify the <emphasis>db.url</emphasis>,
936	<emphasis>db.dynamic.catalog</emphasis>,
937	<emphasis>db.username</emphasis>,
938	and <emphasis>db.password</emphasis> settings to match
939	your choice above. (<emphasis>database host and
940	database name (e.g. base2)</emphasis>,
941	<emphasis>e.g. base2dynamic</emphasis>,
942	<emphasis>db_user</emphasis>, and
943	<emphasis>db_password</emphasis>, respectively.)
944	</listitem>
945	<listitem>
946	Modify the <emphasis>userfiles</emphasis> setting to
947	match your choice above.
948	</listitem>
949	</itemizedlist>
950	See the <xref linkend="appendix.base.config"/> for more
951	information about the settings in
952	the <filename>base.config</filename> file.
953	</para>
954	<para>
955	<emphasis>Optional but recommended.</emphasis> You may want
956	to modify extended properties to fit your needs. Extended
957	properties are defined in
958	<filename><base-dir>/www/WEB-INF/classes/extended-properties.xml</filename>.
959	There is an
960	administrator <ulink
961	url="http://base.thep.lu.se/chrome/site/doc/historical/admin/extended-properties.html">document
962	discussing extended properties</ulink> available. If you
963	plan to perform a migration of a BASE version 1.2 database you
964	should probably not remove any extended properties
965	columns (this is not tested so the outcome is currently
966	undefined). However, adding columns does not affect
967	migration.
968	</para>
969	</listitem>
970	</varlistentry>
971
972	<varlistentry>
973	<term>BASE (database initialization)</term>
974	<listitem>
975	<para>
976	Change directory to
977	<filename class="directory"><base-dir>/bin</filename>
978	and execute the following commands:
979	<programlisting>
980	./initdb.sh [base_root_login] base_root_password
981	./updateindexes.sh
982	</programlisting>
983
984	The second command is important for PostgreSQL users
985	since the Hibernate database initialisation utility
986	is not able to create all indexes that are required.
987	BASE will still work without the indexes but performance
988	may suffer.
989
990	<important>
991	<para>
992	The <emphasis>base_root_login</emphasis> and
993	<emphasis>base_root_password</emphasis> you use here
994	is given to the BASE web application root user account.
995	The <emphasis>base_root_login</emphasis> is optional. If
996	not specified, <constant>root</constant> is used for
997	the login.
998	</para>
999	</important>
1000	If the initialisation script fail, it is most probably a
1001	problem related to the underlying database. Make sure that
1002	the database accepts network connection and make sure that
1003	<emphasis>db_user</emphasis> has proper credentials.
1004	</para>
1005	</listitem>
1006	</varlistentry>
1007
1008	<varlistentry>
1009	<term>BASE and Tomcat</term>
1010	<listitem>
1011	<para>
1012	Either move the <filename
1013	class="directory"><base-dir>/www</filename> directory
1014	to the Tomcat <filename class="directory">webapps</filename>
1015	directory or create a symbolic link from the Tomcat
1016	<filename class="directory">webapps</filename> directory to
1017	the <filename class="directory"><base-dir>/www</filename>
1018	directory
1019	<programlisting>cd /path/to/tomcat/webapps
1020	ln -s /path_to_base/www base2</programlisting>
1021	</para>
1022	<para>
1023	If you plan to install extensions you should make sure that
1024	the <filename class="directory"><base-dir>/www/extensions</filename>
1025	directory is writable by the user account Tomcat is running as.
1026	</para>
1027	<para>
1028	Start/restart Tomcat, and try http://hostname:8080/base2
1029	(change <emphasis>hostname</emphasis> to your hostname) in
1030	your favourite browser. The BASE log-in page should appear
1031	after a few seconds.
1032	</para>
1033	</listitem>
1034	</varlistentry>
1035
1036	<varlistentry>
1037	<term>BASE, Apache, and Apache/Tomcat connector</term>
1038	<listitem>
1039	<para>
1040	<emphasis>This step is optional</emphasis>.
1041	</para>
1042	<para>
1043	If you want run the Tomcat server through the Apache web
1044	server, you need to install the Apache version 2 web
1045	server, available
1046	from <ulink
1047	url="http://www.apache.org/">http://www.apache.org/</ulink>,
1048	and a apache-tomcat connector, available
1049	from <ulink
1050	url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>.
1051	So, we got you there;-) To be honest, this step is not
1052	really well documented since we previously used SuSE 9.3
1053	on our demo/test server, and apache/tomcat/mod_jk comes
1054	pre-installed. The current server does not use the
1055	apache/tomcat connector. What you need to do is something
1056	like this
1057	<itemizedlist>
1058	<listitem>
1059	Get that Tomcat server running in stand-alone
1060	mode.
1061	</listitem>
1062	<listitem>
1063	Get the Apache 2 server running.
1064	</listitem>
1065	<listitem>
1066	Install mod_jk. Note, different version are used for
1067	apache 1.3 and 2. In SuSE 9.3 this step is done by
1068	installing <filename>mod_jk-ap20</filename>.
1069	</listitem>
1070	<listitem>
1071	Create a <filename>workers.properties</filename> file
1072	in the
1073	Tomcat <filename class="directory">base</filename>
1074	directory (commonly copied from a template).
1075	</listitem>
1076	<listitem>
1077	Create a <filename>jk.conf</filename> file in the
1078	apache <filename class="directory">conf</filename>
1079	directory (commonly copied from a template), and make
1080	sure that <emphasis>jk</emphasis> is added to the
1081	modules to be loaded when apache starts.
1082	</listitem>
1083	<listitem>
1084	In <filename>jk.conf</filename> add the lines below
1085	and change paths appropriately.
1086	<programlisting># The following lines makes apache aware of the location of
1087	# the /base2 context
1088	Alias /base2 "/srv/www/tomcat6/base/webapps/base2"
1089	<Directory "/srv/www/tomcat6/base/webapps/base2">
1090	Options Indexes FollowSymLinks
1091	allow from all
1092	</Directory>
1093	# The following lines mounts all base2 jsp files to Tomcat
1094	JkMount /base2 ajp13
1095	JkMount /base2/* ajp13
1096	# The following lines prohibits users from directly accessing WEB-INF
1097	<Location "/base2/WEB-INF/">
1098	AllowOverride None
1099	deny from all
1100	</Location></programlisting>
1101	</listitem>
1102	</itemizedlist>
1103	You must restart the Apache and the Tomcat server after above steps.
1104	</para>
1105	</listitem>
1106	</varlistentry>
1107
1108	<varlistentry>
1109	<term>Setup done!</term>
1110	<listitem>
1111	<para>
1112	Happy BASEing. Now you can log on to your BASE server as
1113	user <emphasis>root</emphasis> (use
1114	the <emphasis>base_root_password</emphasis> from the
1115	database initialization step above). You should begin with
1116	creating a couple user accounts, for more information on
1117	how to create user accounts please refer to
1118	<xref linkend="user_administration"/>.
1119	</para>
1120	<para>
1121	If you are planning to perform a migration of data from
1122	BASE version 1.2.x please perform the steps in
1123	<xref linkend="installation_upgrade.migration"/> before
1124	doing anything else with your new BASE installation.
1125	</para>
1126	</listitem>
1127	</varlistentry>
1128
1129	</variablelist>
1130
1131	</sect1> <!-- Installation instructions -->
1132
1133	<sect1 id="installation_upgrade.serverconfigurations">
1134	<title>Server configurations</title>
1135	<para>
1136	Some server configurations can be done when the installation process is finished and
1137	BASE is up and running. Log into BASE with administration rights and then
1138	open the configuration dialog from menu
1139	<menuchoice>
1140	<guimenu>Administrate</guimenu>
1141	<guimenuitem>Server settings</guimenuitem>
1142	</menuchoice>.
1143	Each tab in the configuration dialog-window is described below.
1144	</para>
1145	<variablelist>
1146	<varlistentry>
1147	<term>
1148	<guilabel>File transfer</guilabel>
1149	</term>
1150	<listitem>
1151	<helptext external_id="serverconfig.filetransfer" title="File transfer rate">
1152	<variablelist>
1153	<varlistentry>
1154	<term><guilabel>Max transfer rate</guilabel></term>
1155	<listitem>
1156	<para>
1157	This is a limit of how many bytes of data that should be
1158	transferred per second when uploading files to BASE. Prefixes
1159	like k, M or G can be used for larger values, just like
1160	described in the tab. The limit is per ongoing upload
1161	and the default value is 100MB/s.
1162	</para>
1163	</listitem>
1164	</varlistentry>
1165	<varlistentry>
1166	<term><guilabel>Unlimited</guilabel></term>
1167	<listitem>
1168	<para>
1169	Check this to not limit the transfer rate. In this case, the
1170	Internet connection of the server is the limit.
1171	</para>
1172	</listitem>
1173	</varlistentry>
1174	</variablelist>
1175	</helptext>
1176	</listitem>
1177	</varlistentry>
1178	<varlistentry>
1179	<term>
1180	<guilabel>About</guilabel>
1181	</term>
1182	<listitem>
1183	<helptext external_id="serverconfig.about"
1184	title="Information about the server">
1185	<variablelist>
1186	<varlistentry>
1187	<term><guilabel>Administrator name</guilabel></term>
1188	<listitem>
1189	<para>
1190	Name of the responsible administrator. The name is displayed
1191	at the bottom of each page in BASE and in the about-dialog.
1192	</para>
1193	</listitem>
1194	</varlistentry>
1195	<varlistentry>
1196	<term><guilabel>Administrator email</guilabel></term>
1197	<listitem>
1198	<para>
1199	An email which the administrator can be contacted on. The
1200	administrator name, visible at the bottom of each page, will
1201	be linked to this email address.
1202	</para>
1203	</listitem>
1204	</varlistentry>
1205	<varlistentry>
1206	<term><guilabel>About</guilabel></term>
1207	<listitem>
1208	<para>
1209	Text written in this field is displayed in the
1210	<guilabel>About this server</guilabel> section on the login
1211	page and in the about-dialog window. We recommend changing the
1212	default Latin text to something meaningful, or remove it
1213	to hide the section completely.
1214	</para>
1215	</listitem>
1216	</varlistentry>
1217	</variablelist>
1218	</helptext>
1219	</listitem>
1220	</varlistentry>
1221	<varlistentry>
1222	<term>
1223	<guilabel>Get account</guilabel>
1224	</term>
1225	<listitem>
1226	<helptext external_id="serverconfig.getaccount"
1227	title="Instructions to get an account">
1228	<para>
1229	A description what a none-registered user should do to get
1230	an account on the particular BASE-server. This text is linked
1231	to the <guilabel>Get an account!</guilabel> link on the login
1232	page. We recommend that the Latin text is replaced with some useful
1233	information, or that it is removed to hide the link.
1234	</para>
1235	</helptext>
1236	</listitem>
1237	</varlistentry>
1238	<varlistentry>
1239	<term>
1240	<guilabel>Forgotten password</guilabel>
1241	</term>
1242	<listitem>
1243	<helptext external_id="serverconfig.password"
1244	title="Instructions when password is forgotten.">
1245	<para>
1246	A description what an user should do if the password is forgotten.
1247	This text is linked
1248	to the <guilabel>Forgot your password?</guilabel> link on the login
1249	page. We recommend that the Latin text is replaced with some useful
1250	information, or that it is removed to hide the link.
1251	</para>
1252	</helptext>
1253	</listitem>
1254	</varlistentry>
1255	<varlistentry>
1256	<term>
1257	<guilabel>Links</guilabel>
1258	</term>
1259	<listitem>
1260	<helptext external_id="serverconfig.links" title="Configurable links">
1261	<para>
1262	External configurable link-types inside BASE.
1263	<note>
1264	<para>
1265	Only link-types that have been set will be visible in the web
1266	client.
1267	</para>
1268	</note>
1269	</para>
1270	<variablelist>
1271	<varlistentry>
1272	<term><guilabel>Help</guilabel></term>
1273	<listitem>
1274	<para>
1275	Links to where the help text is located. By default
1276	this is set to the documentation for the latest released
1277	BASE version on the BASE web site,
1278	<ulink
1279	url="http://base.thep.lu.se/chrome/site/doc/html/index.html">
1280	http://base.thep.lu.se/chrome/site/doc/html/index.html</ulink>.
1281
1282	If you want the documentation for a specific version you will
1283	have to setup a site for that yourself and then change the link
1284	to that site. The documentation is included in the downloaded package
1285	in the directory <filename><basedir>/doc/html</filename>.
1286	</para>
1287	</listitem>
1288	</varlistentry>
1289	<varlistentry>
1290	<term>
1291	<guilabel>FAQ</guilabel>
1292	</term>
1293	<listitem>
1294	<para>Where frequently asked questions can be found. Empty by default.</para>
1295	</listitem>
1296	</varlistentry>
1297	<varlistentry>
1298	<term>
1299	<guilabel>Report a bug</guilabel>
1300	</term>
1301	<listitem>
1302	<para>
1303	Where the user could report bugs, feature request or
1304	perhaps other feedback that concerns the program. As default
1305	this is set to the feedback section on BASE web site,
1306	<ulink url="http://base.thep.lu.se/#Feedback">http://base.thep.lu.se/#Feedback</ulink>.
1307	Note that users must login in order to submit information.
1308	</para>
1309	</listitem>
1310	</varlistentry>
1311	</variablelist>
1312	</helptext>
1313	</listitem>
1314	</varlistentry>
1315	</variablelist>
1316
1317	<sect2 id="installation_upgrade.broadcast">
1318	<title>Sending a broadcast message to logged in users</title>
1319
1320	<para>
1321	It is possible to send a message to all logged in user.
1322	Open the
1323	<menuchoice>
1324	<guimenu>Administrate</guimenu>
1325	<guimenuitem>Broadcast message</guimenuitem>
1326	</menuchoice> dialog box.
1327	</para>
1328
1329	<helptext external_id="broadcast.message" title="Broadcast message">
1330	<para>
1331	This dialog allows you to specify a message that is sent to all
1332	logged in users as well as on the login form. It is also possible
1333	to "disable" login.
1334	</para>
1335	<variablelist>
1336	<varlistentry>
1337	<term><guilabel>Title</guilabel></term>
1338	<listitem>
1339	<para>
1340	The title of the message. It should be a short and consice to
1341	avoid confusion. The title will be displayed on a lot of places
1342	and a user may have to click on it to read the more detailed
1343	message.
1344	</para>
1345	</listitem>
1346	</varlistentry>
1347	<varlistentry>
1348	<term><guilabel>Disable login</guilabel></term>
1349	<listitem>
1350	<para>
1351	Mark this checkbox to try to prevent new users from logging in. To
1352	avoid problems that can be caused by blocking the server admin out,
1353	the login is not completely, disabled. Any user can still login but
1354	only after by-passing several warnings.
1355	</para>
1356	</listitem>
1357	</varlistentry>
1358	<varlistentry>
1359	<term><guilabel>Message</guilabel></term>
1360	<listitem>
1361	<para>
1362	If needed, a longer message giving more information. Users may
1363	have to click on a link to be able to see the complete message.
1364	</para>
1365	</listitem>
1366	</varlistentry>
1367	</variablelist>
1368
1369	<note>
1370	The message will be enabled until it is manually removed by saving
1371	an empty form, or until the Tomcat server is restarted. Since the
1372	message is only kept in memory, a restart will always remove it.
1373	</note>
1374
1375	</helptext>
1376
1377	</sect2>
1378
1379	</sect1>
1380
1381	<sect1 id="installation_upgrade.migration">
1382	<title>Migration instructions</title>
1383
1384	<caution>
1385	<title>The disclaimer section</title>
1386	<para>
1387	We have made extensive testing of the migration from BASE
1388	version 1.2 (BASE1.2) to BASE version 2 (BASE2). To our
1389	knowledge the migration works but we cannot
1390	guarantee perfect functionality. The migration tool is
1391	supplied as is and usage is done at your risk. We are
1392	committed to solve migration problems at the level of
1393	transferring data from BASE1.2 to BASE2, but
1394	cannot resolve data loss issues in a running BASE2
1395	server due to imperfect
1396	migration. When you start the migration tool you are required
1397	to pass parameter <emphasis>"disclaimer_understood"</emphasis>
1398	to the <filename>migrate_from_1.2.sh</filename>
1399	script. Remember to check that the migration performed well
1400	before you decide to delete your 1.2 installation.
1401	</para>
1402
1403	<para>
1404	Since BASE 2.6 we no longer actively test or maintain the
1405	migration program. We still accept bug reports and will try
1406	to fix critical bugs, but only if we get help with testing
1407	the fixes before they are released. Supplying a patch for a
1408	bug will increase the chance of getting it fixed.
1409	</para>
1410	</caution>
1411
1412	<para>
1413	Verify that your new BASE installation is up and running before
1414	attempting migration. Preferably try to log in using the root
1415	user through the web interface.
1416	</para>
1417
1418	<para>
1419	Make sure your BASE1.2 runs with the latest
1420	(<emphasis>pristine</emphasis>) schema
1421	version, <emphasis>i.e.,</emphasis> the migration will only
1422	support an unmodified BASE1.2 installation. If you have
1423	an out of date schema version, please upgrade to the latest
1424	schema using BASE1.2 tools before migrating. If you
1425	have made local changes to the BASE1.2 schema you need
1426	to patch the BASE2 schema as well as make proper
1427	changes to the migration program. If there are added columns to
1428	the reporter table in your BASE1.2 database you need to
1429	transfer the additional information after migration (even if you
1430	modified the BASE2 <filename>extended-properties.xml</filename> file).
1431	</para>
1432
1433	<para>
1434	The behaviour of migration is controlled
1435	through <filename>migration.properties</filename> file (see
1436	<xref linkend="appendix.migrate.properties"/>), but you should
1437	know what you do when you change parameters in this file.
1438	</para>
1439
1440	<para>
1441	Migration can be restarted in one specific case only; If the
1442	migration fails during the RawBioAssayData transfer simply
1443	restart the migration and the script will ask you to verify that
1444	a restart should be attempted. For all other failure points the
1445	migration has to be restarted with an empty database.
1446	</para>
1447
1448	<para>
1449	Migration is performed with the following steps:
1450	<orderedlist>
1451
1452	<listitem>
1453	<para>
1454	To transfer files from BASE1.2 (default migration
1455	behaviour), you must have file system access to BASE1.2
1456	files, <emphasis>i.e.,</emphasis>
1457	the <filename class="directory">/BASE 1.2/data</filename>
1458	directory containing directories
1459	<filename class="directory">rawdata</filename>,
1460	<filename class="directory">uploads</filename>,
1461	<filename class="directory">protocols</filename>, ...
1462	</para>
1463	</listitem>
1464
1465	<listitem>
1466	<para>
1467	Change settings in the file
1468	<filename><base-dir>/dist/www/WEB-INF/classes/migrate.properties</filename>.
1469	The available options are commented:
1470	<itemizedlist>
1471	<listitem>
1472	<para>
1473	Modify <emphasis>db1.*</emphasis> parameters to
1474	match your BASE1.2 installation.
1475	</para>
1476	</listitem>
1477	<listitem>
1478	<para>
1479	Set <emphasis>userfiles</emphasis> (note, this is
1480	not the same parameter as
1481	in <filename>base.config</filename>) to point to the
1482	directory containing the BASE1.2 files (defined in a
1483	previous step above).
1484	</para>
1485	</listitem>
1486	<listitem>
1487	<para>
1488	Set the <emphasis>pluginDir</emphasis> to point to
1489	the directory where your BASE1.2 plug-ins are
1490	installed. The default is
1491	<filename
1492	class="directory">/usr/local/base/plugins</filename>.
1493	</para>
1494	</listitem>
1495	<listitem>
1496	<para>
1497	Modify <emphasis>root.password</emphasis>.
1498	</para>
1499	</listitem>
1500	<listitem>
1501	<para>
1502	Change the <emphasis>deletefiles</emphasis> setting
1503	wisely. If you
1504	set <emphasis>deletefiles=yes</emphasis> all BASE1.2
1505	files will be physically removed when copied to the
1506	BASE2 server. Leave this options
1507	as <emphasis>deletefiles=no</emphasis> unless you
1508	are absolutely sure of what you are doing.
1509	</para>
1510	</listitem>
1511	</itemizedlist>
1512	</para>
1513	</listitem>
1514
1515	<listitem>
1516	<para>
1517	Run migration utility:
1518	<programlisting>cd /path_to_base/dist/bin
1519	./migrate_from_1.2.sh disclaimer_understood</programlisting>
1520	</para>
1521	<para>
1522	If the migration fails during the RawBioAssayData
1523	transfer you can restart the migration at the point of
1524	failure. Simply restart the migration and the script will
1525	ask you to verify that a restart should be attempted. For
1526	all other failure points the migration has to be restarted
1527	with an empty database.
1528	</para>
1529	</listitem>
1530
1531	<listitem>
1532	<para>
1533	<emphasis>Optional, depends on your BASE1.2 reporter
1534	table.</emphasis> Additional columns (as compared with a
1535	pristine database schema) in the reporter table in the
1536	BASE1.2 schema are not transferred during migration. You
1537	have to perform the transfer manually after
1538	migration. Simply export the reporter information from
1539	BASE1.2, and import the data into the new BASE installation. In BASE1.2: i)
1540	View the reporters, ii) Use `Get as tab-separated text` to
1541	create a tab separated file (right click and save). In
1542	BASE2, to import the file follow the instructions in
1543	<xref linkend="reporters.import"/>.
1544	</para>
1545	</listitem>
1546
1547	<listitem>
1548	<para>
1549	Migration done! Happy BASEing.
1550	</para>
1551	</listitem>
1552
1553	</orderedlist>
1554
1555	</para>
1556
1557	</sect1> <!-- Migration instructions -->
1558
1559	</chapter>

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

Context Navigation

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

Download in other formats: