Install and configure Zowe server component
Install and configure Zowe server component
Learn how to install and configure the Zowe server components or extensions manually or by using scripts zowe-install-component.sh
and zowe-configure-component.sh
.
zowe-install-component.sh
(Technical Preview)#
Install with Technical PreviewNote: This section is for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future.
Note: this feature is added with Zowe v1.19.0 release.
From Zowe v1.19.0, Zowe ships a bin/zowe-install-component.sh
tool to help you install any Zowe server component (extension). Zowe core components are also installed with this tool. In order to be compatible with the tool, we recommend components follow Zowe server component package format standard.
The tool can be executed from z/OS USS, and it takes these command line parameters:
-o|--component-file
: (Required) Defines the path to the component package or directory.-c|--component-name
: Specifies the name of the component. This parameter is optional ifNODE_HOME
is defined and the component has the manifest file. Otherwise, it's required.-i|--instance-dir
: (Optional) Defines the path to the Zowe instance directory. When a value is defined, the script will also executebin/zowe-configure-component.sh
once it's installed.-d|--target-dir
: (Optional) Defines the path to the installation target directory. For native components, the default value is${ZOWE_ROOT_DIR}/components
. For non-native components, the script will check the value of theZWE_EXTENSION_DIR
variable. If the value is also empty, the script will fall back to the default target directory/global/zowe/extensions
.-e|--auto-encoding
: (Optional) Defines whether to automatically tag the encoding of the files that are shipped with the component. The default value isauto
, which indicates that the script will determine whether the automatic tagging is needed or not. Note that the automatic tagging process is opinionated about which file extensions should be in which encoding. If this does not fit in your needs, apax
format is recommended to include the tagging information into your package. This option is only applicable for z/OS. Allowed values include:yes
: automatically tag the encoding of the files.no
: do not automatically tag encoding of the files.auto
: tag only when manifest is inISO8859-1
encoding.
-k|--core
: This is an optional boolean. It defines whether this component is bundled into the Zowe package as a core component.-l|--logs-dir
: (Optional) Specifies the path to the log directory.-f|--log-file
: (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified.
Examples
This command installs my-zowe-component-1.2.3.pax
into /global/zowe/extensions
.
$ zowe-install-component.sh -o /path/to/my-zowe-component-1.2.3.pax
This command installs my-zowe-component-1.2.3.zip
into /var/zowe/my-extensions
and also configures this component for the Zowe instance located at /var/zowe/instance
. The installation and configuration logs will be written into /var/zowe/instance/logs
.
$ zowe-install-component.sh \ -o /path/to/my-zowe-component-1.2.3.zip \ -d /var/zowe/my-extensions \ -i /var/zowe/instance \ -l /var/zowe/instance/logs
zowe-configure-component.sh
(Technical Preview)#
Configure with Technical PreviewNote: This section is for technical preview and we are happy to hear any feedback. Content in this section may be changed or improved in the future.
Note: This feature is added with Zowe v1.19.0 release.
From Zowe v1.19.0, Zowe ships a bin/zowe-configure-components.sh
tool to help you configure an installed Zowe server component (extension) for a Zowe instance. Zowe core components are also configured with this tool. In order to be compatible with the tool, we recommend components follow Zowe server component package format standard.
You may not need to run this script directly if you have supplied -i|--instance-dir
when you run zowe-install-component.sh
.
The tool can be executed from z/OS USS, and it takes these command line parameters:
-c|--component-name
: (Required) Specifies the name of the component.-i|--instance-dir
: (Required) Defines the path to the Zowe instance directory.-d|--target-dir
: (Optional) Defines the directory where the component is installed. For native components, the default value is${ZOWE_ROOT_DIR}/components
. For non-native components, the script will checkZWE_EXTENSION_DIR
if possible. Otherwise, it will fall back to the default target directory/global/zowe/extensions
.-k|--core
: This is an optional Boolean. It defines whether this component is bundled into the Zowe package as a core component.-l|--logs-dir
: (Optional) Defines the path to the log directory.-f|--log-file
: (Optional) Instead of writing independent log to a directory, you have option to append log to this log file specified.
Examples
This command configures my-zowe-component
installed in /global/zowe/extensions
for the Zowe instance located at /var/zowe/instance
.
$ zowe-configure-component.sh \ -c my-zowe-component \ -i /var/zowe/instance
This command configures my-zowe-component
installed in /var/zowe/my-extensions
for the Zowe instance located at /var/zowe/instance
. The configuration logs will be written into /var/zowe/instance/logs
.
$ zowe-configure-component.sh \ -c my-zowe-component \ -i /var/zowe/instance \ -d /var/zowe/my-extensions \ -l /var/zowe/instance/logs
#
Install and configure manually#
Zowe core componentsThe Zowe runtime directory delivers its core components in the <RUNTIME_DIR>/components/
directory. A typical components directory looks like this:
<RUNTIME_DIR>/components/ /discovery /gateway /app-server /explorer-jes /explorer-mvs /files-api /jobs-api /...
You can configure whether to start the Zowe core component or not with the LAUNCH_COMPONENTS
variable defined in <INSTANCE_DIR>/instance.env
. The value of this variable can be a comma-separated list of core component names.
Note: You can also use full USS path to the component bin
directory which contains lifecycle scripts, but this behavior will be deprecated in next major release.
#
Zowe extensionsIt is suggested that you install all Zowe extension runtime programs into a single location. The suggested default extension directory is /global/zowe/extensions
. Each extension should be represented with the extension name in this directory, either a directory or a symbolic link. This location should be defined as ZWE_EXTENSION_DIR
in <INSTANCE_DIR>/instance.env
.
The Zowe launch script reads EXTERNAL_COMPONENTS
defined in <INSTANCE_DIR>/instance.env
to decide whether to start an extension. The value of EXTERNAL_COMPONENTS
is a comma-separated list of extension names.
Note: You can also use full USS path to the extension bin
directory which contains lifecycle scripts, but this behavior will be deprecated in next major release.
#
ExampleThe vendor MYVENDOR has a product named MYAPP that installs into /usr/lpp/myvendor/myapp
. There is one Zowe extension shipped within it in the directory /usr/lpp/myvendor/myapp/zowe-ext
. This subdirectory is a Zowe extension so they want it to be started and stopped with Zowe and run as an address space under the ZWESVSTC
started task in the Zowe USS shell.
The directory /usr/lpp/myvendor/myapp/zowe-ext
should include a manifest.yaml
file to describe the extension. The script /usr/lpp/myvendor/myapp/zowe-ext/bin/validate.sh
checks that the environment has been configured correctly and the script /usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh
starts the vendor application. The /usr/lpp/myvendor/myapp/zowe-ext/manifest.yaml
should look like this:
name: myappid: com.myvendor.myapptitle: My Zowe Extensioncommands: validate: bin/validate.sh start: bin/start.sh
Because MYAPP is shipped within another product, the installation should create a symbolic link in ZWE_EXTENSION_DIR
directory.
$ ls -l /global/zowe/extensionstotal 16lrwxrwxrwx 1 <USER> <GROUP> 23 Nov 11 2019 myapp -> /usr/lpp/myvendor/myapp/zowe-ext
Also myapp
will be added into the value of the EXTERNAL_COMPONENTS
variable in <INSTANCE_DIR>/instance.env
.
ZWE_EXTENSION_DIR=/global/zowe/extensionEXTERNAL_COMPONENTS=some-other-extensions,myapp
You might need to manually run the script <INSTANCE_DIR>/bin/install-app.sh
if your component is a Desktop plug-in. Or you can choose to add this step to Zowe component Configure lifecycle stage.
When the Zowe instance is launched by running <INSTANCE_DIR>/bin/zowe-start.sh
, it will read manifest commands
instructions and call the /usr/lpp/myvendor/myapp/zowe-ext/bin/start.sh
script. The started task will create an address space under ZWESVSTC
for the vendor component. When the Zowe instance is stopped, the address space is terminated.