Changeset 6324
- Timestamp:
- Sep 12, 2013, 2:47:41 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
r6129 r6324 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 Nordborg 12 Copyright (C) 2013 Jari Häkkinen 11 13 12 14 This file is part of BASE - BioArray Software Environment. … … 35 37 These instructions apply only to the BASE release which this 36 38 document is a part of. The instructions here assume 37 that <ulink url="http://tomcat.apache.org/">Apache Tomcat 7</ulink> is used39 that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used 38 40 on the server side. Other servlet engines may work but we only 39 41 test with Tomcat. … … 49 51 This section list some important information that may or may not 50 52 apply when upgrading from the <emphasis>previous</emphasis> BASE 51 release to the current release (eg. 3. 2 to 3.3). If you are52 upgrading from a BASE installation that is older (eg. 2.x or 3.0 -3.1to53 3. 3) you should also read <xref linkend="appendix.update_warnings" />.53 release to the current release (eg. 3.1.x to 3.2.x). If you are 54 upgrading from a BASE installation that is older (eg. 2.x or 3.0.x to 55 3.2.x) you should also read <xref linkend="appendix.update_warnings" />. 54 56 </para> 55 57 56 <bridgehead> Java SE 7 and Tomcat 7 is required</bridgehead>58 <bridgehead>Custom logging implementations must be updated</bridgehead> 57 59 <para> 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. 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. 61 65 </para> 62 66 … … 87 91 If the BASE application is not shut down already, it is 88 92 time to do it now. Do something like <command>sudo 89 /etc/init.d/tomcat 7.0 stop</command>93 /etc/init.d/tomcat6.0 stop</command> 90 94 </para> 91 95 … … 223 227 <para> 224 228 Start the Tomcat server: <command>sudo 225 /etc/init.d/tomcat 7.0 start</command>229 /etc/init.d/tomcat6.0 start</command> 226 230 </para> 227 231 </listitem> … … 245 249 <listitem> 246 250 <para> 247 Download and install Java SE 7, available from251 Download and install Java SE 6, available from 248 252 <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />. 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" />. 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. 328 256 </para> 329 257 </listitem> … … 335 263 <para> 336 264 BASE 337 utili ze <ulink265 utilise <ulink 338 266 url="http://www.hibernate.org/">Hibernate</ulink> for 339 267 object persistence to a relational database. Hibernate … … 383 311 </varlistentry> 384 312 385 <varlistentry>386 <term>BASE (download and unpacking)</term>387 <listitem>388 <para>389 <ulink390 url="http://base.thep.lu.se/wiki/DownloadPage">Download391 BASE</ulink> and unpack the downloaded file,392 i.e. <command>tar zxpf base-...tar.gz</command>. If you393 prefer to have the bleeding edge version of BASE, perform394 a checkout of the source from the subversion repository395 (subversion checkout instructions at396 <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE397 trac site</ulink>).398 </para>399 <para>400 If you choose to download the binary package, skip to the401 next item. The rest of us, read on and compile BASE. If402 you downloaded a source distribution, unpack the403 downloaded file <command>tar zxpf404 base-...src.tar.gz</command>, or you may have performed a405 subversion checkout. Change to the 'root' base2406 directory, and issue <command>ant407 package.bin</command>. This will create a binary package408 in the base2 'root' directory. Unpack this new package409 (outside of the source file hierarchy), and from now on410 the instructions are the same irrespective where you got411 the binary package.412 </para>413 <para>414 <emphasis>This section is intended for advanced users and415 programmers only. In cases when you want to change the416 BASE code and try out personalized features it may be417 advantageous to run the tweaked BASE server against the418 development tree. Instructions on how to accomplish this419 is available in the420 <ulink421 url="http://base.thep.lu.se/wiki/BuildingBase">building422 BASE document</ulink>. When you return back after423 compiling in the subversion tree you can follow the424 instruction here (with obvious changes to425 paths).</emphasis>426 </para>427 </listitem>428 </varlistentry>429 430 313 <varlistentry id="installation.main.database"> 431 314 <term>BASE (database engine)</term> 432 315 <listitem> 433 316 <para> 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. 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. 444 326 </para> 445 327 <note> 446 Note that the <emphasis>db_user</emphasis> name 447 and<emphasis>db_password</emphasis> set here is used328 Note that the <emphasis>db_user</emphasis> name and 329 <emphasis>db_password</emphasis> set here is used 448 330 internally by BASE in communication with the database and 449 331 is never used to log on to the BASE application. … … 453 335 <para> 454 336 Otherwise there will be a problem with storing values 455 that uses characters outside the normal Latin1 range, for456 example unit-related such as µ (micro) and Ω (ohm).337 that uses characters outside the normal Latin1 range, 338 for example unit-related such as µ (micro) and Ω (ohm). 457 339 </para> 458 340 </important> … … 477 359 </para> 478 360 <para> 479 The <filename><base-dir>/misc/sql/createdb.mysql.sql</filename> 480 file contains the above statements and can be used 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 481 364 by the <filename>mysql</filename> command-line tool 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 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 488 370 header in the script file contains further 489 371 information about the script. … … 507 389 # within the tool and quit with a '\q'. 508 390 CREATE SCHEMA "dynamic" AUTHORIZATION "db_user";</programlisting> 509 The <filename><base-dir>/misc/sql/createdb.postgresql.sql</filename> 510 file contains the above statements and can be used 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 511 395 by the <filename>psql</filename> command-line tool: 512 <command>psql -f ./misc/sql/createdb.posgres.sql 513 template1</command> The header in the script file 396 <command>psql -f 397 <base-dir>/misc/sql/createdb.posgres.sql 398 template1</command> The header in the script file 514 399 contains further information about the script. 515 400 </para> … … 521 406 522 407 <varlistentry> 408 <term>BASE (download and unpacking)</term> 409 <listitem> 410 <para> 411 <ulink 412 url="http://base.thep.lu.se/wiki/DownloadPage">Download 413 BASE</ulink> and unpack the downloaded file, 414 i.e. <command>tar zxpf base-...tar.gz</command>. If you 415 prefer to have the bleeding edge version of BASE, perform 416 a checkout of the source from the subversion repository 417 (subversion checkout instructions at 418 <ulink url="http://base.thep.lu.se/wiki/DownloadPage">BASE 419 trac site</ulink>). 420 </para> 421 <para> 422 If you choose to download the binary package, skip to the 423 next item. The rest of us, read on and compile BASE. If 424 you downloaded a source distribution, unpack the 425 downloaded file <command>tar zxpf 426 base-...src.tar.gz</command>, or you may have performed a 427 subversion checkout. Change to the 'root' base2 428 directory, and issue <command>ant 429 package.bin</command>. This will create a binary package 430 in the base2 'root' directory. Unpack this new package 431 (outside of the source file hierarchy), and from now on 432 the instructions are the same irrespective where you got 433 the binary package. 434 </para> 435 <para> 436 <emphasis>This section is intended for advanced users and 437 programmers only. In cases when you want to change the 438 BASE code and try out personalised features it may be 439 advantageous to run the tweaked BASE server against the 440 development tree. Instructions on how to accomplish this 441 is available in the 442 <ulink 443 url="http://base.thep.lu.se/wiki/BuildingBase">building 444 BASE document</ulink>. When you return back after 445 compiling in the subversion tree you can follow the 446 instruction here (with obvious changes to 447 paths).</emphasis> 448 </para> 449 </listitem> 450 </varlistentry> 451 452 <varlistentry> 523 453 <term>BASE (file storage setup)</term> 524 454 <listitem> 525 455 <para> 526 456 An area for file storage must be setup. Create an empty 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 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 530 461 later use. The default location is <filename>/usr/local/base2/files</filename>. 531 462 </para> … … 540 471 Create an empty directory in a proper location in your file system, 541 472 and make sure that the user that the Tomcat 542 server will be running as has read permission. Remember this location for 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 543 476 later use. The default location is <filename>/usr/local/base2/plugins</filename>. 544 477 </para> … … 599 532 600 533 <varlistentry> 601 <term>BASE (database initiali zation)</term>534 <term>BASE (database initialisation)</term> 602 535 <listitem> 603 536 <para> … … 606 539 and execute the following commands: 607 540 <programlisting> 608 ./initdb.sh [base_root_login] base_root_password541 sudo ./initdb.sh [base_root_login] base_root_password 609 542 ./updateindexes.sh 610 543 </programlisting> 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. 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> 617 560 618 561 <important> … … 626 569 </para> 627 570 </important> 628 If the initialisation script fail, it is most probably a 571 572 <para> 573 If the initialisation script fail, it is probably a 629 574 problem related to the underlying database. Make sure that 630 575 the database accepts network connection and make sure that 631 <emphasis>db_user</emphasis> has proper credentials. 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" />. 632 647 </para> 633 648 </listitem> … … 638 653 <listitem> 639 654 <para> 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 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 647 668 <programlisting>cd /path/to/tomcat/webapps 648 669 ln -s /path_to_base/www base2</programlisting> 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. 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. 660 708 </para> 661 709 </listitem> … … 687 735 user <emphasis>root</emphasis> (use 688 736 the <emphasis>base_root_password</emphasis> from the 689 database initiali zation step above). You should begin with737 database initialisation step above). You should begin with 690 738 creating a couple user accounts, for more information on 691 739 how to create user accounts please refer to … … 724 772 are optional and must be installed and setup 725 773 separately. However, BASE is prepared for job agent setup and to 726 utili ze the agents, but the agent are not required.774 utilise the agents, but the agent are not required. 727 775 </para> 728 776 … … 1023 1071 agents</guilabel> tab. To do the same from the job agent pages, 1024 1072 go to the edit view of the job agent and select 1025 the <guilabel>Plugins</guilabel> tab. The registration dialog s1073 the <guilabel>Plugins</guilabel> tab. The registration dialogues 1026 1074 are very similar but only the plug-in side of registration is 1027 1075 described here. The major difference is that it is not possible … … 1433 1481 It is possible to migrate a BASE installation on a MySQL database to a 1434 1482 PostgreSQL database. In a real-world scenario a migration is probably coupled 1435 with a hardware upgrade, i e. the MySQL installation is on one (the old) server1483 with a hardware upgrade, i.e. the MySQL installation is on one (the old) server 1436 1484 and the PostgreSQL installation is on another (the new) server. While 1437 1485 this is not any problem per se, it requires a few extra steps to ensure that … … 1552 1600 directories. 1553 1601 The import program protects against some mistakes by comparing 1554 the colum names from the export with the column names in the new1602 the column names from the export with the column names in the new 1555 1603 database, but it will, for example, not check that data types match. 1556 1604 </para>
Note: See TracChangeset
for help on using the changeset viewer.
