Context Navigation

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

Visit:

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

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

Download in other formats: