Installing Plugins
Plugins can be added or removed from the Zowe App Server, as well as upgraded. There are two ways to do these actions: By REST API or by filesystem. The instructions below assume you have administrative permissions either to access the correct REST APIs or to have the necessary permissions to update server directories & files.
NOTE: Plugins must be pre-built, and follow the directory structure, and have all dependencies met to be successfully installed. Read the server log in <INSTANCE_DIR>/log/install-app.log, (ex ~/.zowe/log/install-app.log) if a plugin does not show in the Zowe desktop, but has been installed successfully.
The App server uses directories of JSON files, described in the wiki. Defaults are located in the folder zlux-app-server/defaults/plugins, but the server reads the list of plugins instead from the instance directory, at <INSTANCE_DIR>/workspace/app-server/plugins (ex ~/.zowe/workspace/app-server/plugins which includes JSON files describing where to find a plugin. Adding or removing JSONs from this folder will add or remove plugins upon server restart (or you can use REST APIs & cluster mode to add or remove plugins without restarting).
Prior to Zowe release 1.8.0, the location of the default and instance plugins directory were located within zlux-app-server folder unless otherwise customized.
1.8.0 has backwards compatibility for the existence of these directories, but they can and should be migrated to take advantage of future enhancements.
| Folder | New Location | Old Location | Note |
|---|---|---|---|
| Default plugins | zlux-app-server/defaults/plugins | zlux-app-server/plugins | |
| Instance plugins | <INSTANCE_DIR>/workspace/app-server/plugins | zlux-app-server/instance/ZLUX/plugins | INSTANCE_DIR is ~/.zowe if not otherwise defined |
To add/install a plugin, run the script zlux-app-server/bin/install-app.sh providing the location to a plugin folder.
For example,
./install-app.sh /home/john/zowe/sample-angular-app
This will generate a JSON file that states the plugin's ID and its location on disk. These JSON files tell the Desktop where to find apps. For example, if we were to install the sample angular-app in the folder /home/john/zowe/sample-angular-app, then the JSON would be:
{
"identifier":"org.zowe.zlux.sample.angular",
"location": "/home/john/zowe/sample-angular-app"
}To remove a plugin, locate the server's instance plugin directory <INSTANCE_DIR>/workspace/app-server/plugins (ex ~/.zowe/workspace/app-server/plugins`) and remove the locator JSON that is associated with that plugin. Remove the plugin's content by deleting it from the file system if applicable.
Currently, only one version of a plugin can exist per server. So, to upgrade, you either upgrade the plugin within its pre-existing directory by rebuilding it (with more up to date code), or you alter the locator JSON of that app to point to the content of the upgraded version.
The server's reading of the locator JSONs and initializing of plugins only happens during bootstrapping at startup. However, in cluster mode the bootstrapping happens once per worker process. Therefore, it is possible to manage plugins without a server restart by killing & respawning all worker processes without killing the cluster master process. This is what the REST API does, internally. To do this without the REST API, it may be possible to script knowing the parent process ID, and running a kill command on all child processes of the App server cluster process.
The server REST APIs allow plugin management without restarting the server - you can add, remove, and upgrade plugins in real-time. However, removal or upgrade must be done carefully as it can disrupt users of those plugins.
This swagger file documents the REST API for plugin management
The API only works when RBAC is configured, and an RBAC-compatible security plugin is being used.
An example of this is zss-auth, and use of RBAC with it is described in the Zowe documentation. Wiki also here.