Context Navigation

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

Visit:

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

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

Download in other formats: