Context Navigation

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

Visit:

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

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

Download in other formats: