![[Important]](../gfx/admonitions/important.png) |
Changes since BASE 2 |
|---|---|
|
The plug-in and extensions installation has changed since BASE 2. The major changes are:
|
The first step is to install the actual code on the web server. The recommendation to developers is to ship the entire package as a single JAR file. If everything is JAVA based this should not be a problem. A common exception is that configuration files should be installed (and configured) separately. Always read the installation instructions for the package you are installing. The rest of the instructions in this section assume that the plug-in/extensions comes as a single JAR file.
![[Note]](../gfx/admonitions/note.png) |
Make sure the extensions folder is writable by Tomcat |
|---|---|
|
The package you are installing may include resources such as HTML
files, JSP scripts, images, etc. that needs to be extracted to the
web application path before they can be used. This extraction is
automatically done by the installation wizard, but you have to make
sure that the user account Tomcat is running as has permission
to create (and delete) new files in the
|
So, the first step should be simple. Just put the JAR file in the
dedicated plug-ins directory. This is the directory that is specified
in the plugins.dir setting in base.config.
|
Content security policy |
|---|---|
|
Since BASE 3.3 the default configuration specify a setting that tell web browsers to not execute code (including JavaScript) that is considered unsafe. Older extensions may not adhere to the restrictions implied by this and may thus not work unless the configured Content security policy is relaxed a bit. The extension installation wizard will try to detect if a plug-in violates the policy and display a warning message. If you see the warning please read Section E.1, “Content security policy” for more information. |
When the plug-in/extensions package is installed on the server you must register it with BASE. Go to .
The left-hand side of the screen shows a tree with all installed plug-ins and extensions, sorted by extension point and by file. Use the + and - icons to expand and collapse parts of the tree. Click on an item in the tree to display detailed information about it on the right-hand side of the screen. Click on the button to start the installation wizard (which can also be used for uninstallation).
This wizard can be used for both installing, re-installing and un-installing plug-in and extension packages. The first dialog shows a list with all currently installed packages as well as any new packages that has been found on the server. The list includes the name of the JAR file, the current status and some information provided by the author of the package. There are also three columns Install, Uninstall and Ignore which may or may not have a checkbox in them. For new packages there should be a checkbox in the install column that is already checked. Already installed packages can either be re-installed or uninstalled by checking the appropriate checkbox. If there is a problem with a package an error message is displayed and neither installation or uninstallation is possible.
The Ignore column can be used to tell the wizard to ignore the selected file from now on. Ignored files are moved to a separate section at the bottom of the installation wizard and you will not be asked about installing them every time you run the wizard. Ignored files can either be brought back to the regular flow with the Stop ignore option or directly installed with the Install button.
Click on to perform the selected actions. The next dialog should display a summary with the installation results. Hopefully everything was succeessful. Close the dialog and refresh the overview tree to see the changes.
|
Note |
|---|---|
|
Uninstalling a package doesn't remove the plug-in definitions from BASE nor does it remove the JAR file from the server. This is because there may be jobs and other items referencing the plug-ins. The plug-ins are only marked as disabled and it is up to the administrator to actually delete them if it is possible. |
Manual installation of a plug-in should almost never be neccessary. One exception is that developers may want to do this as a first step before everything has been properly packaged. Another exception is plug-ins developed for BASE 2 that doesn't support the automatic installation procedure. If the old plug-in still works API-wise in BASE 3, manual installation can be used to install it. Repackaging such a plug-in is however not difficult so we recommend that the plug-in author is asked to provide an updated version.
To perform a manual installation the plug-in's JAR file must be
located in the the directory specified by the plugins.dir
setting in base.config. Subdirectories are not
allowed. This is a change since BASE 2 were plug-ins could be installed
almost anywhere. When the JAR file is in place, go to
and click on the button.
- Name
-
The name of the plug-in. This name is set automatically by the plug-in and cannot be changed.
- Class
-
The full Java class name of the plug-in.
- JAR file
-
The name of the JAR file on the web server. The JAR file must be installed in the directory specified by the
plugins.dirsetting inbase.configIf left empty the plug-in must be on the web server's class path (not recommended). - Max memory
-
The maximum amount of memory the plug-in may use. This setting only applies when the plug-in is executed with a job agent. If the internal job queue is used this setting has no effect and the plug-in may use as much memory as it likes. See Section 21.3.4, “Configuring the job agent” for more information.
- Trusted
-
If the plug-in is trusted enough to be executed in an unprotected environment. This setting has currently no effect since BASE cannot run in a protected environment. When this becomes implemented in the future a no value will apply security restrictions to plug-ins similar to those a web browser put on applets. For example, the plug-in is not allowed to access the file system, open ports, shut down the server, and a lot of other nasty things.
- Allow immediate execution
-
If the plug-in is allowed to bypass the job queue and be executed immediately.
-
No: The plug-in must always use the job queue.
-
Yes: The plug-in is allowed to bypass the job queue. This also means that the plug-in always executes on the web server, job agents are not used. This setting is mainly useful for export plug-ins that needs to support immediate download of the exported data. See the section called “Immediate download of the exported data”.
Note If a plug-in should be executed immediately or not is always decided by the plug-in. BASE will never give the users a choice. -
Auto: BASE will allow export plug-ins to execute immediately, and deny all other types of plug-ins. This alternative is only available when registering a new plug-in.
-
Click on to finish the registration or on to abort.
BASE version 1 plug-ins are supported through the use of the Base1PluginExecuter plug-in. This is itself a plug-in and BASE version 1 plug-ins are added as configurations to this plug-in (cf. Section 22.2, “Plug-in configurations”). To install a BASE version 1 plug-in follow these instructions:
-
Install the BASE version 1 plug-in executable and any other files needed by it on the BASE server. Check the documentation for the plug-in for information about what is needed.
-
Upload the
*.basefile for the BASE version 1 plug-in. If you cannot find the file, you can let your BASE version 1 server create one for you. In your BASE version 1 installation go to and use the Export function. This will create a configuration file for your BASE version 1 plug-in that you can upload to your new BASE server. -
Create a new plug-in configuration using, for example, the button in single-item view for the Base1PluginExecuter plug-in.
-
Start the configuration wizard and select parameters:
-
File: The
*.basefile describing the BASE version 1 plug-in. This can be left empty for manual configuration, but in reality it is only usable for tweaking an existing configuration that has been created from a file in the first place. -
Plugin executables path: The path to the executable program that was installed in the first step.
-
Source intensities: Select if the plug-in can work with regular or logged data (or both).
-
Resulting intensities: Select if the plug-in generates regular or logged data.
Click to finish the wizard.
-
-
To check that the new plug-in works correctly, you need to have an experiment with some data. Go to the single-item view for a bioassay set and click on the button. Select the Base1PluginExecuter plug-in. The list of configurations should include the newly installed plug-in. Select it and click on .
-
This will enter regular plug-in execution wizard and you will have to enter parameters needed by the plug-in.
Some extensions may want to use custom JSP files that also uses
classes that are stored in the extension's JAR file. The problem
with this is that Tomcat usually doesn't know to look for classes
in the plugins.dir directory. To solve
this problem BASE ships with a X-JSP compiler that can do this.
This compiler has been mapped to files with a .xjsp
extension, which are just regular JSP files with a different extension.
The X-JSP compiler must be installed into Tomcat's internal
library folder ($CATALINA_HOME/lib)
since this is the only place where Tomcat look for compilers. The installation
is easy. Simply copy <base-dir>/bin/jar/base-xjsp-compiler-3.x.jar
to $CATALINA_HOME/lib and restart Tomcat.
|
X-JSP is experimental |
|---|---|
|
This is an experimental feature that depends on internal functionality in Tomcat. It may or may not work with future versions of Tomcat. The compiler will most likely not work with other servlet containers. |
It is possible to disable specific extensions, extension point and or a plug-in without uninstalling the XML or JAR file. When you click on an item in the tree on the left-hand side of the screen a lot of detailed information about it will show up on the right-hand side. The right-hand side usually has a or button in the toolbar. Click on that button to disable the plug-in, extension or all extensions for an extension point. The button will change to or which lets you enable the extensions and plug-ins again.
When a plug-in is executed the default is to give it the same permissions as the user that started it. This can be seen as a security risk if the plug-in is not trusted, or if someone manages to replace the plug-in code with their own code. A malicious plug-in can, for example, delete the entire database if invoked by the root user.
To limit this problem it is possible to tune the permissions for a plug-in so that it only has permission to do things that it is supposed to do. For example, a plug-in that import reporters may only need permission to update and create new reporters and nothing else.
To enable the permission system for a plug-in go the edit view of the plug-in and select the Permissions tab.
- Use permissions
-
Select if the plug-in should use the permission system or not. If no is selected, the rest of the form is disabled.
- Item types
-
The list contains all item types found in BASE that can have permissions set on them. The list is more or less the same as the permission list for roles. See the section called “Permissions”.
- Always grant
-
The selected permissions will always be granted to the plug-in no matter if the logged in user had the permission to begin with or not. This makes it possible to develop a plug-in that allows users to do things that they are normally not allowed to do. The reporter importer is for example allowed to create and use reporter types.
- Always deny
-
The selected permissions will always be denied to the plug-in no matter if the logged in user had the permission to begin with or not. The default is to always deny all permissions. Permissions that are not always denied and not always granted uses permissions from the logged in user.
- Requested by plug-in
-
To make it easier for the server administrator to assign permissions, the plug-in developer can let the plug-in include a list of permissions that are needed. Plug-in developers are advised to only include the minimal set of permissions that are required for the plug-in to function. Click on the button to give the plug-in the requested permissions.