Changeset 6326
- Timestamp:
- Sep 16, 2013, 2:52:42 PM (10 years ago)
- File:
-
- 1 edited
-
trunk/doc/src/docbook/admin/installation.xml (modified) (22 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/admin/installation.xml
r6324 r6326 9 9 Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg, Martin Svensson 10 10 Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg 11 Copyright (C) 2010, 2011, 2012 Nicklas Nordborg12 Copyright (C) 2013 Jari Häkkinen13 11 14 12 This file is part of BASE - BioArray Software Environment. … … 37 35 These instructions apply only to the BASE release which this 38 36 document is a part of. The instructions here assume 39 that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used37 that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used 40 38 on the server side. Other servlet engines may work but we only 41 39 test with Tomcat. … … 51 49 This section list some important information that may or may not 52 50 apply when upgrading from the <emphasis>previous</emphasis> BASE 53 release to the current release (eg. 3. 1.x to 3.2.x). If you are54 upgrading from a BASE installation that is older (eg. 2.x or 3.0 .xto55 3. 2.x) you should also read <xref linkend="appendix.update_warnings" />.51 release to the current release (eg. 3.2 to 3.3). If you are 52 upgrading from a BASE installation that is older (eg. 2.x or 3.0-3.1 to 53 3.3) you should also read <xref linkend="appendix.update_warnings" />. 56 54 </para> 57 55 58 <bridgehead> Custom logging implementations must be updated</bridgehead>56 <bridgehead>Java SE 7 and Tomcat 7 is required</bridgehead> 59 57 <para> 60 The plug-in functionality for custom logging has been converted 61 to an extension point. The default database logging will continue 62 to function, but custom logging implementations must be converted 63 to an extension. See <xref linkend="appendix.incompatible.3.2" /> and 64 <xref linkend="extensions_developer.logging" /> for more information. 58 BASE now require <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java SE 7</ulink> 59 and <ulink url="http://tomcat.apache.org/download-70.cgi">Tomcat 7</ulink>. Servers with Java SE 6 or Tomcat 6 60 should be updated to newer versions before installing BASE 3.3. 65 61 </para> 66 62 … … 91 87 If the BASE application is not shut down already, it is 92 88 time to do it now. Do something like <command>sudo 93 /etc/init.d/tomcat 6.0 stop</command>89 /etc/init.d/tomcat7.0 stop</command> 94 90 </para> 95 91 … … 227 223 <para> 228 224 Start the Tomcat server: <command>sudo 229 /etc/init.d/tomcat 6.0 start</command>225 /etc/init.d/tomcat7.0 start</command> 230 226 </para> 231 227 </listitem> … … 249 245 <listitem> 250 246 <para> 251 Download and install Java SE 6, available from247 Download and install Java SE 7, available from 252 248 <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />. 253 You can select either the JDK or the JRE version. We have only made a few tests 254 with BASE and Java SE 7. While it seems to be working just fine we can't make 255 any promises or provide any support for it. 249 You can select either the JDK or the JRE version. 250 </para> 251 252 <important> 253 <para> 254 As of BASE 3.3 Java SE 7 is required. BASE will no longer run on 255 Java SE 6 or lower. 256 </para> 257 </important> 258 259 </listitem> 260 </varlistentry> 261 262 <varlistentry> 263 <term>Tomcat</term> 264 <listitem> 265 <para> 266 Download and install Apache Tomcat 7.0.30 or any later 7.x release, 267 available from <ulink url="http://tomcat.apache.org" />. 268 </para> 269 270 <important> 271 <para> 272 As of BASE 3.3 Tomcat 7 is required. BASE will no longer run on 273 Tomcat 6 or lower. 274 </para> 275 </important> 276 277 <para> 278 There are a few configuration options that are needed to 279 make Tomcat work properly with BASE. The options are set in the 280 <code>CATALINA_OPTS</code> environment variable. 281 </para> 282 283 <itemizedlist> 284 <listitem> 285 <para> 286 Increase the amount of memory that Tomcat is allowed to use. The default setting is 287 usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>. 288 </para> 289 </listitem> 290 <listitem> 291 <para> 292 Disable strict parsing of JSP files. 293 <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code> 294 </para> 295 </listitem> 296 <listitem> 297 <para> 298 Unless you have manually downloaded and installed JAI (Java Advanced 299 Imaging) native acceleration libraries (see <ulink 300 url="http://java.sun.com/javase/technologies/desktop/media/jai/" />) 301 it is a good idea to disable the native acceleration of JAI. 302 <code>-Dcom.sun.media.jai.disableMediaLib=true</code> 303 </para> 304 </listitem> 305 <listitem> 306 <para> 307 Enable headless mode if your are setting up a server which doesn't have 308 a display device connected to it. <code>-Djava.awt.headless=true</code>. 309 </para> 310 </listitem> 311 312 </itemizedlist> 313 314 <para> 315 Depending on your system there are probably several ways to set the 316 the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following 317 line (as a single line) close to the top of the <filename>catalina.sh</filename> 318 script that comes with Tomcat (directory <filename 319 class="directory">bin</filename>): 320 <programlisting>CATALINA_OPTS="-Xmx1G 321 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false 322 -Dcom.sun.media.jai.disableMediaLib=true 323 -Djava.awt.headless=true"</programlisting> 324 </para> 325 <para> 326 For more information about Tomcat options see 327 <ulink url="http://tomcat.apache.org/tomcat-7.0-doc/index.html" />. 256 328 </para> 257 329 </listitem> … … 263 335 <para> 264 336 BASE 265 utili se <ulink337 utilize <ulink 266 338 url="http://www.hibernate.org/">Hibernate</ulink> for 267 339 object persistence to a relational database. Hibernate … … 311 383 </varlistentry> 312 384 385 <varlistentry> 386 <term>BASE (download and unpacking)</term> 387 <listitem> 388 <para> 389 <ulink 390 url="http://base.thep.lu.se/wiki/DownloadPage">Download 391 BASE</ulink> and unpack the downloaded file, 392 i.e. <command>tar zxpf base-...tar.gz</command>. If you 393 prefer to have the bleeding edge version of BASE, perform 394 a checkout of the source from the subversion repository 395 (subversion checkout instructions at 396 <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE 397 trac site</ulink>). 398 </para> 399 <para> 400 If you choose to download the binary package, skip to the 401 next item. The rest of us, read on and compile BASE. If 402 you downloaded a source distribution, unpack the 403 downloaded file <command>tar zxpf 404 base-...src.tar.gz</command>, or you may have performed a 405 subversion checkout. Change to the 'root' base2 406 directory, and issue <command>ant 407 package.bin</command>. This will create a binary package 408 in the base2 'root' directory. Unpack this new package 409 (outside of the source file hierarchy), and from now on 410 the instructions are the same irrespective where you got 411 the binary package. 412 </para> 413 <para> 414 <emphasis>This section is intended for advanced users and 415 programmers only. In cases when you want to change the 416 BASE code and try out personalized features it may be 417 advantageous to run the tweaked BASE server against the 418 development tree. Instructions on how to accomplish this 419 is available in the 420 <ulink 421 url="http://base.thep.lu.se/wiki/BuildingBase">building 422 BASE document</ulink>. When you return back after 423 compiling in the subversion tree you can follow the 424 instruction here (with obvious changes to 425 paths).</emphasis> 426 </para> 427 </listitem> 428 </varlistentry> 429 313 430 <varlistentry id="installation.main.database"> 314 431 <term>BASE (database engine)</term> 315 432 <listitem> 316 433 <para> 317 The database names (base2 and base2dynamic are used here), 318 the <emphasis>db_user</emphasis>, and the 319 <emphasis>db_password</emphasis> can be changed during the 320 creation of the databases. It is recommended to change the 321 <emphasis>db_password</emphasis>, the other changes are 322 optional and can be made if desired. The database names, 323 the <emphasis>db_user</emphasis>, and the 324 <emphasis>db_password</emphasis> are needed below when 325 configuring BASE. 434 Instructions for MySQL and PostgreSQL are available 435 below. The database names (base2 and base2dynamic is used 436 here), the <emphasis>db_user</emphasis>, and 437 the <emphasis>db_password</emphasis> can be changed during 438 the creation of the databases. It is recommended to change 439 the <emphasis>db_password</emphasis>, the other changes 440 can be made if desired. The database names, 441 the <emphasis>db_user</emphasis>, and 442 the <emphasis>db_password</emphasis> are needed in a later 443 step below when configuring BASE. 326 444 </para> 327 445 <note> 328 Note that the <emphasis>db_user</emphasis> name and329 <emphasis>db_password</emphasis> set here is used446 Note that the <emphasis>db_user</emphasis> name 447 and <emphasis>db_password</emphasis> set here is used 330 448 internally by BASE in communication with the database and 331 449 is never used to log on to the BASE application. … … 335 453 <para> 336 454 Otherwise there will be a problem with storing values 337 that uses characters outside the normal Latin1 range, 338 forexample unit-related such as µ (micro) and Ω (ohm).455 that uses characters outside the normal Latin1 range, for 456 example unit-related such as µ (micro) and Ω (ohm). 339 457 </para> 340 458 </important> … … 359 477 </para> 360 478 <para> 361 If you download BASE (instructions below) you find a file 362 <filename><base-dir>/misc/sql/createdb.mysql.sql</filename> 363 that contains the above statements and can be used 479 The <filename><base-dir>/misc/sql/createdb.mysql.sql</filename> 480 file contains the above statements and can be used 364 481 by the <filename>mysql</filename> command-line tool 365 (remember to edit the <emphasis>db_user</emphasis>, 366 <emphasis>db_password</emphasis>, and the database 367 names in the script file before executing the 368 command): <command>mysql -uroot -p < 369 <base-dir>/misc/sql/createdb.mysql.sql</command>. The 482 (remember to edit 483 the <emphasis>db_user</emphasis>, 484 <emphasis>db_password</emphasis>, 485 and the database names in the script file before 486 executing the command): <command>mysql -uroot -p 487 < ./misc/sql/createdb.mysql.sql</command>. The 370 488 header in the script file contains further 371 489 information about the script. … … 389 507 # within the tool and quit with a '\q'. 390 508 CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting> 391 392 If you download BASE (instructions below) you find a file 393 <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename> 394 that contains the above statements and can be used 509 The <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename> 510 file contains the above statements and can be used 395 511 by the <filename>psql</filename> command-line tool: 396 <command>psql -f 397 <base-dir>/misc/sql/createdb.posgres.sql 398 template1</command> The header in the script file 512 <command>psql -f ./misc/sql/createdb.posgres.sql 513 template1</command> The header in the script file 399 514 contains further information about the script. 400 515 </para> … … 406 521 407 522 <varlistentry> 408 <term>BASE (download and unpacking)</term>409 <listitem>410 <para>411 <ulink412 url="http://base.thep.lu.se/wiki/DownloadPage">Download413 BASE</ulink> and unpack the downloaded file,414 i.e. <command>tar zxpf base-...tar.gz</command>. If you415 prefer to have the bleeding edge version of BASE, perform416 a checkout of the source from the subversion repository417 (subversion checkout instructions at418 <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE419 trac site</ulink>).420 </para>421 <para>422 If you choose to download the binary package, skip to the423 next item. The rest of us, read on and compile BASE. If424 you downloaded a source distribution, unpack the425 downloaded file <command>tar zxpf426 base-...src.tar.gz</command>, or you may have performed a427 subversion checkout. Change to the 'root' base2428 directory, and issue <command>ant429 package.bin</command>. This will create a binary package430 in the base2 'root' directory. Unpack this new package431 (outside of the source file hierarchy), and from now on432 the instructions are the same irrespective where you got433 the binary package.434 </para>435 <para>436 <emphasis>This section is intended for advanced users and437 programmers only. In cases when you want to change the438 BASE code and try out personalised features it may be439 advantageous to run the tweaked BASE server against the440 development tree. Instructions on how to accomplish this441 is available in the442 <ulink443 url="http://base.thep.lu.se/wiki/BuildingBase">building444 BASE document</ulink>. When you return back after445 compiling in the subversion tree you can follow the446 instruction here (with obvious changes to447 paths).</emphasis>448 </para>449 </listitem>450 </varlistentry>451 452 <varlistentry>453 523 <term>BASE (file storage setup)</term> 454 524 <listitem> 455 525 <para> 456 526 An area for file storage must be setup. Create an empty 457 directory in a proper location in your file system. Set 458 the owner of the created directory to the user the Tomcat 459 server will be running as. Tomcat server set up 460 instructions will follow below. Remember this location for 527 directory in a proper location in your file system, and 528 set the owner to be the same as the one that the Tomcat 529 server will be running as. Remember this location for 461 530 later use. The default location is <filename>/usr/local/base2/files</filename>. 462 531 </para> … … 471 540 Create an empty directory in a proper location in your file system, 472 541 and make sure that the user that the Tomcat 473 server will be running as has read permission in this 474 directory. Tomcat server set up instructions will follow 475 below. Remember this location for 542 server will be running as has read permission. Remember this location for 476 543 later use. The default location is <filename>/usr/local/base2/plugins</filename>. 477 544 </para> … … 532 599 533 600 <varlistentry> 534 <term>BASE (database initiali sation)</term>601 <term>BASE (database initialization)</term> 535 602 <listitem> 536 603 <para> … … 539 606 and execute the following commands: 540 607 <programlisting> 541 sudo./initdb.sh [base_root_login] base_root_password608 ./initdb.sh [base_root_login] base_root_password 542 609 ./updateindexes.sh 543 610 </programlisting> 544 </para> 545 546 <para> 547 In the first command sudo is required because a file will 548 be created in the directory defined by 549 <emphasis>userfiles</emphasis> above. If the directory is 550 writable by you then sudo is not needed. 551 </para> 552 553 <para> 554 The second command is important for PostgreSQL users since 555 the Hibernate database initialisation utility is not able 556 to create all required indexes. BASE will work without the 557 indexes but performance is impaired. Running the script as 558 a MySQL user does not have a negative impact. 559 </para> 611 612 The second command is important for PostgreSQL users 613 since the Hibernate database initialisation utility 614 is not able to create all indexes that are required. 615 BASE will still work without the indexes but performance 616 may suffer. 560 617 561 618 <important> … … 569 626 </para> 570 627 </important> 571 572 <para> 573 If the initialisation script fail, it is probably a 628 If the initialisation script fail, it is most probably a 574 629 problem related to the underlying database. Make sure that 575 630 the database accepts network connection and make sure that 576 <emphasis>db_user</emphasis> has proper credentials. You 577 may also get a <emphasis>Permission denied</emphasis> on 578 file <filename>extension-settings.xml</filename> if you do 579 not have write permission to the directory defined by 580 variable <emphasis>userfiles</emphasis> in file 581 <filename>base.config</filename>. If the initialisation 582 fails on <filename>extension-settings.xml</filename> you 583 must drop the database and recreate the database as 584 described in <xref linkend="installation.main.database"/>. 585 </para> 586 </listitem> 587 </varlistentry> 588 589 <varlistentry> 590 <term>Tomcat</term> 591 <listitem> 592 <para> 593 Download and install Apache Tomcat 6.0.20 or any later 6.x release, 594 available from <ulink url="http://tomcat.apache.org" />. We have only 595 made a few tests with BASE and Tomcat 7. While it seems to be working 596 fine (except for the XJSP compiler) we can't make any promises or 597 provide support for it. 598 There are a few configuration options that are needed to 599 make Tomcat work properly with BASE. The options are set in the 600 <code>CATALINA_OPTS</code> environment variable. 601 </para> 602 603 <itemizedlist> 604 <listitem> 605 <para> 606 Increase the amount of memory that Tomcat is allowed to use. The default setting is 607 usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>. 608 </para> 609 </listitem> 610 <listitem> 611 <para> 612 Disable strict parsing of JSP files. 613 <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code> 614 </para> 615 </listitem> 616 <listitem> 617 <para> 618 Unless you have manually downloaded and installed JAI (Java Advanced 619 Imaging) native acceleration libraries (see <ulink 620 url="http://java.sun.com/javase/technologies/desktop/media/jai/" />) 621 it is a good idea to disable the native acceleration of JAI. 622 <code>-Dcom.sun.media.jai.disableMediaLib=true</code> 623 </para> 624 </listitem> 625 <listitem> 626 <para> 627 Enable headless mode if your are setting up a server which doesn't have 628 a display device connected to it. <code>-Djava.awt.headless=true</code>. 629 </para> 630 </listitem> 631 </itemizedlist> 632 633 <para> 634 Depending on your system there are probably several ways to set the 635 the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following 636 line (as a single line) close to the top of the <filename>catalina.sh</filename> 637 script that comes with Tomcat (directory <filename 638 class="directory">bin</filename>): 639 <programlisting>CATALINA_OPTS="-Xmx1G 640 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false 641 -Dcom.sun.media.jai.disableMediaLib=true 642 -Djava.awt.headless=true"</programlisting> 643 </para> 644 <para> 645 For more information about Tomcat options see 646 <ulink url="http://tomcat.apache.org/tomcat-6.0-doc/index.html" />. 631 <emphasis>db_user</emphasis> has proper credentials. 647 632 </para> 648 633 </listitem> … … 653 638 <listitem> 654 639 <para> 655 Do the following: 656 <itemizedlist> 657 <listitem> 658 <para> 659 Either move the <filename 660 class="directory"><base-dir>/www</filename> 661 directory to the Tomcat <filename 662 class="directory">webapps</filename> directory or 663 create a symbolic link from the Tomcat <filename 664 class="directory">webapps</filename> directory to 665 the <filename 666 class="directory"><base-dir>/www</filename> 667 directory 640 Either move the <filename 641 class="directory"><base-dir>/www</filename> directory 642 to the Tomcat <filename class="directory">webapps</filename> 643 directory or create a symbolic link from the Tomcat 644 <filename class="directory">webapps</filename> directory to 645 the <filename class="directory"><base-dir>/www</filename> 646 directory 668 647 <programlisting>cd /path/to/tomcat/webapps 669 648 ln -s /path_to_base/www base2</programlisting> 670 </para> 671 </listitem> 672 <listitem> 673 <para> 674 Make sure that user Tomcat is running as can read 675 all objects in the directory defined by 676 <emphasis>plugins.dir</emphasis> in file 677 <filename>base.config</filename>. 678 </para> 679 </listitem> 680 <listitem> 681 <para> 682 Make sure that user Tomcat is running as owns (i.e., 683 can read, write, delete and create) all objects in 684 the directory, as well as the directory itself, 685 defined by <emphasis>userfiles</emphasis> in file 686 <filename>base.config</filename>. 687 </para> 688 </listitem> 689 <listitem> 690 <para> 691 If you plan to install extensions you should make 692 sure that the <filename 693 class="directory"><base-dir>/www/extensions</filename> 694 directory is writable by the user account Tomcat is 695 running as. 696 </para> 697 </listitem> 698 </itemizedlist> 699 </para> 700 <para> 701 and finalise with start, or restart, Tomcat, and try 702 http://hostname:8080/base2 (change 703 <emphasis>hostname</emphasis> to your hostname and 704 <emphasis>base2</emphasis> if you selected another name 705 for the BASE Tomcat application) in your favourite 706 browser. The BASE log-in page should appear after a few 707 seconds. 649 </para> 650 <para> 651 If you plan to install extensions you should make sure that 652 the <filename class="directory"><base-dir>/www/extensions</filename> 653 directory is writable by the user account Tomcat is running as. 654 </para> 655 <para> 656 Start/restart Tomcat, and try http://hostname:8080/base2 657 (change <emphasis>hostname</emphasis> to your hostname) in 658 your favourite browser. The BASE log-in page should appear 659 after a few seconds. 708 660 </para> 709 661 </listitem> … … 735 687 user <emphasis>root</emphasis> (use 736 688 the <emphasis>base_root_password</emphasis> from the 737 database initiali sation step above). You should begin with689 database initialization step above). You should begin with 738 690 creating a couple user accounts, for more information on 739 691 how to create user accounts please refer to … … 772 724 are optional and must be installed and setup 773 725 separately. However, BASE is prepared for job agent setup and to 774 utili se the agents, but the agent are not required.726 utilize the agents, but the agent are not required. 775 727 </para> 776 728 … … 1071 1023 agents</guilabel> tab. To do the same from the job agent pages, 1072 1024 go to the edit view of the job agent and select 1073 the <guilabel>Plugins</guilabel> tab. The registration dialog ues1025 the <guilabel>Plugins</guilabel> tab. The registration dialogs 1074 1026 are very similar but only the plug-in side of registration is 1075 1027 described here. The major difference is that it is not possible … … 1481 1433 It is possible to migrate a BASE installation on a MySQL database to a 1482 1434 PostgreSQL database. In a real-world scenario a migration is probably coupled 1483 with a hardware upgrade, i .e. the MySQL installation is on one (the old) server1435 with a hardware upgrade, ie. the MySQL installation is on one (the old) server 1484 1436 and the PostgreSQL installation is on another (the new) server. While 1485 1437 this is not any problem per se, it requires a few extra steps to ensure that … … 1600 1552 directories. 1601 1553 The import program protects against some mistakes by comparing 1602 the colum nnames from the export with the column names in the new1554 the colum names from the export with the column names in the new 1603 1555 database, but it will, for example, not check that data types match. 1604 1556 </para>
Note: See TracChangeset
for help on using the changeset viewer.
