Changeset 5737
- Timestamp:
- Sep 14, 2011, 2:36:05 PM (11 years ago)
- Location:
- trunk
- Files:
-
- 3 deleted
- 9 edited
- 4 moved
Legend:
- Unmodified
- Added
- Removed
-
trunk/build.xml
r5718 r5737 1289 1289 <mkdir dir="${docbook.html.out}/admindoc/user_administration"/> 1290 1290 <mkdir dir="${docbook.html.out}/admindoc/installation_upgrade"/> 1291 <mkdir dir="${docbook.html.out}/admindoc/plugin _installation"/>1291 <mkdir dir="${docbook.html.out}/admindoc/plugins"/> 1292 1292 <mkdir dir="${docbook.html.out}/admindoc/extensions"/> 1293 1293 <mkdir dir="${docbook.html.out}/admindoc/coreplugin_configuration"/> -
trunk/doc/src/docbook/admindoc/index.xml
r4889 r5737 28 28 <title>Admin documentation</title> 29 29 <include file="installation_upgrade.xml"/> 30 <include file="plugin_installation.xml"/> 31 <include file="extensions.xml" /> 30 <include file="plugins.xml"/> 32 31 <include file="user_administration.xml"/> 33 32 </part> -
trunk/doc/src/docbook/admindoc/installation_upgrade.xml
r5367 r5737 30 30 <?dbhtml dir="installation_upgrade"?> 31 31 32 <title>Installation , setup, migration,and upgrade instructions</title>32 <title>Installation and upgrade instructions</title> 33 33 34 34 <note> 35 <para> 35 36 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 three 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. The first time installation is only to be performed once. 45 </para> 46 47 <para> 48 The instructions here assume 37 document is a part of. The instructions here assume 49 38 that <ulink url="http://tomcat.apache.org/">Apache Tomcat 6</ulink> is used 50 39 on the server side. Other servlet engines may work but we only 51 40 test with Tomcat. 52 </para>53 41 </para> 42 </note> 54 43 55 44 <sect1 id="installation_upgrade.upgrade"> … … 57 46 58 47 <important id="installation_upgrade.upgrade.important"> 59 <title>Important information for upgrading to the current release</title> 48 <title>Important information for upgrading from BASE 2.17 to BASE 3.0-alfa</title> 49 50 <bridgehead>Do not use on a production server!</bridgehead> 60 51 <para> 61 Th is section list some important information that may or may not62 apply when upgrading from the <emphasis>previous</emphasis> BASE63 release to the current release (eg. 2.8.x to 2.9.x). If you are64 upgrading from a BASE installation that is older (eg. 2.7.x to 2.9.x)65 you should also read <xref linkend="appendix.update_warnings" />.52 The update has not been tested enough to consider this a safe option. 53 The update may cause loss of data. Even if the update works, it is not 54 certain that the 3.0-alfa version can be updated to the 3.0-final 55 version. Before updating make sure that you have a backup of your 56 BASE 2.17 database. 66 57 </para> 67 68 <bridgehead> BASE 2.9 must use a database that supports UTF-8</bridgehead>58 59 <bridgehead>Updating is supported from BASE 2.17 only</bridgehead> 69 60 <para> 70 If you are upgrading from BASE 2.8 or lower and your existing 71 database is not using UTF-8 you must convert the database to 72 UTF-8 <emphasis>before you execute the <code>./updatedb.sh</code></emphasis> 73 script. 61 If your BASE is an older version you'll first need to update 62 to BASE 2.17. 74 63 </para> 64 65 <bridgehead>Old plug-ins and extensions may not work</bridgehead> 75 66 <para> 76 BASE 2.9 includes a utility that can convert an existing MySQL 77 database. After installing the BASE 2.9 files, but <emphasis>before</emphasis> 78 running the <code>./updatedb.sh</code> script, execute the following 79 on the command line: 67 The BASE API has changed in several places and it is not certain that 68 plug-ins and extensions developed for BASE 2 works with BASE 3. The 69 update will disable all plug-ins and extensions that are currently installed. 70 Before you update we recommend that you go through all (external) plug-ins 71 and check if there is an updated version. The recommended approach 72 is to first update BASE and then install updated versions of plug-ins 73 and extensions following the instructions in <xref 74 linkend="plugins.installation"/>. 80 75 </para> 81 <programlisting> 82 <![CDATA[ 83 cd <base-dir>/bin 84 ./onetimefix.sh utf8 -x 85 ]]> 86 </programlisting> 87 76 88 77 <para> 89 The <code>-x</code> option makes the script update the database immediately. 90 You can leave this option out to have it generate a SQL script file 91 (<filename>convert-to-utf8.sql</filename>) instead. The script will by default 92 not try to convert tables that it already thinks are using UTF-8. If the script 93 for some reason is incorrect when detecting this, you can use the option 94 <code>-f</code> to force conversion of all tables. 78 If there is no updated version of a specific plug-in you may try 79 a manual re-installation of the old plug-ins. Follow the instructions 80 in <xref linkend="plugins.installation.manual" />. 95 81 </para> 96 82 83 <bridgehead>Batch item importer changes</bridgehead> 97 84 <para> 98 The conversion utility only works with MySQL. PostgreSQL users should 99 instead use a backup and restore using as described in the 100 <ulink url="http://www.postgresql.org/docs/8.1/static/backup.html">PostgreSQL manual</ulink>. 101 Eg. dump the existing BASE database, create a new database that uses UTF8 and 102 restore the backup into the new database. 85 There are several changes to batch item importers that may affect 86 current workflows and file templates used for importing data. 103 87 </para> 104 88 89 <itemizedlist> 90 <listitem> 91 <para> 92 Sample and extract importer: The 'pooled' column is no longer used. 93 Instead a 'parent type' column should be used which should contain 94 the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT). 95 Existing importer configurations and file templates may have to be updated. 96 </para> 97 </listitem> 98 <listitem> 99 <para> 100 Labeled extract importer: This has been deprecated and it is recommended 101 that the Extract importer is used instead. Existing importer configurations 102 should be re-created as extract importer configurations. 103 </para> 104 </listitem> 105 <listitem> 106 <para> 107 Hybridization importer: This has been deprecated and it is recommended 108 that the Physical bioassay importer is used instead. Existing importer configurations 109 should be re-created as physical bioassay importer configurations. 110 </para> 111 </listitem> 112 <listitem> 113 <para> 114 Scan importer: This has been deprecated and it is recommended 115 that the Derived bioassay importer is used instead. Existing importer configurations 116 should be re-created as derived bioassay importer configurations. 117 </para> 118 </listitem> 119 </itemizedlist> 120 121 <note> 122 The deprecated importers can be re-enabled by an administrator, but they are 123 lacking features that are available in the new importers so this is not 124 something that we recommend. 125 </note> 126 105 127 </important> 106 128 … … 196 218 This option is for advanced users only and is not 197 219 covered here. Please refer to 198 < xref linkend="core_ref.build"/> for information on220 <ulink url="http://base.thep.lu.se/wiki/BuildingBase" /> for information on 199 221 this download option. 200 222 </para> … … 261 283 262 284 <varlistentry> 263 <term>Remove Tomcat cache</term>264 <listitem>265 <para>266 As Tomcat user, remove cached files and directories. Do267 something like268 <programlisting>cd /usr/share/apache-tomcat-6.0/269 rm -rf work/Catalina</programlisting>270 </para>271 </listitem>272 </varlistentry>273 274 <varlistentry>275 285 <term>Start Tomcat</term> 276 286 <listitem> … … 290 300 </sect1> <!-- Upgrade instructions --> 291 301 292 293 <sect1 id="installation_upgrade.jobagents"> 294 <title>Installing job agents</title> 295 296 <para> 297 It is important to understand that the BASE application can be 298 spread on to several computers. The main BASE application is 299 serving HTTP requests, the underlying database engine is 300 providing storage and persistence of data, and job agents can be 301 installed on computers that will serve the BASE installation 302 with computing power and perform analysis and run plug-in. In a 303 straight forward setup one computer provides all services needed 304 for running BASE. From this starting point it is easy to add 305 computers to shares load from the BASE server by installing job 306 agents on these additional computers. 307 </para> 308 309 <para> 310 A job agent is a program running on a computer regularly 311 checking the BASE job queue for jobs awaiting execution. When 312 the job agent finds a job that it is enabled to execute, it 313 loads the plug-in and executes it. Job agents will in this way 314 free up resources on the BASE application server, and thus allow 315 the BASE server to concentrate on serving web pages. Job agents 316 are optional and must be installed and setup 317 separately. However, BASE is prepared for job agent setup and to 318 utilize the agents, but the agent are not required. 319 </para> 320 321 <para> 322 A job agent supports many configuration options that are not 323 supported by the internal job queue. For example, you can 324 <itemizedlist> 325 <listitem> 326 <para> 327 Specify exactly which plug-ins each job agent should be 328 able to execute. 329 </para> 330 </listitem> 331 <listitem> 332 <para> 333 Give some plug-ins higher priority than other plug-ins. 334 </para> 335 </listitem> 336 <listitem> 337 <para> 338 Specify which users/groups/projects should be able to use 339 a specific job agent. 340 </para> 341 </listitem> 342 <listitem> 343 <para> 344 Override memory settings and more for each plug-in. 345 </para> 346 </listitem> 347 <listitem> 348 <para> 349 Execute plug-ins in separate processes. Thus, a misbehaving 350 plug-in cannot bring the main application server down. 351 </para> 352 </listitem> 353 <listitem> 354 <para> 355 Add more computers with job agents as needed. 356 </para> 357 </listitem> 358 </itemizedlist> 359 All these options make it possible to create a very flexible 360 setup. For example one job agent can be assigned for importing 361 data only, another job agent can be assigned for running 362 analysis plug-ins for specific project only, and a third may be a 363 catch-all job agent that performs all low-priority jobs. 364 </para> 365 366 <sect2 id="installation_upgrade.jobagents.serverside"> 367 <title>BASE application server side setup</title> 368 <para> 369 <variablelist> 370 <varlistentry> 371 <term>Make sure the internal job queue doesn't execute all plug-ins</term> 302 <sect1 id="installation_upgrade.installation"> 303 <title>Installation instructions</title> 304 305 <variablelist> 306 307 <varlistentry> 308 <term>Java</term> 309 <listitem> 310 <para> 311 Download and install Java SE 6, available from 312 <ulink url="http://www.oracle.com/technetwork/java/javase/downloads/index.html" />. 313 You can select either the JDK or the JRE version. We have not yet tested BASE with 314 Java SE 7 so we can't tell if it works or not. 315 </para> 316 </listitem> 317 </varlistentry> 318 319 <varlistentry> 320 <term>Tomcat</term> 321 <listitem> 322 <para> 323 Download and install Apache Tomcat 6.0.20 or any later 6.x release, 324 available from <ulink 325 url="http://tomcat.apache.org" />. We have not yet tested BASE 326 with Tomcat 7 so we can't tell if it works or not. 327 There are a few configuration options that are needed to 328 make Tomcat work properly with BASE. The options are set in the 329 <code>CATALINA_OPTS</code> environment variable. 330 </para> 331 332 <itemizedlist> 372 333 <listitem> 373 334 <para> 374 The setting <command>jobqueue.internal.runallplugins</command> 375 should be set to <command>false</command> for the 376 BASE server. This setting is found in 377 the <filename><base-dir>/www/WEB-INF/classes/base.config</filename> 378 file. The changes will not take effect until the 379 application server is restarted. 335 Increase the amount of memory that Tomcat is allowed to use. The default setting is 336 usually not enough. To give Tomcat 1 gigabyte, use <code>-Xmx1G</code>. 380 337 </para> 381 382 <note>383 Prior to BASE 2.5 the internal job queue had to be disabled384 completely. This is no longer the case since it is possible to385 enable/disable the internal job queue separately for386 each plug-in.387 </note>388 389 338 </listitem> 390 </varlistentry>391 <varlistentry id="installation_upgrade.jobagent.user_account">392 <term>Enable the job agent user account</term>393 339 <listitem> 394 340 <para> 395 During installation of BASE a user account is created 396 for the job agent. This account is used by the job 397 agents to log on to BASE. The account is disabled by 398 default and must be enabled. Enable the account and 399 set a password using the BASE web interface. 400 The same password must also be set in the 401 <filename>jobagent.properties</filename> file, see 402 item 403 <xref linkend="installation_upgrade.jobagent.client.properties"/> 404 below. 341 Disable strict parsing of JSP files. 342 <code>-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false</code> 405 343 </para> 406 344 </listitem> 407 </varlistentry>408 </variablelist>409 </para>410 </sect2>411 412 <sect2 id="installation_upgrade.jobagents.database">413 <title>Database server setup</title>414 <para>415 <variablelist>416 <varlistentry id="installation_upgrade.jobagent.database">417 <term>Create a user account on the database</term>418 345 <listitem> 419 346 <para> 420 This is the similar to granting database access for 421 the BASE server user in the in the regular BASE 422 installation, cf. 423 <xref 424 linkend="installation_upgrade.installation.database"/>. 425 You must create an account in the database that is 426 allowed to connect from the job agent server. MySQL 427 example: 428 <programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password'; 429 GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting> 430 431 Replace <command>job.agent.host</command> with the 432 host name of the server that is going to run the job 433 agent. You should also set password. This password is 434 used in item 435 <xref linkend="installation_upgrade.jobagent.client.config"/> 436 below in job agent server setup. You can use the same 437 database user and password as in the regular database 438 setup. 347 Unless you have manually downloaded and installed JAI (Java Advanced 348 Imaging) native acceleration libraries (see <ulink 349 url="http://java.sun.com/javase/technologies/desktop/media/jai/" />) 350 it is a good idea to disable the native acceleration of JAI. 351 <code>-Dcom.sun.media.jai.disableMediaLib=true</code> 439 352 </para> 440 353 </listitem> 441 </varlistentry>442 </variablelist>443 </para>444 </sect2>445 446 <sect2 id="installation_upgrade.jobagents.client">447 <title>Job agent client setup</title>448 <para>449 <variablelist>450 <varlistentry>451 <term>Download and unpack a regular BASE distribution</term>452 354 <listitem> 453 355 <para> 454 You <emphasis>must</emphasis> use the same version on 455 the web server and all job agents. You find the 456 downloads at 457 <ulink 458 url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink> 356 Enable headless mode if your are setting up a server which doesn't have 357 a display device connected to is. <code>-Djava.awt.headless=true</code>. 459 358 </para> 460 359 </listitem> 461 </varlistentry>462 <varlistentry id="installation_upgrade.jobagent.client.config">463 <term>Edit the <filename>base.config</filename> file</term>464 <listitem>465 <para>466 The <filename><base-dir>/www/WEB-INF/classes/base.config</filename>467 file must be configured as in regular BASE468 installation, cf.469 <xref470 linkend="installation_upgrade.installation.configuration"/>,471 to use the same database as the web server472 application. The most important settings are473 <itemizedlist>474 <listitem>475 <para>476 <command>db.username</command>: The database477 user you created in item478 <xref479 linkend="installation_upgrade.jobagent.database"/>480 above.481 </para>482 </listitem>483 <listitem>484 <para>485 <command>db.password</command>: The password for486 the user.487 </para>488 </listitem>489 <listitem>490 <para>491 <command>db.url</command>: The connection url to492 the database.493 </para>494 </listitem>495 <listitem>496 <para>497 <command>userfiles</command>: The path to the498 directory where user files are located. This499 directory must be accessible from all job500 agents, i.e., by nfs or other file system501 sharing method.502 </para>503 </listitem>504 </itemizedlist>505 See the <xref linkend="appendix.base.config"/> for506 more information about the settings in507 the <filename>base.config</filename> file.508 </para>509 </listitem>510 </varlistentry>511 <varlistentry id="installation_upgrade.jobagent.client.properties">512 <term>Edit513 the <filename>jobagent.properties</filename> file</term>514 <listitem>515 <para>516 The <filename><base-dir>/www/WEB-INF/classes/jobagent.properties</filename>517 file contains settings for the job agent. The most518 important ones to specify value for are519 <itemizedlist>520 <listitem>521 <para>522 <command>agent.password</command>: The password523 you set for the job agent user account in item524 <xref525 linkend="installation_upgrade.jobagent.user_account"/>526 above.527 </para>528 </listitem>529 <listitem>530 <para>531 <command>agent.id</command>: An ID that must be532 unique for each job agent accessing the BASE application.533 </para>534 </listitem>535 <listitem>536 <para>537 <command>agent.remotecontrol</command>: The538 name/ip address of the web server if you want it539 to be able to display info about running540 jobs. The job agent will only allow connections541 from computers specified in this setting.542 </para>543 </listitem>544 </itemizedlist>545 </para>546 <para>547 The <filename>jobagent.properties</filename> file548 contains many more configuration options. See549 the <xref linkend="appendix.jobagent.properties"/> for550 more information.551 </para>552 </listitem>553 </varlistentry>554 <varlistentry>555 <term>Register the job agent</term>556 <listitem>557 <para>558 From the <filename>bin</filename> directory, register559 the job agent with560 <programlisting>./jobagent.sh register</programlisting>561 </para>562 </listitem>563 </varlistentry>564 <varlistentry>565 <term>Start the job agent</term>566 <listitem>567 <para>568 From the <filename>bin</filename> directory, start the569 job agent with570 <programlisting>./jobagent.sh start &</programlisting>571 </para>572 <para>573 See the <xref linkend="appendix.jobagent.sh"/>574 for more information about what you can do575 with the job agent command line interface.576 </para>577 </listitem>578 </varlistentry>579 </variablelist>580 </para>581 </sect2>582 583 <sect2 id="installation_upgrade.jobagents.configuration">584 <title>Configuring the job agent</title>585 <para>586 Before the job agent starts executing jobs for you it must be587 configured. The configuration is done through the BASE web588 interface. See <xref linkend="plugins.jobagents" />589 <variablelist>590 <varlistentry>591 <term>Configure the plug-ins the job agent should handle</term>592 <listitem>593 <para>594 <itemizedlist>595 <listitem>596 <para>597 Go to the598 <menuchoice>599 <guimenu>Administrate</guimenu>600 <guisubmenu>Plugins</guisubmenu>601 <guimenuitem>Job agents</guimenuitem>602 </menuchoice> menu.603 </para>604 </listitem>605 <listitem>606 <para>607 Select the job agent and click on the &gbEdit;608 button.609 </para>610 </listitem>611 <listitem>612 <para>613 On the <guilabel>Plugins</guilabel> tab you can614 specify which plug-ins the job agent should615 handle. Note that if you have installed external616 plug-ins on the web server, those plug-ins must be617 installed on the job agent as well. It is618 possible to specify different paths to the JAR619 file for each job agent.620 </para>621 </listitem>622 </itemizedlist>623 </para>624 </listitem>625 </varlistentry>626 <varlistentry>627 <term>Grant users access to the job agent</term>628 <listitem>629 <para>630 Use the regular <guilabel>Share</guilabel>631 functionality to specify which users/groups/projects632 should be able to use the job agent. You must give633 them at least <command>USE</command> permission.634 </para>635 </listitem>636 </varlistentry>637 </variablelist>638 </para>639 </sect2>640 641 </sect1> <!-- job agent setup -->642 643 644 <sect1 id="installation_upgrade.installation">645 <title>Installation instructions</title>646 647 <variablelist>648 649 <varlistentry>650 <term>Java</term>651 <listitem>652 <para>653 Download and install Java SDK 1.6 (aka Java 6), available from654 <ulink url="http://java.sun.com/" />.655 </para>656 </listitem>657 </varlistentry>658 659 <varlistentry>660 <term>Tomcat</term>661 <listitem>662 <para>663 Download and install Apache Tomcat 6.0.20 or later, available664 from <ulink665 url="http://tomcat.apache.org" />.666 667 It is a good idea to specify the maximum allowed memory668 that Tomcat can use. The default setting is usually not669 large enough. If you are using Tomcat 6.0.18 or higher670 you also need to disable strict parsing of JSP files.671 </para>672 360 673 <para> 674 Unless you have manually downloaded and installed JAI (Java Advanced 675 Imaging) native acceleration libraries (see <ulink 676 url="https://jai.dev.java.net/">https://jai.dev.java.net/</ulink>) 677 it is also a good idea to disable the native acceleration of JAI. 678 </para> 679 <para> 680 All of the above is done by setting Java startup options for 681 Tomcat in the <code>CATALINA_OPTS</code> environment variable. 682 683 Basically add the next line (as a single line) close to the top of 684 the <filename>catalina.sh</filename> script that comes 685 with Tomcat 686 (directory <filename 361 </itemizedlist> 362 363 <para> 364 Depending on your system there are probably several ways to set the 365 the <code>CATALINA_OPTS</code> variable. One suggestion is to add the following 366 line (as a single line) close to the top of the <filename>catalina.sh</filename> 367 script that comes with Tomcat (directory <filename 687 368 class="directory">bin</filename>): 688 <programlisting>CATALINA_OPTS="-Xmx 500m369 <programlisting>CATALINA_OPTS="-Xmx1G 689 370 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false 690 -Dcom.sun.media.jai.disableMediaLib=true"</programlisting> 371 -Dcom.sun.media.jai.disableMediaLib=true 372 -Djava.awt.headless=true"</programlisting> 691 373 </para> 692 374 <para> … … 698 380 699 381 <varlistentry> 700 <term>Set up SQL database</term>382 <term>Set up an SQL database</term> 701 383 <listitem> 702 384 <para> … … 717 399 <para> 718 400 Download and install MySQL (tested with version 719 5. 0), available from401 5.1), available from 720 402 <ulink url="http://www.mysql.com/" />. You need to 721 403 be able to connect to the server over TCP, so … … 735 417 <listitem> 736 418 <para> 737 PostgreSQL 8. 2seems to be working very well with419 PostgreSQL 8.4 seems to be working very well with 738 420 BASE and Hibernate. Download and install PostgreSQL, 739 421 available from … … 755 437 </para> 756 438 </note> 757 439 <para> 440 We have not yet tested BASE with PostgreSQL 9 so we can't tell 441 if it works or not. 442 </para> 758 443 </listitem> 759 444 </varlistentry> … … 799 484 is available in the 800 485 <ulink 801 url="http://base.thep.lu.se/ chrome/site/doc/historical/development/build.html">building486 url="http://base.thep.lu.se/wiki/BuildingBase">building 802 487 BASE document</ulink>. When you return back after 803 488 compiling in the subversion tree you can follow the … … 908 593 set the owner to be the same as the one that the Tomcat 909 594 server will be running as. Remember this location for 910 later use. 595 later use. The default location is <filename>/usr/local/base2/files</filename>. 596 </para> 597 </listitem> 598 </varlistentry> 599 600 <varlistentry> 601 <term>BASE (plug-in setup)</term> 602 <listitem> 603 <para> 604 An area for plug-in and extensions installation must be setup. 605 Create an empty directory in a proper location in your file system, 606 and make sure that the user that the Tomcat 607 server will be running as has read permission. Remember this location for 608 later use. The default location is <filename>/usr/local/base2/plugins</filename>. 911 609 </para> 912 610 </listitem> … … 936 634 <listitem> 937 635 Modify the <emphasis>userfiles</emphasis> setting to 938 match your choice above. 636 match your choice in file storage setup above. 637 </listitem> 638 <listitem> 639 Modify the <emphasis>plugins.dir</emphasis> setting to 640 match your choice in plug-in setup above. 939 641 </listitem> 940 642 </itemizedlist> … … 1035 737 server, you need to install the Apache version 2 web 1036 738 server, available 1037 from <ulink 1038 url="http://www.apache.org/">http://www.apache.org/</ulink>, 739 from <ulink url="http://httpd.apache.org/" />, 1039 740 and a apache-tomcat connector, available 1040 741 from <ulink 1041 url="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</ulink>. 1042 So, we got you there;-) To be honest, this step is not 1043 really well documented since we previously used SuSE 9.3 1044 on our demo/test server, and apache/tomcat/mod_jk comes 1045 pre-installed. The current server does not use the 1046 apache/tomcat connector. What you need to do is something 1047 like this 1048 <itemizedlist> 1049 <listitem> 1050 Get that Tomcat server running in stand-alone 1051 mode. 1052 </listitem> 1053 <listitem> 1054 Get the Apache 2 server running. 1055 </listitem> 1056 <listitem> 1057 Install mod_jk. Note, different version are used for 1058 apache 1.3 and 2. In SuSE 9.3 this step is done by 1059 installing <filename>mod_jk-ap20</filename>. 1060 </listitem> 1061 <listitem> 1062 Create a <filename>workers.properties</filename> file 1063 in the 1064 Tomcat <filename class="directory">base</filename> 1065 directory (commonly copied from a template). 1066 </listitem> 1067 <listitem> 1068 Create a <filename>jk.conf</filename> file in the 1069 apache <filename class="directory">conf</filename> 1070 directory (commonly copied from a template), and make 1071 sure that <emphasis>jk</emphasis> is added to the 1072 modules to be loaded when apache starts. 1073 </listitem> 1074 <listitem> 1075 In <filename>jk.conf</filename> add the lines below 1076 and change paths appropriately. 1077 <programlisting># The following lines makes apache aware of the location of 1078 # the /base2 context 1079 Alias /base2 "/srv/www/tomcat6/base/webapps/base2" 1080 <Directory "/srv/www/tomcat6/base/webapps/base2"> 1081 Options Indexes FollowSymLinks 1082 allow from all 1083 </Directory> 1084 # The following lines mounts all base2 jsp files to Tomcat 1085 JkMount /base2 ajp13 1086 JkMount /base2/* ajp13 1087 # The following lines prohibits users from directly accessing WEB-INF 1088 <Location "/base2/WEB-INF/"> 1089 AllowOverride None 1090 deny from all 1091 </Location></programlisting> 1092 </listitem> 1093 </itemizedlist> 1094 You must restart the Apache and the Tomcat server after above steps. 742 url="http://tomcat.apache.org/connectors-doc/index.html" /> 1095 743 </para> 1096 744 </listitem> … … 1109 757 <xref linkend="user_administration"/>. 1110 758 </para> 1111 <para>1112 If you are planning to perform a migration of data from1113 BASE version 1.2.x please perform the steps in1114 <xref linkend="installation_upgrade.migration"/> before1115 doing anything else with your new BASE installation.1116 </para>1117 759 </listitem> 1118 760 </varlistentry> … … 1121 763 1122 764 </sect1> <!-- Installation instructions --> 765 766 <sect1 id="installation_upgrade.jobagents"> 767 <title>Installing job agents</title> 768 769 <para> 770 It is important to understand that the BASE application can be 771 spread on to several computers. The main BASE application is 772 serving HTTP requests, the underlying database engine is 773 providing storage and persistence of data, and job agents can be 774 installed on computers that will serve the BASE installation 775 with computing power and perform analysis and run plug-ins. In a 776 straight forward setup one computer provides all services needed 777 for running BASE. From this starting point it is easy to add 778 computers to shares load from the BASE server by installing job 779 agents on these additional computers. 780 </para> 781 782 <para> 783 A job agent is a program running on a computer regularly 784 checking the BASE job queue for jobs awaiting execution. When 785 the job agent finds a job that it is enabled to execute, it 786 loads the plug-in and executes it. Job agents will in this way 787 free up resources on the BASE application server, and thus allow 788 the BASE server to concentrate on serving web pages. Job agents 789 are optional and must be installed and setup 790 separately. However, BASE is prepared for job agent setup and to 791 utilize the agents, but the agent are not required. 792 </para> 793 794 <para> 795 A job agent supports many configuration options that are not 796 supported by the internal job queue. For example, you can 797 <itemizedlist> 798 <listitem> 799 <para> 800 Specify exactly which plug-ins each job agent should be 801 able to execute. 802 </para> 803 </listitem> 804 <listitem> 805 <para> 806 Give some plug-ins higher priority than other plug-ins. 807 </para> 808 </listitem> 809 <listitem> 810 <para> 811 Specify which users/groups/projects should be able to use 812 a specific job agent. 813 </para> 814 </listitem> 815 <listitem> 816 <para> 817 Override memory settings and more for each plug-in. 818 </para> 819 </listitem> 820 <listitem> 821 <para> 822 Execute plug-ins in separate processes. Thus, a misbehaving 823 plug-in cannot bring the main application server down. 824 </para> 825 </listitem> 826 <listitem> 827 <para> 828 Add more computers with job agents as needed. 829 </para> 830 </listitem> 831 </itemizedlist> 832 All these options make it possible to create a very flexible 833 setup. For example one job agent can be assigned for importing 834 data only, another job agent can be assigned for running 835 analysis plug-ins for specific project only, and a third may be a 836 catch-all job agent that performs all low-priority jobs. 837 </para> 838 839 <sect2 id="installation_upgrade.jobagents.serverside"> 840 <title>BASE application server side setup</title> 841 <para> 842 <variablelist> 843 <varlistentry> 844 <term>Make sure the internal job queue doesn't execute all plug-ins</term> 845 <listitem> 846 <para> 847 The setting <command>jobqueue.internal.runallplugins</command> 848 should be set to <command>false</command> for the 849 BASE server. This setting is found in 850 the <filename><base-dir>/www/WEB-INF/classes/base.config</filename> 851 file. The changes will not take effect until the 852 application server is restarted. 853 </para> 854 855 </listitem> 856 </varlistentry> 857 <varlistentry id="installation_upgrade.jobagent.user_account"> 858 <term>Enable the job agent user account</term> 859 <listitem> 860 <para> 861 During installation of BASE a user account is created 862 for the job agent. This account is used by the job 863 agents to log on to BASE. The account is disabled by 864 default and must be enabled. Enable the account and 865 set a password using the BASE web interface. 866 The same password must also be set in the 867 <filename>jobagent.properties</filename> file, see 868 item 869 <xref linkend="installation_upgrade.jobagent.client.properties"/> 870 below. 871 </para> 872 </listitem> 873 </varlistentry> 874 </variablelist> 875 </para> 876 </sect2> 877 878 <sect2 id="installation_upgrade.jobagents.database"> 879 <title>Database server setup</title> 880 <para> 881 <variablelist> 882 <varlistentry id="installation_upgrade.jobagent.database"> 883 <term>Create a user account on the database</term> 884 <listitem> 885 <para> 886 This is the similar to granting database access for 887 the BASE server user in the in the regular BASE 888 installation, cf. 889 <xref 890 linkend="installation_upgrade.installation.database"/>. 891 You must create an account in the database that is 892 allowed to connect from the job agent server. MySQL 893 example: 894 <programlisting>GRANT ALL ON base2.* TO db_user@job.agent.host IDENTIFIED BY 'db_password'; 895 GRANT ALL ON base2dynamic.* TO db_user@job.agent.host;</programlisting> 896 897 Replace <command>job.agent.host</command> with the 898 host name of the server that is going to run the job 899 agent. You should also set password. This password is 900 used in item 901 <xref linkend="installation_upgrade.jobagent.client.config"/> 902 below in job agent server setup. You can use the same 903 database user and password as in the regular database 904 setup. 905 </para> 906 </listitem> 907 </varlistentry> 908 </variablelist> 909 </para> 910 </sect2> 911 912 <sect2 id="installation_upgrade.jobagents.client"> 913 <title>Job agent client setup</title> 914 <para> 915 <variablelist> 916 <varlistentry> 917 <term>Download and unpack a regular BASE distribution</term> 918 <listitem> 919 <para> 920 You <emphasis>must</emphasis> use the same version on 921 the web server and all job agents. You find the 922 downloads at 923 <ulink 924 url="http://base.thep.lu.se/wiki/DownloadPage">http://base.thep.lu.se/wiki/DownloadPage</ulink> 925 </para> 926 </listitem> 927 </varlistentry> 928 <varlistentry id="installation_upgrade.jobagent.client.config"> 929 <term>Edit the <filename>base.config</filename> file</term> 930 <listitem> 931 <para> 932 The <filename><base-dir>/www/WEB-INF/classes/base.config</filename> 933 file must be configured as in regular BASE 934 installation, cf. 935 <xref 936 linkend="installation_upgrade.installation.configuration"/>, 937 to use the same database as the web server 938 application. The most important settings are 939 <itemizedlist> 940 <listitem> 941 <para> 942 <command>db.username</command>: The database 943 user you created in item 944 <xref 945 linkend="installation_upgrade.jobagent.database"/> 946 above. 947 </para> 948 </listitem> 949 <listitem> 950 <para> 951 <command>db.password</command>: The password for 952 the user. 953 </para> 954 </listitem> 955 <listitem> 956 <para> 957 <command>db.url</command>: The connection url to 958 the database. 959 </para> 960 </listitem> 961 <listitem> 962 <para> 963 <command>userfiles</command>: The path to the 964 directory where user files are located. This 965 directory must be accessible from all job 966 agents, i.e., by nfs or other file system 967 sharing method. 968 </para> 969 </listitem> 970 <listitem> 971 <para> 972 <command>plugins.dir</command>: The path to the 973 directory where plug-ins are located. This 974 directory must be accessible from all job 975 agents, i.e., by nfs or other file system 976 sharing method. 977 </para> 978 </listitem> 979 </itemizedlist> 980 See the <xref linkend="appendix.base.config"/> for 981 more information about the settings in 982 the <filename>base.config</filename> file. 983 </para> 984 </listitem> 985 </varlistentry> 986 <varlistentry id="installation_upgrade.jobagent.client.properties"> 987 <term>Edit 988 the <filename>jobagent.properties</filename> file</term> 989 <listitem> 990 <para> 991 The <filename><base-dir>/www/WEB-INF/classes/jobagent.properties</filename> 992 file contains settings for the job agent. The most 993 important ones to specify value for are 994 <itemizedlist> 995 <listitem> 996 <para> 997 <command>agent.password</command>: The password 998 you set for the job agent user account in item 999 <xref 1000 linkend="installation_upgrade.jobagent.user_account"/> 1001 above. 1002 </para> 1003 </listitem> 1004 <listitem> 1005 <para> 1006 <command>agent.id</command>: An ID that must be 1007 unique for each job agent accessing the BASE application. 1008 </para> 1009 </listitem> 1010 <listitem> 1011 <para> 1012 <command>agent.remotecontrol</command>: The 1013 name or ip address of the web server if you want it 1014 to be able to display info about running 1015 jobs. The job agent will only allow connections 1016 from computers specified in this setting. 1017 </para> 1018 </listitem> 1019 </itemizedlist> 1020 </para> 1021 <para> 1022 The <filename>jobagent.properties</filename> file 1023 contains many more configuration options. See 1024 the <xref linkend="appendix.jobagent.properties"/> for 1025 more information. 1026 </para> 1027 </listitem> 1028 </varlistentry> 1029 <varlistentry> 1030 <term>Register the job agent</term> 1031 <listitem> 1032 <para> 1033 From the <filename>bin</filename> directory, register 1034 the job agent with 1035 <programlisting>./jobagent.sh register</programlisting> 1036 </para> 1037 </listitem> 1038 </varlistentry> 1039 <varlistentry> 1040 <term>Start the job agent</term> 1041 <listitem> 1042 <para> 1043 From the <filename>bin</filename> directory, start the 1044 job agent with 1045 <programlisting>./jobagent.sh start &</programlisting> 1046 </para> 1047 <para> 1048 See the <xref linkend="appendix.jobagent.sh"/> 1049 for more information about what you can do 1050 with the job agent command line interface. 1051 </para> 1052 </listitem> 1053 </varlistentry> 1054 </variablelist> 1055 </para> 1056 </sect2> 1057 1058 1059 <sect2 id="installation_upgrade.jobagents.configuration"> 1060 <title>Configuring the job agent</title> 1061 1062 <para> 1063 A job agent will not execute a plug-in unless the administrator 1064 has configured the job agent to do so. There are two things that 1065 must be done: 1066 </para> 1067 1068 <itemizedlist> 1069 <listitem> 1070 <para> 1071 Share the job agent to the users, groups and project that should be 1072 able to use it. If the job agent is not shared, only the owner of 1073 job agent is allowed to use it. Use the regular <guilabel>Share</guilabel> 1074 functionality to specify which users/groups/projects 1075 should be able to use the job agent. You must give 1076 them at least <command>USE</command> permission. 1077 To give all users permission to the job agent share it 1078 to the <command>EVERYONE</command> group. 1079 </para> 1080 </listitem> 1081 1082 <listitem> 1083 <para> 1084 Selecting plug-ins that the job agent should handle. This can be 1085 done either from the plug-in pages or from the job agent pages. To register 1086 a plug-in with one or more job agents from the plug-in pages, go 1087 to the edit view of the plug-in and select the <guilabel>Job 1088 agents</guilabel> tab. To do the same from the job agent pages, 1089 go to the edit view of the job agent and select 1090 the <guilabel>Plugins</guilabel> tab. The registration dialogs 1091 are very similar but only the plug-in side of registration is 1092 described here. The major difference is that it is not possible 1093 to enable/disable the internal job queue for plug-in when using 1094 the jobagent side of the registration. 1095 </para> 1096 </listitem> 1097 </itemizedlist> 1098 1099 <figure id="plugins.figures.jobagents"> 1100 <title>Select job agents for a plug-in</title> 1101 <screenshot> 1102 <mediaobject> 1103 <imageobject><imagedata 1104 scalefit="1" width="100%" 1105 fileref="figures/plugin_jobagents.png" format="PNG" 1106 /></imageobject> 1107 </mediaobject> 1108 </screenshot> 1109 </figure> 1110 1111 <helptext external_id="plugindefinition.jobagents" 1112 title="Job agents"> 1113 1114 <para> 1115 Use this tab to specify which job agents the plug-in is 1116 installed and allowed to be executed on. 1117 </para> 1118 1119 <variablelist> 1120 <varlistentry> 1121 <term><guilabel>Run this plugin on</guilabel></term> 1122 <listitem> 1123 <para> 1124 You may select if the internal job queue should execute the 1125 plug-in or not. 1126 </para> 1127 </listitem> 1128 </varlistentry> 1129 <varlistentry> 1130 <term><guilabel>Job agents</guilabel></term> 1131 <listitem> 1132 <para> 1133 A list with the job agents where the plug-in is installed and 1134 allowed to be executed. Select a plug-in in this list to display 1135 more configuration options for the plug-in. 1136 </para> 1137 </listitem> 1138 </varlistentry> 1139 <varlistentry> 1140 <term><guilabel>Add job agents</guilabel></term> 1141 <listitem> 1142 <para> 1143 Use this button to open a pop-up window for selecting 1144 job agents. 1145 </para> 1146 </listitem> 1147 </varlistentry> 1148 <varlistentry> 1149 <term><guilabel>Remove</guilabel></term> 1150 <listitem> 1151 <para> 1152 Remove the selected plug-in from the list. 1153 </para> 1154 </listitem> 1155 </varlistentry> 1156 </variablelist> 1157 1158 <para> 1159 The following properties are only displayed when a 1160 job agent has been selected in the list. Each job agent may have it's 1161 own settings of these properties. If you leave the values unspecified 1162 the job agent will use the default values specified on the 1163 <guilabel>Plugin</guilabel> tab. 1164 </para> 1165 1166 <variablelist> 1167 <varlistentry> 1168 <term><guilabel>Max memory</guilabel></term> 1169 <listitem> 1170 <para> 1171 The maximum amount of memory the plug-in is allowed to use. 1172 Add around 40MB for the Java run-time environment and BASE. 1173 If not specified Java will choose it's default value which is 64MB. 1174 </para> 1175 </listitem> 1176 </varlistentry> 1177 <varlistentry> 1178 <term><guilabel>Trusted</guilabel></term> 1179 <listitem> 1180 <para> 1181 If the plug-in should be executed in a protected or 1182 unprotected environment. Currently, BASE only supports 1183 running plug-ins in an unprotected environment. 1184 </para> 1185 </listitem> 1186 </varlistentry> 1187 <varlistentry> 1188 <term><guilabel>Priority boost</guilabel></term> 1189 <listitem> 1190 <para> 1191 Used to give a plug-in higher priority in the job queue. 1192 Values between 0 and 10 are allowed. A higher value will 1193 give the plug-in higher priority. The priority boost is useful 1194 if we, for example, want to use one server mainly for importing 1195 data. By giving all import plugins a priority boost they will 1196 be executed before all other jobs, which will have to wait 1197 until there are no more waiting imports. 1198 </para> 1199 </listitem> 1200 </varlistentry> 1201 </variablelist> 1202 1203 <seeother> 1204 <other external_id="plugindefinition.edit">Plug-in properties</other> 1205 <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other> 1206 </seeother> 1207 </helptext> 1208 </sect2> 1209 1210 </sect1> <!-- job agent setup --> 1123 1211 1124 1212 <sect1 id="installation_upgrade.serverconfigurations"> … … 1218 1306 title="Instructions to get an account"> 1219 1307 <para> 1220 A description what a none-registereduser should do to get1221 an account on the particular BASE -server. This text is linked1308 A description what a user should do to get 1309 an account on the particular BASE server. This text is linked 1222 1310 to the <guilabel>Get an account!</guilabel> link on the login 1223 1311 page. We recommend that the Latin text is replaced with some useful … … 1235 1323 title="Instructions when password is forgotten."> 1236 1324 <para> 1237 A description what a nuser should do if the password is forgotten.1325 A description what a user should do if the password is forgotten. 1238 1326 This text is linked 1239 1327 to the <guilabel>Forgot your password?</guilabel> link on the login … … 1342 1430 Mark this check-box to try to prevent new users from logging in. To 1343 1431 avoid problems that can be caused by blocking the server admin out, 1344 the login is not completely ,disabled. Any user can still login but1432 the login is not completely disabled. Any user can still login but 1345 1433 only after by-passing several warnings. 1346 1434 </para> … … 1370 1458 </sect1> 1371 1459 1372 <sect1 id="installation_upgrade.migration">1373 <title>Migration instructions</title>1374 1375 <para>1376 The support for migration from BASE 1.2 to BASE 2 ended in1377 BASE 2.6, but the migration program was included in the1378 distribution until BASE 2.15. As of BASE 2.16 the migration1379 program is no longer included in the distribution. Our1380 recommendation for migration is to try BASE 2.15 first and1381 then upgrade to the newest BASE version. Full instructions for1382 the migratation program are included in the BASE 2.15 distribution.1383 </para>1384 1385 </sect1> <!-- Migration instructions -->1386 1387 1460 </chapter> -
trunk/doc/src/docbook/admindoc/plugins.xml
r5735 r5737 28 28 29 29 <chapter id="plugins"> 30 <?dbhtml dir="plugin _installation"?>31 <title>Plug-ins </title>30 <?dbhtml dir="plugins"?> 31 <title>Plug-ins and extensions</title> 32 32 33 33 <para> 34 BASE can get extended functionality by the use of plug-ins . In fact, most35 of the hard work, such as data import/export and analysis is done with plug-ins.34 BASE can get extended functionality by the use of plug-ins and extensions. 35 Much of the hard work, such as data import/export and analysis is done with plug-ins. 36 36 BASE ships with a number of standard plug-ins, the core plug-ins, which gives 37 basic import/export and analysis functionality. See <xref linkend="resources" /> 38 for more information about the core plug-ins and 3rd-party plug-ins. 37 basic import/export and analysis functionality. Typically a plug-in interacts with 38 a user by asking for parameters that it need to be able to do it's work. For 39 example, which file to import data from, and maybe some regular expressions that 40 should be used when parsing the file and then some information about how the data 41 in the file should be mapped to items and properties in BASE. When the plug-in has 42 all parameters it needs a <guilabel>Job</guilabel> is added to a job queue. A job 43 agent or similar is then responsible for sceduling and executing (possibly on a 44 different machine) the plug-in code. 39 45 </para> 46 47 <para> 48 Extensions are historically more targeted at additions to the user interface, 49 such as additional menu items, toolbar buttons, etc. As a result, extensions have 50 a lot more flexibility when it comes to the visual appearance. On the other 51 hand they are executed immediately as a result of user interaction and are expected 52 to perform quickly and without delay. 53 </para> 54 55 <para> 56 Starting with BASE 3 the extension mechanism has been somewhat extended to cover 57 other things that are not directly related to the web interface. For example, 58 extensions can be used to add support for other protocols than HTTP when using 59 external files. The main difference between a plug-in and extension is that an 60 extension must execute immediately it's service is requested, but a plug-in can 61 be scheduled for later execution. 62 </para> 40 63 41 64 42 65 <sect1 id="plugins.installation"> 43 <title>Installing plug-ins</title> 66 <title>Managing plug-ins and extensions</title> 67 68 <note> 69 <title>Changes since BASE 2</title> 70 <para> 71 The plug-in and extensions installation has changed since BASE 2. The major 72 changes are: 73 </para> 74 <itemizedlist> 75 <listitem> 76 <para> 77 The main JAR file must be installed in the directory specified by the 78 <constant>plugins.dir</constant> setting in <filename>base.config</filename>. 79 Subdirectories are not allowed. This applies to both plug-ins and 80 extensions. The <filename>WEB-INF/extensions</filename> is not used for 81 extensions anymore. 82 </para> 83 </listitem> 84 <listitem> 85 <para> 86 A package must be installed as a whole. It is no longer possible to only 87 select some of the plug-ins to install. If neccessary, the administrator can 88 always disable plug-ins that is not wanted. 89 </para> 90 </listitem> 91 </itemizedlist> 92 </note> 93 44 94 <para> 45 The first step is to install the plug-in on the web server. To make 46 these instructions easier to read we assume the plug-in comes as 47 a single JAR file and that it does not depend on any other JAR files. 95 The first step is to install the actual code on the web server. The recommendation 96 to developers is to ship the entire package as a single JAR file. If everything is 97 JAVA based this should not be a problem. A common exception is that configuration 98 files should be installed (and configured) separately. Always read the installation 99 instructions for the package you are installing. The rest of the instructions in 100 this section assume that the plug-in/extensions comes as a single JAR file. 48 101 </para> 49 102 103 <note> 104 <title>Make sure the extensions folder is writable by Tomcat</title> 105 <para> 106 The package you are installing may include resources such as HTML 107 files, JSP scripts, images, etc. that needs to be extracted to the 108 web application path before they can be used. This extraction is 109 automatically done by the installation wizard, but you have to make 110 sure that the user account Tomcat is running as has permission 111 to create (and delete) new files in the 112 <filename class="directory"><base-dir>/www/extensions</filename> 113 directory. 114 </para> 115 </note> 116 50 117 <para> 51 We recommend that you install the plug-in JAR file outside the web 52 server's Classpath. Do not put the plug-in in the 53 <filename><base-dir>/www/WEB-INF/lib</filename> 54 directory or any other directory where the web server keeps it's classes. 55 This makes BASE use it's own class loader that support unloading of classes 56 as well. This means that you can install new plug-ins and update 57 existing ones without restarting the web server. 118 So, the first step should be simple. Just put the JAR file in the 119 dedicated plug-ins directory. This is the directory that is specified 120 in the <constant>plugins.dir</constant> setting in <filename>base.config</filename>. 58 121 </para> 59 122 60 <para> 61 We recommend that you create a separate directory for plug-ins and 62 install all of them there. You may use a sub-directory for each plug-in 63 if you like, for example: 64 <filename><base-dir>/plugins/<name-of-plugin></filename> 65 </para> 66 67 <note> 68 <title>Plug-ins that use other JAR files</title> 69 <para> 70 Some plug-ins may depend on other JAR files. Normally, 71 these JAR files should be put in the same directory as the 72 plug-in JAR file. This may, however, vary from plug-in to plug-in 73 so always check the plug-in documentation first. 74 </para> 75 </note> 76 77 <para> 78 When the plug-in is installed on the server you must register it with BASE. To register 79 the plug-in with BASE go to 80 <menuchoice> 81 <guimenu>Administrate</guimenu> 82 <guisubmenu>Plugins</guisubmenu> 83 <guimenuitem>Definitions</guimenuitem> 84 </menuchoice> 85 and click on the &gbNew; button. In the pop-up window that appears 86 you should first decide if you want to do a manual or an (almost) automatic 87 installation. An automatic installation scans the server disks for plug-ins 88 and lets you select which ones to install or update from a list in the 89 web interface. In a manual installation you are required to enter the 90 path and class name of the plug-in yourself. 91 </para> 92 93 <sect2 id="plugins.select.installtype"> 94 <title>Select installation method</title> 95 <para> 96 This window appears, like described above, when automatic installation/registration 97 of plug-ins is available. 98 <figure id="plugins.figures.selectinstall"> 99 <title>Select installation type</title> 100 <screenshot> 101 <mediaobject> 102 <imageobject> 103 <imagedata fileref="figures/select_install.png" format="PNG" 104 scalefit="1" width="70%" /> 105 </imageobject> 106 </mediaobject> 107 </screenshot> 108 </figure> 109 </para> 110 <helptext external_id="plugindefinition.installationtype" 111 title="Select installation type"> 112 <variablelist> 113 <varlistentry> 114 <term><guilabel>Install</guilabel> 115 </term> 116 <listitem> 117 <para> 118 How to register the plug-in(s) with BASE. 119 <variablelist> 120 <varlistentry> 121 <term><emphasis>Automatically</emphasis></term> 122 <listitem> 123 <para> 124 BASE will scan the selected directories for JAR files containing 125 plug-ins. If it finds any, you will have the option 126 to select which ones to install from a list. 127 <nohelp>The next step will be <xref linkend="plugins.autoinstall" /></nohelp> 128 </para> 129 </listitem> 130 </varlistentry> 131 <varlistentry> 132 <term><emphasis>Manually</emphasis></term> 133 <listitem> 134 <para> 135 Class name and JAR path have to be entered manually by the 136 administrator. Only one plug-in can be registered at 137 a time in this way. Next step will be 138 <nohelp><xref linkend="plugins.install.properties" /></nohelp> 139 </para> 140 </listitem> 141 </varlistentry> 142 </variablelist> 143 </para> 144 </listitem> 145 </varlistentry> 146 <varlistentry> 147 <term><guilabel>Directories</guilabel> (only when <emphasis>Automatically</emphasis> is selected)</term> 148 <listitem> 149 <para> 150 Select the checkboxes were BASE should look for new plug-ins. 151 For security reasons the only options are the dedicated plug-ins 152 directory that is configured in the <filename>base.config</filename> 153 directory and the extensions that directory that is normally 154 used for extensions to the web client. 155 </para> 156 </listitem> 157 </varlistentry> 158 </variablelist> 123 <sect2 id="plugins.installation.wizard"> 124 <title>Automatic installation wizard</title> 125 126 <para> 127 When the plug-in/extensions package is installed on the server you must register 128 it with BASE. Go to 129 <menuchoice> 130 <guimenu>Administrate</guimenu> 131 <guisubmenu>Plug-ins & extensions</guisubmenu> 132 <guimenuitem>Overview</guimenuitem> 133 </menuchoice>. 134 </para> 135 136 <figure id="extensions.figures.installedextensions"> 137 <title>Installed extensions & plug-ins</title> 138 <screenshot> 139 <mediaobject> 140 <imageobject> 141 <imagedata fileref="figures/installed_extensions.png" format="PNG" /> 142 </imageobject> 143 </mediaobject> 144 </screenshot> 145 </figure> 146 147 <helptext 148 external_id="extensions.details.main" 149 title="Installed extensions"> 159 150 160 <note> 161 The automatic installation doesn't allow you to set all properties 162 that can be set in a manual installation. If you for example, need 163 to share the plug-ins to other users or assign them to job agents 164 this must be done after the auto-installation has been completed. 165 </note> 151 <para> 152 The left-hand side of the screen shows a tree with all installed 153 plug-ins and extensions, sorted by extension point and by file. Use 154 the + and - icons to expand and collapse parts of the tree. Click on an item 155 in the tree to display detailed information about it 156 on the right-hand side of the screen. Click on the 157 <guibutton>Install/uninstall</guibutton> button to start 158 the installation wizard (which can also be used for uninstallation). 159 </para> 166 160 167 161 <seeother> 168 <other external_id="plugindefinition.edit">Manual installation</other> 169 <other external_id="plugindefintion.autoinstaller">Automatic installation</other> 162 <other external_id="extensions.install-wizard">Install/uninstall wizard</other> 170 163 </seeother> 164 </helptext> 165 166 <figure id="plugins.figures.installwizard"> 167 <title>Extensions and plug-ins installation wizard</title> 168 <screenshot> 169 <mediaobject> 170 <imageobject> 171 <imagedata fileref="figures/plugins_install_wizard.png" format="PNG" 172 scalefit="1" width="100%" /> 173 </imageobject> 174 </mediaobject> 175 </screenshot> 176 </figure> 171 177 178 179 <helptext 180 external_id="extensions.install-wizard" 181 title="Extensions and plug-ins installation wizard"> 182 183 <para> 184 This wizard can be used for both installing, re-installing and un-installing 185 plug-in and extension packages. The first dialog shows a list with all 186 currently installed packages as well as any new packages that has been 187 found on the server. The list includes the name of the JAR file, 188 the current status and some information provided by the author of the package. 189 There are also two columns <guilabel>Install</guilabel> and 190 <guilabel>Uninstall</guilabel> which may or may not have a checkbox in them. 191 For new packages there should be a checkbox in the install column that is already 192 checked. Already installed packages can either be re-installed or uninstalled by 193 checking the appropriate checkbox. If there is a problem with a package an error 194 message is displayed and neither installation or uninstallation is possible. 195 </para> 196 197 <para> 198 Click on <guibutton>Next</guibutton> to perform the selected actions. The next 199 dialog should display a summary with the installation results. 200 Hopefully everything was succeessful. Close the dialog and refresh the overview tree 201 to see the changes. 202 </para> 203 204 <note> 205 <para> 206 Uninstalling a package doesn't remove the plug-in definitions from BASE nor 207 does it remove the JAR file from the server. This is because there may be jobs 208 and other items referencing the plug-ins. The plug-ins are only marked as disabled 209 and it is up to the administrator to actually delete them if it is possible. 210 </para> 211 </note> 172 212 </helptext> 213 214 <figure id="plugins.figures.installresults"> 215 <title>Extensions and plug-ins installation results</title> 216 <screenshot> 217 <mediaobject> 218 <imageobject> 219 <imagedata fileref="figures/plugins_install_wizard_2.png" format="PNG" 220 scalefit="1" width="100%" /> 221 </imageobject> 222 </mediaobject> 223 </screenshot> 224 </figure> 173 225 </sect2> 174 226 175 <sect2 id="plugins.install.properties"> 176 <title>Plug-in properties</title> 177 178 <para> 179 This section describes the manual installation of a plug-in. 180 </para> 181 182 <figure id="plugins.figures.install"> 183 <title>Installing a plug-in</title> 184 <screenshot> 185 <mediaobject> 186 <imageobject><imagedata 187 fileref="figures/install_plugin.png" format="PNG" 188 /></imageobject> 189 </mediaobject> 190 </screenshot> 191 </figure> 227 <sect2 id="plugins.installation.manual"> 228 <title>Manual plug-in registration</title> 229 230 <para> 231 Manual installation of a plug-in should almost never be neccessary. 232 One exception is that developers may want to do this as a first step 233 before everything has been properly packaged. Another exception is plug-ins 234 developed for BASE 2 that doesn't support the automatic installation procedure. 235 If the old plug-in still works API-wise in BASE 3, manual installation 236 can be used to install it. Repackaging such a plug-in is however not difficult 237 so we recommend that the plug-in author is asked to provide an updated 238 version. 239 </para> 240 241 <para> 242 To perform a manual installation, go to <menuchoice> 243 <guimenu>Administrate</guimenu> 244 <guisubmenu>Plug-ins & extensions</guisubmenu> 245 <guimenuitem>Plug-in definitions</guimenuitem> 246 </menuchoice> and click on the <guibutton>New</guibutton> button. 247 </para> 248 249 <figure id="plugins.figures.installmanual"> 250 <title>Manually installing a plug-in</title> 251 <screenshot> 252 <mediaobject> 253 <imageobject><imagedata 254 fileref="figures/plugins_install_manual.png" format="PNG" 255 /></imageobject> 256 </mediaobject> 257 </screenshot> 258 </figure> 192 259 193 260 <helptext external_id="plugindefinition.edit" … … 208 275 <listitem> 209 276 <para> 210 The Java class name of the plug-in. 211 </para> 212 </listitem> 213 </varlistentry> 214 <varlistentry> 215 <term><guilabel>Path</guilabel></term> 216 <listitem> 217 <para> 218 The path to the JAR file on the web server. If left empty 277 The full Java class name of the plug-in. 278 </para> 279 </listitem> 280 </varlistentry> 281 <varlistentry> 282 <term><guilabel>JAR file</guilabel></term> 283 <listitem> 284 <para> 285 The name of the JAR file on the web server. The JAR file must 286 be installed in the directory specified by the <constant>plugins.dir</constant> 287 setting in <filename>base.config</filename> If left empty 219 288 the plug-in must be on the web server's class path (not 220 289 recommended). … … 230 299 the internal job queue is used this setting has no effect and the 231 300 plug-in may use as much memory as it likes. 232 <nohelp>See <xref linkend="plugins.jobagents" /> later 233 in this chapter.</nohelp> 301 <nohelp>See <xref linkend="installation_upgrade.jobagents.configuration" /> for more information.</nohelp> 234 302 </para> 235 303 </listitem> … … 313 381 </sect2> 314 382 315 <sect2 id="plugins.autoinstall"> 316 <title>Automatic installation of plug-ins</title> 317 318 <para> 319 This section describes the automatic installation of plug-ins 320 using a wizard. 321 </para> 322 323 <figure id="plugins.figures.autoinstall"> 324 <title>Auto install plug-ins</title> 325 326 <screenshot> 327 <mediaobject> 328 <imageobject> 329 <imagedata 330 fileref="figures/plugin_autoinstall.png" format="PNG" 331 /> 332 </imageobject> 333 </mediaobject> 334 </screenshot> 335 </figure> 336 337 <para> 338 This window lists all the plug-ins that were found in JAR files, 339 after scanning the selected directories from the previous step. 340 There are a few options to set for each plug-in before they can be registered. 341 </para> 342 343 <helptext external_id="plugindefintion.autoinstaller" title="Auto install plugins"> 344 <para> 345 The page has, for each plug-in, a row that is divided into four columns with 346 information or settings. These are explained more in details below. There is an icon 347 in the <guilabel>Install</guilabel> column that displays summarized information about the plug-in when 348 the mouse pointer is held over it. Most of this information is from the plug-in's 349 <classname docapi="net.sf.basedb.core.plugins">About</classname> 350 property but some, like 'Works with', 'Class' and 'Jar' is from the installation 351 file included in the JAR file. A plug-in can also be distributed with one or many 352 configurations that can be selected for import together with plug-in 353 registration. The configurations are by default hidden but can easily be viewed by 354 expanding the configuration tree for a plug-in. 355 <variablelist> 356 <varlistentry> 357 <term> 358 <guilabel>Plugins</guilabel> 359 </term> 360 <listitem> 361 <para> 362 The plug-in's name, from the plug-in class. Names of the 363 configurations that comes with a plug-in are also displayed in 364 this column but in a tree under the plug-in they belong to. 365 </para> 366 </listitem> 367 </varlistentry> 368 <varlistentry> 369 <term> 370 <guilabel>Install</guilabel> 371 </term> 372 <listitem> 373 <para> 374 A selection list for each plug-in found when scanning the plug-in directory. 375 There are at least two option for each plug-in in this drop-down list. The 376 default option 377 <emphasis>no</emphasis> 378 will not register the plug-in to BASE while 379 <emphasis>yes</emphasis> 380 will register the plug-in when proceeding. If the plug-in 381 also have configurations the <emphasis>yes</emphasis> 382 option is replaced with <emphasis>plugin only</emphasis> 383 and <emphasis>plugin + configurations</emphasis>. 384 If the last option is selected all configurations for the 385 specific plug-in will be imported. 386 </para> 387 <para> 388 Each listed configuration can individually be defined if it 389 should be imported or not. This is done by selecting 390 <emphasis>yes</emphasis> or <emphasis>no</emphasis>. 391 </para> 392 <note> 393 <para> 394 Plug-ins that already are registered in BASE will be disabled in the list, 395 unless the plug-in comes from a JAR file in a different path than the 396 one registered in BASE, or if the version does not consist 397 with the one registered in BASE. In these cases the 398 drop-down list is enabled for selection but the plug-in 399 name is marked with an exclamation mark and the plug-in will be 400 re-registered and updated if any of the two install options are 401 selected. 402 </para> 403 </note> 404 <note> 405 <para> 406 If a configuration in the list has an identical name as a configuration in BASE 407 and the configurations are for the same plug-in, there will be a warning in the 408 list beside the install-select box. The already existing configuration will not 409 be overwritten if the new plug-in configuration is set to be imported, 410 but there will be two configurations with the same name and for the same plug-in. 411 </para> 412 </note> 413 </listitem> 414 </varlistentry> 415 <varlistentry> 416 <term> 417 <guilabel>Trusted</guilabel> 418 </term> 419 <listitem> 420 <para> 421 If the plug-in is trusted enough to be executed in an 422 unprotected environment. See 423 <nohelp> 424 <xref linkend="plugins.install.properties" /> 425 </nohelp> 426 </para> 427 </listitem> 428 </varlistentry> 429 <varlistentry> 430 <term> 431 <guilabel>Immediate execution</guilabel> 432 </term> 433 <listitem> 434 <para> 435 If the plug-in is allowed to bypass the job queue and be 436 executed immediately. See 437 <nohelp> 438 <xref linkend="plugins.install.properties" /> 439 </nohelp> 440 </para> 441 </listitem> 442 </varlistentry> 443 </variablelist> 444 </para> 445 <para> 446 Click on &gbSave; to finish the registration 447 or on &gbCancel; to abort. 448 </para> 449 <seeother> 450 <other external_id="plugindefinition.edit">Edit plugins</other> 451 </seeother> 452 </helptext> 453 </sect2> 454 383 455 384 <sect2 id="plugins.installation.base1"> 456 385 <title>BASE version 1 plug-ins</title> … … 476 405 <listitem> 477 406 <para> 478 Follow the instructions in 479 <xref linkend="plugins.configuration.base1" /> to configure 480 Base1PluginExecuter for use of the BASE1 plug-in. 407 Upload the <filename>*.base</filename> file for the BASE 408 version 1 plug-in. If you cannot find the file, you can let 409 your BASE version 1 server create one for you. In your BASE 410 version 1 installation go to 411 <menuchoice> 412 <guimenu>Analyze data</guimenu> 413 <guimenuitem>Plug-ins</guimenuitem> 414 </menuchoice> 415 and use the <guilabel>Export</guilabel> function. This will 416 create a configuration file for your BASE version 1 plug-in 417 that you can upload to your new BASE server. 481 418 </para> 482 419 </listitem> 420 421 <listitem> 422 <para> 423 Create a new plug-in configuration using, for example, 424 the <guibutton>New configuration</guibutton> button in 425 single-item view for 426 the <emphasis>Base1PluginExecuter</emphasis> plug-in. 427 </para> 428 </listitem> 429 430 <listitem> 431 <para> 432 Start the configuration wizard and select parameters: 433 </para> 434 <itemizedlist> 435 <listitem> 436 <para> 437 <guilabel>File</guilabel>: The <filename>*.base</filename> file 438 describing the BASE version 1 plug-in. This can be left empty for 439 manual configuration, but in reality it is only usable for tweaking 440 an existing configuration that has been created from a file 441 in the first place. 442 </para> 443 </listitem> 444 <listitem> 445 <para> 446 <guilabel>Plugin executables path</guilabel>: The path to the executable 447 program that was installed in the first step. 448 449 </para> 450 </listitem> 451 <listitem> 452 <para> 453 <guilabel>Source intensities</guilabel>: Select if the plug-in can work 454 with regular or logged data (or both). 455 </para> 456 </listitem> 457 <listitem> 458 <para> 459 <guilabel>Resulting intensities</guilabel>: Select if the plug-in generates 460 regular or logged data. 461 </para> 462 </listitem> 463 </itemizedlist> 464 465 <para> 466 Click <guibutton>Next</guibutton> to finish the wizard. 467 </para> 468 469 </listitem> 470 471 <listitem> 472 <para> 473 To check that the new plug-in works correctly, you need to 474 have an experiment with some data. Go to the single-item 475 view for a bioassay set and click on the <guibutton>Run 476 analysis</guibutton> button. Select 477 the <emphasis>Base1PluginExecuter</emphasis> plug-in. The 478 list of configurations should include the newly installed 479 plug-in. Select it and click on &gbNext;. 480 </para> 481 </listitem> 482 483 <listitem> 484 <para> 485 This will enter regular plug-in execution wizard and you 486 will have to enter parameters needed by the plug-in. 487 </para> 488 </listitem> 489 490 </orderedlist> 491 492 </sect2> 493 494 495 <sect2 id="plugins.installation.xjspcompiler"> 496 <title>Installing the X-JSP compiler</title> 497 <para> 498 Some extensions may want to use custom JSP files that also uses 499 classes that are stored in the extension's JAR file. The problem 500 with this is that Tomcat usually doesn't know to look for classes 501 in the <filename>plugins.dir</filename> directory. To solve 502 this problem BASE ships with a X-JSP compiler that can do this. 503 This compiler has been mapped to files with a <code>.xjsp</code> 504 extension, which are just regular JSP files with a different extension. 505 </para> 506 507 <para> 508 The X-JSP compiler must be installed into Tomcat's internal 509 library folder (<filename>$CATALINA_HOME/lib</filename>) 510 since this is the only place where Tomcat look for compilers. The installation 511 is easy. Simply copy <filename><base-dir>/bin/jar/base-xjsp-compiler-3.x.jar</filename> 512 to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat. 513 </para> 514 515 <note> 516 <title>X-JSP is experimental</title> 517 <para> 518 This is an experimental feature that depends on internal functionality 519 in Tomcat. It may or may not work with future versions of Tomcat. 520 The compiler will most likely not work with other servlet 521 containers. 522 </para> 523 </note> 524 </sect2> 525 526 <sect2 id="plugins.installation.disable"> 527 <title>Disable/enable plug-ins and extensions</title> 528 529 <para> 530 It is possible to disable specific extensions, extension point 531 and or a plug-in without uninstalling the XML or JAR file. 532 When you click on an item in the tree on the left-hand side of the 533 screen a lot of detailed information about it will show up on the right-hand side. 534 The right-hand side usually has a <guibutton>Disable</guibutton> 535 or <guibutton>Disable all</guibutton> button in the toolbar. Click on that button 536 to disable the plug-in, extension or all extensions 537 for an extension point. The button will change to <guibutton>Enable</guibutton> 538 or <guibutton>Enable all</guibutton> which lets you enable the extensions and 539 plug-ins again. 540 </para> 541 </sect2> 542 543 <sect2 id="plugins.permissions"> 544 <title>Plug-in permissions</title> 545 546 <helptext external_id="plugindefinition.edit.permissions" 547 title="Edit plug-in permissions"> 548 549 550 <para> 551 When a plug-in is executed the default is to give it the same 552 permissions as the user that started it. This can be seen as a 553 security risk if the plug-in is not trusted, or if someone manages 554 to replace the plug-in code with their own code. A malicious plug-in can, 555 for example, delete the entire database if invoked by the root user. 556 </para> 483 557 484 </orderedlist> 485 486 558 <para> 559 To limit this problem it is possible to tune the permissions for 560 a plug-in so that it only has permission to do things that it 561 is supposed to do. For example, a plug-in that import reporters 562 may only need permission to update and create new reporters and 563 nothing else. 564 </para> 565 566 <nohelp> 567 <para> 568 To enable the permission system for a plug-in go the 569 edit view of the plug-in and select the <guilabel>Permissions</guilabel> 570 tab. 571 </para> 572 573 <figure id="plugins.figures.permissions"> 574 <title>Setting permissions on a plug-in</title> 575 <screenshot> 576 <mediaobject> 577 <imageobject><imagedata 578 fileref="figures/plugin_permissions.png" format="PNG" 579 /></imageobject> 580 </mediaobject> 581 </screenshot> 582 </figure> 583 </nohelp> 584 585 <variablelist> 586 <varlistentry> 587 <term><guilabel>Use permissions</guilabel></term> 588 <listitem> 589 <para> 590 Select if the plug-in should use the permission system 591 or not. If <guilabel>no</guilabel> is selected, the rest 592 of the form is disabled. 593 </para> 594 </listitem> 595 </varlistentry> 596 <varlistentry> 597 <term><guilabel>Item types</guilabel></term> 598 <listitem> 599 <para> 600 The list contains all item types found in BASE that 601 can have permissions set on them. The list is more or less the 602 same as the permission list for roles. 603 <nohelp> 604 See <xref linkend="user_administration.roles.edit.permissions" />. 605 </nohelp> 606 </para> 607 </listitem> 608 </varlistentry> 609 <varlistentry> 610 <term><guilabel>Always grant</guilabel></term> 611 <listitem> 612 <para> 613 The selected permissions will always be granted 614 to the plug-in no matter if the logged in user had the 615 permission to begin with or not. This makes it possible to 616 develop a plug-in that allows users to do things that they 617 are normally not allowed to do. The reporter importer is 618 for example allowed to create and use reporter types. 619 </para> 620 </listitem> 621 </varlistentry> 622 <varlistentry> 623 <term><guilabel>Always deny</guilabel></term> 624 <listitem> 625 <para> 626 The selected permissions will always be denied 627 to the plug-in no matter if the logged in user had the 628 permission to begin with or not. The default is to always 629 deny all permissions. Permissions that are not always 630 denied and not always granted uses permissions from 631 the logged in user. 632 </para> 633 </listitem> 634 </varlistentry> 635 <varlistentry> 636 <term><guilabel>Requested by plug-in</guilabel></term> 637 <listitem> 638 <para> 639 To make it easier for the server administrator 640 to assign permissions, the plug-in developer can 641 let the plug-in include a list of permissions that 642 are needed. Plug-in developers are advised to 643 only include the minimal set of permissions that are 644 required for the plug-in to function. Click on the 645 <guibutton>Use requested permissions</guibutton> 646 button to give the plug-in the requested permissions. 647 </para> 648 </listitem> 649 </varlistentry> 650 </variablelist> 651 652 <seeother> 653 <other external_id="plugindefinition.edit">Plug-in properties</other> 654 <other external_id="plugindefinition.jobagents">Job agents</other> 655 <other external_id="role.edit.permissions">Role permissions</other> 656 </seeother> 657 </helptext> 658 487 659 </sect2> 488 660 489 661 </sect1> 490 662 491 <sect1 id="plugins.permissions">492 <title>Plug-in permissions</title>493 494 <helptext external_id="plugindefinition.edit.permissions"495 title="Edit plug-in permissions">496 497 498 <para>499 When a plug-in is executed the default is to give it the same500 permissions as the user that started it. This can be seen as a501 security risk if the plug-in is not trusted, or if someone manages502 to replace the plug-in code with their own code. A malicious plugin can,503 for example, delete the entire database if invoked by the root user.504 </para>505 506 <para>507 To limit this problem it is possible to tune the permissions for508 a plug-in so that it only has permission to do things that it509 is supposed to do. For example, a plug-in that import reporters510 may only need permission to update and create new reporters and511 nothing else.512 </para>513 514 <nohelp>515 <para>516 To enable the permission system for a plug-in go the517 edit view of the plug-in and select the <guilabel>Permissions</guilabel>518 tab.519 </para>520 521 <figure id="plugins.figures.permissions">522 <title>Setting permissions on a plug-in</title>523 <screenshot>524 <mediaobject>525 <imageobject><imagedata526 fileref="figures/plugin_permissions.png" format="PNG"527 /></imageobject>528 </mediaobject>529 </screenshot>530 </figure>531 </nohelp>532 533 <variablelist>534 <varlistentry>535 <term><guilabel>Use permissions</guilabel></term>536 <listitem>537 <para>538 Select if the plug-in should use the permission system539 or not. If <guilabel>no</guilabel> is selected, the rest540 of the form is disabled.541 </para>542 </listitem>543 </varlistentry>544 <varlistentry>545 <term><guilabel>Item types</guilabel></term>546 <listitem>547 <para>548 The list contains all item types found in BASE that549 can have permissions set on them. The list is more or less the550 same as the permission list for roles.551 <nohelp>552 See <xref linkend="user_administration.roles.edit.permissions" />.553 </nohelp>554 </para>555 </listitem>556 </varlistentry>557 <varlistentry>558 <term><guilabel>Always grant</guilabel></term>559 <listitem>560 <para>561 The selected permissions will always be granted562 to the plug-in no matter if the logged in user had the563 permission to begin with or not. This makes it possible to564 develop a plugin that allows users to do things that they565 are normally not allowed to do. The reporter importer is566 for example allowed to create and use reporter types.567 </para>568 </listitem>569 </varlistentry>570 <varlistentry>571 <term><guilabel>Always deny</guilabel></term>572 <listitem>573 <para>574 The selected permissions will always be denied575 to the plug-in no matter if the logged in user had the576 permission to begin with or not. The default is to always577 deny all permissions. Permissions that are not always578 denied and not always granted uses permissions from579 the logged in user.580 </para>581 </listitem>582 </varlistentry>583 <varlistentry>584 <term><guilabel>Requested by plug-in</guilabel></term>585 <listitem>586 <para>587 To make it easier for the server administrator588 to assign permissions, the plug-in developer can589 let the plug-in include a list of permissions that590 are needed. Plug-in developers are advised to591 only include the minimal set of permissions that are592 required for the plug-in to function. Click on the593 <guibutton>Use requested permissions</guibutton>594 button to give the plug-in the requested permissions.595 </para>596 </listitem>597 </varlistentry>598 </variablelist>599 600 <seeother>601 <other external_id="plugindefinition.edit">Plug-in properties</other>602 <other external_id="plugindefinition.jobagents">Job agents</other>603 <other external_id="role.edit.permissions">Role permissions</other>604 </seeother>605 </helptext>606 607 608 </sect1>609 610 611 <sect1 id="plugins.jobagents">612 <title>Job agents</title>613 <para>614 Job agents are used for executing plug-ins on external615 computers. Using job agents will free up resources on the BASE616 application server, and allow the server to concentrate on617 serving web pages. Job agents are optional and must be installed618 separately. See <xref linkend="installation_upgrade.jobagents"619 /> for more information about setting up job agents. This620 section assumes that at least one job agent is setup to serve621 your BASE installation.622 </para>623 624 <para>625 A job agent will not execute a plug-in unless the administrator626 has configured the job agent to do so. This can be done either627 from the plug-in pages or from the job agent pages. To register628 a plug-in with one or more job agents from the plug-in pages, go629 to the edit view of the plug-in and select the <guilabel>Job630 agents</guilabel> tab. To do the same from the job agent pages,631 go to the edit view of the job agent and select632 the <guilabel>Plugins</guilabel> tab. The registration dialogs633 are very similar but only the plug-in side of registration is634 described here, the job agent route is described in635 <xref linkend="installation_upgrade.jobagents" />.636 </para>637 638 <figure id="plugins.figures.jobagents">639 <title>Select job agents for a plug-in</title>640 <screenshot>641 <mediaobject>642 <imageobject><imagedata643 scalefit="1" width="100%"644 fileref="figures/plugin_jobagents.png" format="PNG"645 /></imageobject>646 </mediaobject>647 </screenshot>648 </figure>649 650 <helptext external_id="plugindefinition.jobagents"651 title="Job agents">652 653 <para>654 Use this tab to specify which job agents the plug-in is655 installed and allowed to be executed on.656 </para>657 658 <variablelist>659 <varlistentry>660 <term><guilabel>Run this plugin on</guilabel></term>661 <listitem>662 <para>663 You may select if the internal job queue should execute the664 plug-in or not.665 </para>666 </listitem>667 </varlistentry>668 <varlistentry>669 <term><guilabel>Job agents</guilabel></term>670 <listitem>671 <para>672 A list with the job agents where the plug-in is installed and673 allowed to be executed. Select a plug-in in this list to display674 more configuration options for the plug-in.675 </para>676 </listitem>677 </varlistentry>678 <varlistentry>679 <term><guilabel>Add job agents</guilabel></term>680 <listitem>681 <para>682 Use this button to open a pop-up window for selecting683 job agents.684 </para>685 </listitem>686 </varlistentry>687 <varlistentry>688 <term><guilabel>Remove</guilabel></term>689 <listitem>690 <para>691 Remove the selected plug-in from the list.692 </para>693 </listitem>694 </varlistentry>695 </variablelist>696 697 <para>698 The following properties are only displayed when a699 job agent has been selected in the list. Each job agent may have it's700 own settings of these properties. If you leave the values unspecified701 the job agent will use the default values specified on the702 <guilabel>Plugin</guilabel> tab.703 </para>704 705 <variablelist>706 <varlistentry>707 <term><guilabel>Jar path</guilabel></term>708 <listitem>709 <para>710 The path on the external server to the JAR file containing the711 plug-in code. If not specified the same path as on the web server712 is used.713 </para>714 </listitem>715 </varlistentry>716 <varlistentry>717 <term><guilabel>Max memory</guilabel></term>718 <listitem>719 <para>720 The maximum amount of memory the plug-in is allowed to use.721 Add around 40MB for the Java run-time environment and BASE.722 If not specified Java will choose it's default value which is 64MB.723 </para>724 </listitem>725 </varlistentry>726 <varlistentry>727 <term><guilabel>Trusted</guilabel></term>728 <listitem>729 <para>730 If the plug-in should be executed in a protected or731 unprotected environment. Currently, BASE only supports732 running plug-ins in an unprotected environment.733 </para>734 </listitem>735 </varlistentry>736 <varlistentry>737 <term><guilabel>Priority boost</guilabel></term>738 <listitem>739 <para>740 Used to give a plug-in higher priority in the queue.741 Values between 0 and 10 are allowed. A higher value will742 give the plug-in higher priority. The priority boost is useful743 if we, for example, want to use one server mainly for importing744 data. By giving all import plugins a priority boost they will745 be executed before all other jobs, which will have to wait746 until there are no more waiting imports.747 </para>748 </listitem>749 </varlistentry>750 </variablelist>751 752 <seeother>753 <other external_id="plugindefinition.edit">Plug-in properties</other>754 <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>755 </seeother>756 </helptext>757 </sect1>758 663 759 664 <sect1 id="plugins.configuration"> … … 774 679 <menuchoice> 775 680 <guimenu>Administrate</guimenu> 776 <guisubmenu>Plug ins</guisubmenu>777 <guimenuitem> Configurations</guimenuitem>681 <guisubmenu>Plug-ins & extensions</guisubmenu> 682 <guimenuitem>Plug-in configurations</guimenuitem> 778 683 </menuchoice> 779 page .684 page or from the single-item view page of each plug-in. 780 685 </para> 781 686 … … 959 864 <note> 960 865 <title>Do not go back</title> 866 <para> 961 867 It is not possible to go backwards in the wizard. 962 868 If you try it will most likely result in an 963 869 unexpected error and the configuration must be restarted 964 870 from the beginning. 871 </para> 965 872 </note> 966 873 … … 979 886 BASE ships with one importer and one exporter that allows 980 887 you to import and export plug-in configurations. This makes 981 it easy to copy configurations between servers. The BASE website 982 also has a <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/admin/plugin_configuration/coreplugins.html" 983 >page where you can download additional configurations</ulink> 984 not included in the main distribution. 888 it easy to copy configurations between servers. 985 889 </para> 986 890 … … 990 894 <menuchoice> 991 895 <guimenu>Administrate</guimenu> 992 <guisubmenu>Plug ins</guisubmenu>993 <guimenuitem> Configurations</guimenuitem>896 <guisubmenu>Plug-ins & extensions</guisubmenu> 897 <guimenuitem>Plug-in configurations</guimenuitem> 994 898 </menuchoice> 995 899 </para> … … 1463 1367 </sect2> 1464 1368 1465 <sect2 id="plugins.configuration.base1">1466 <title>Configuring Base1PluginExecuter</title>1467 <para>1468 BASE version 1 plug-ins are supported through the use of1469 the <emphasis>Base1PluginExecuter</emphasis> plug-in. Each1470 BASE version 1 plug-in must have at least one1471 Base1PluginExecuter configuration to work. To install a BASE1472 version 1 plug-in follow these instructions:1473 </para>1474 1475 <orderedlist>1476 <listitem>1477 <para>1478 Install the BASE version plug-in package as outlined in1479 <xref linkend="plugins.installation.base1" />1480 </para>1481 </listitem>1482 1483 <listitem>1484 <para>1485 Upload the <filename>*.base</filename> file for the BASE1486 version 1 plug-in. If you cannot find the file, you can let1487 your BASE version 1 server create one for you. In your BASE1488 version 1 installation go to1489 <menuchoice>1490 <guimenu>Analyze data</guimenu>1491 <guimenuitem>Plug-ins</guimenuitem>1492 </menuchoice>1493 and use the <guilabel>Export</guilabel> function. This will1494 create a configuration file for your BASE version 1 plug-in1495 that you can upload to your new BASE server.1496 </para>1497 </listitem>1498 1499 <listitem>1500 <para>1501 Create a new plug-in configuration using, for example,1502 the <guibutton>New configuration</guibutton> button in1503 single-item view for1504 the <emphasis>Base1PluginExecuter</emphasis> plug-in.1505 </para>1506 </listitem>1507 1508 <listitem>1509 <para>1510 Start the configuration wizard and select1511 the <filename>*.base</filename> file describing the BASE1512 version 1 plug-in and enter the path and file name to the1513 location of the executable.1514 </para>1515 </listitem>1516 1517 <listitem>1518 <para>1519 To check that the new plug-in works correctly, you need to1520 have an experiment with some data. Go to the single-item1521 view for a bioassay set and click on the <guibutton>Run1522 analysis</guibutton> button. Select1523 the <emphasis>Base1PluginExecuter</emphasis> plug-in. The1524 list of configurations should include the newly installed1525 plug-in. Select it and click on &gbNext;.1526 </para>1527 </listitem>1528 1529 <listitem>1530 <para>1531 This will enter regular plug-in execution wizard and you1532 will have to enter parameters needed by the plug-in.1533 </para>1534 </listitem>1535 1536 </orderedlist>1537 1538 </sect2>1539 1540 1369 </sect1> 1541 1370 -
trunk/doc/src/docbook/appendix/web.xml.xml
r5678 r5737 168 168 files to a compiler that includes the extension supplied JAR file(s) 169 169 in the class path. Can be disabled if no extensions use this feature. 170 See also <xref linkend=" admin.extensions.xjspcompiler" /> for more information170 See also <xref linkend="plugins.installation.xjspcompiler" /> for more information 171 171 about how to enable this feature. 172 172 </para> -
trunk/doc/src/docbook/developerdoc/api_overview.xml
r5525 r5737 3464 3464 which are regular JSP files with a different extension. This feature is 3465 3465 experimental and requires installing an extra JAR into Tomcat's lib 3466 directory. See <xref linkend=" admin.extensions.xjspcompiler" /> for3466 directory. See <xref linkend="plugins.installation.xjspcompiler" /> for 3467 3467 more information. 3468 3468 </para> -
trunk/doc/src/docbook/developerdoc/extensions.xml
r5654 r5737 48 48 extensions. From this page, if you are logged in with enough permissions, 49 49 it is also possible to configure the extensions system, enable/disable 50 extensions, etc. Read more about this in <xref linkend=" admin.extensions" />.50 extensions, etc. Read more about this in <xref linkend="plugins" />. 51 51 </para> 52 52 … … 63 63 <listitem> 64 64 <para> 65 <xref linkend=" admin.extensions" />.65 <xref linkend="plugins" />. 66 66 </para> 67 67 </listitem> … … 913 913 X-JSP compiler is installed into Tomcat's internal <filename>/lib</filename> 914 914 directory. It is an optional step and not all BASE installations 915 may have the compiler installed. See <xref linkend=" admin.extensions.xjspcompiler" />.915 may have the compiler installed. See <xref linkend="plugins.installation.xjspcompiler" />. 916 916 </para> 917 917 </note> -
trunk/doc/src/docbook/developerdoc/plugin_developer.xml
r5654 r5737 190 190 the auto-installation wizard. The wizard makes it very easy for a 191 191 server administrator to install new plug-ins. See 192 <xref linkend="plugins. autoinstall" />.192 <xref linkend="plugins.installation.wizard" />. 193 193 </para> 194 194 -
trunk/lib/docbook/custom-styles/docbook/plain/css/docbook.css
r5678 r5737 233 233 } 234 234 235 div.warning div.tip {235 div.warning div.tip, div.important div.note { 236 236 background-color: #ffffff; 237 237 } -
trunk/www/admin/extensions/wizard.jsp
r5616 r5737 94 94 <input type=hidden name="cmd" value="DoManualScan"> 95 95 96 <h3 class="docked">Extensions and plug-ins installation wizard <base:help helpid="extensions. manualscan" /></h3>96 <h3 class="docked">Extensions and plug-ins installation wizard <base:help helpid="extensions.install-wizard" /></h3> 97 97 <tbl:table id="extensions" clazz="itemlist"> 98 98 <tbl:columndef id="file" title="File" />
Note: See TracChangeset
for help on using the changeset viewer.