Description

This plug-in includes steps for installing and updating applications in the IBM WebSphere Liberty Profile, working with the profile configuration, and managing Liberty collectives.

Quick Info

Product
HCL Launch
Type
plugin
Compatibility
Created by
HCL Software
Version Name Action

21.1100824

launch-websphereliberty-21.1100824.zip

launch-websphereliberty-21.1100824.zip

21.1100824


Summary

The IBM WebSphere Application Server Liberty profile is a lightweight configuration of IBM WebSphere Application Server. It provides rapid deployment of applications for use in the development process. You can use the plugin to complete the following task:

  • Working with servers in the profile
  • Install, update, and uninstall applications
  • Work with Liberty collectives
  • Configure the Liberty server

This plugin includes one or more steps, click Steps for step details and properties.

Compatibility

This plugin requires version 6.0 or later of HCL Launch.

This plugin was tested with WebSphere Liberty profile versions 8.5.5.9 16.0.0.2.

Installation

See Installing plugins in HCL Launch for installing and removing plugins.

History

The following table describes the changes made in each plugin version.

Plugin history details
Version Description
21 Minor enhancements

Usage

To use the Wait for Application to be STARTED step, you must complete the following steps to configure the REST connector for the WebSphere Application Server Liberty profile:

  • In the server.xml file on the server, enable the REST connector, SSL certificates, and an administrator role for a user or group. You must use an administrator account to run the Wait for Application to be STARTED step. For more information, see the documentation for your version of the WebSphere Application Server Liberty Profile. For example, for version 8.5, see the following topic: Configuring secure JMX connection to the Liberty profile
  • Update the server to listen on all endpoints. For example, the default server.xml file contains a line that is similar to the following example:
    <httpEndpoint host="localhost" httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"/>

    In this code, set the host attribute to the wildcard character (*), as shown in the following example:

    <httpEndpoint host="*" httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"/>

Steps

The following process steps are available in the WebSphere Liberty plugin

Create Collective

Create a new collective controller configuration in the WebSphere Liberty Profile.

Input properties for the Create Collective step
Name Type Description Required
Additional command arguments String Any additional arguments that should be passed to the collective create command No
Keystore Password Password The password to use for the generated keystores Yes
Password Password The password to include in quickStartSecurity XML node Yes
Server Name String The name of the server to act as the collective controller Yes
User Name String The name of the user to include in quickStartSecurity XML node Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/ Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Create Server

Create a server in the WebSphere Liberty profile.

Input properties for the Create Server step
Name Type Description Required
Server Name(s) String The name of the server(s) to create. Multiple server names are separated by commas. Yes
WebSphere Liberty Installation Directory String The base directory for the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Delete Server

Delete a server in the WebSphere Liberty profile.

Input properties for the Delete Server step
Name Type Description Required
Server Name(s) String The name of the server(s) to delete. Multiple server names are separated by commas. Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Generate Component-Resource Properties

Generate Component-Resource properties from variable tags in the server.xml file

Input properties for the Generate Component-Resource Properties step
Name Type Description Required
Location of the server.xml file String The location of the server.xml file to be processed. Yes

Generate Plugin Config

Generate plugin configuration for a WebSphere Liberty server.

Input properties for the Generate Plugin Config step
Name Type Description Required
Install Root String The installation root to add to the plugin configuration. This property is required
if Server Name is specified.
No
Password Password The password for WebSphere Liberty. Yes
Server HTTPS Port String The HTTPS port of the server. Yes
Server Hostname String The host name or IP address of the server. Yes
Server Name String The name of the server to add to the plugin configuration. This property is required
if Install Root is specified.
No
Trust Store File Path String The path to the trust store file. This path can be relative or absolute. Yes
Trust Store Password Password The password for the trust store file. Yes
User Name String The user name for WebSphere Liberty. Yes

Install Server Archive

Install a WebSphere Liberty archive file.

Input properties for the Install Server Archive step
Name Type Description Required
Accept License Boolean Select to automatically accept the license if extracting from a jar file. Yes
Source File String The archive file to extract. Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/ Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Install or Update Application with Server XML

Install or update an application in the WebSphere Liberty profile by editing the server.xml file.

Input properties for the Install or Update Application with Server XML step
Name Type Description Required
Application Name String The name of the application to install. Yes
Application Type String The type of application archive. Valid values are war, ear, eba, and esa. Yes
Auto Start Boolean Select to configure the application to start automatically when the server starts. No
Context Root String The context root of the application. No
Server Name String The name of the server to install the application into. Yes
Source File Location String Location of the application, expressed as an absolute path or a path that is relative
to the server-level apps directory.
Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Install or Update Applications with Dropins

Install or update an application in WebSphere Liberty by using the dropins directory.

Input properties for the Install or Update Applications with Dropins step
Name Type Description Required
Server Name String The name of the server to install the application into. Yes
Source File String The archive file (for example, an EAR or WAR file) that contains the application to
install.
Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Join Collective

Join a server to the collective controlled by the designated controller.

Input properties for the Join Collective step
Name Type Description Required
Additional command arguments String Any additional arguments that should be passed to the collective join command No
Admin Password Password The password for the Administrator user for the target Collective Controller Yes
Admin User Name String An Administrator user for the target Collective Controller Yes
Collective Controller Host Name String The host name of the target Collective Controller Yes
Collective Controller Port String The HTTPS port number of the target Collective Controller Yes
Keystore Password Password The password to use for the generated keystores Yes
RPC User String The user with which to authenticate to the RPC mechanism No
RPC User Password Password The password for the rpcUser. Only one authentication option (rpcUserPassword or
sshPrivateKey) should be used, but not both.
No
SSH Private Key Password Password The password for the specified SSH key No
SSH Private Key Path String The path to the SSH key to use to authenticate to the host. Only one authentication
option (rpcUserPassword or sshPrivateKey) should be used, but not both.
No
Server Host Name String The name of the collective host where the server to join resides No
Server Name(s) String The name of the server(s) that will join the Collective. Multiple server names are
separated by commas.
Yes
Trust Store File Path String The path to the trust store to be used when connecting to the collective controller No
Trust Store Password Password The password for the trust store file. No
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/.
This path is on the host where the server joining the collective resides.
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Merge Plugin Config

Merge multiple plugin-cfg.xml files into one xml for web servers for clarity and eliminate errors caused by dealing with multiple config files.

Input properties for the Merge Plugin Config step
Name Type Description Required
Source Directory String Location of the source directory where all the plugin files are located, or a comma
separated list of source plugin file names specified as full filepaths
Yes
Target Directory String Parent directory of the merge-plugin-cofig file Optional. By default the merged file
is generated in the same directory where pluginUtility.sh is located and named merged-plugin-cfg.xml.
Users can either specify the directory name where the merged file must be placed,
or a fully qualified file name. In case there is already a file named merged-plugin-cfg.xml
or the specified file specified file name is already present, then the contents of
the file will be overwritten.
No
WebSphere Liberty Installation Directory String The base directory for the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Propagate Plugin Config

Make the merged plugin config xml available to the web server.

Input properties for the Propagate Plugin Config step
Name Type Description Required
Plugin-Config File String Full filepath of the plugin config xml targeted for use by the web server. This is
produced by the Merge Plugin Config step.
Yes
Web Server Home String The install directory of web server. For example: /opt/IBM/HTTPServer Yes
WebSphere Plugins Home String Full path to top-level directory where WebSphere Plugins are installed. This directory
contains libraries used to connect WebSphere Liberty servers to web servers.
Yes

Register Host

Register a new host with the collective controlled by the designated controller.

Input properties for the Register Host step
Name Type Description Required
Additional command arguments String Any additional arguments that should be passed to the collective registerHost command No
Admin Password Password The password for the Administrator user for the target Collective Controller Yes
Admin User Name String An Administrator user for the target Collective Controller Yes
Collective Controller Host Name String The host name of the target Collective Controller Yes
Collective Controller Port String The HTTPS port number of the target Collective Controller Yes
Host JAVA_HOME Path String The path to the Java home directory for the registrant. No
Host Name String The name of the host that will be registered with the Collective Yes
Host Read Path String A readable path for the file transfer operations originated from the controller.
Specify multiple paths on separate lines.
No
Host Write Path String A writable path for the file transfer operations originated from the controller.
Specify multiple paths on separate lines.
No
RPC User String The user with which to authenticate to the RPC mechanism No
RPC User Password Password The password for the rpcUser. Only one authentication option (rpcUserPassword or
sshPrivateKey) should be used, but not both.
No
SSH Private Key Password Password The password for the specified SSH key No
SSH Private Key Path String The path to the SSH key to use to authenticate to the host. Only one authentication
option (rpcUserPassword or sshPrivateKey) should be used, but not both.
No
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/ Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Replace Variable Values with Component-Resource Properties

Replace variable values in the server.xml file with Component-Resource properties

Input properties for the Replace Variable Values with Component-Resource Properties step
Name Type Description Required
Location of the server.xml file String The location of the server.xml file to be processed. Yes

Start Application

Start an application in the WebSphere Liberty profile.

Input properties for the Start Application step
Name Type Description Required
Application Name String The name of the application to start. Yes
Password Password The password for WebSphere Liberty. Yes
Server HTTPS Port String The HTTPS port of the server. Yes
Server Hostname String The host name or IP address of the server. Yes
Trust Store File Path String The path to the trust store file. This path can be relative or absolute. Yes
Trust Store Password Password The password for the trust store file. Yes
User Name String The user name for WebSphere Liberty. Yes

Start Server

Start one or more servers in the WebSphere Liberty profile. This step will create output properties named startedServers, alreadyStartedServers, and failedServers. Servers that were successfully started will be listed in the startedServers output property. Servers that were already in the started state will be listed in the alreadyStartedServers output property. Servers that failed to start will be listed in the failedServers output property.

Input properties for the Start Server step
Name Type Description Required
Admin Password Password The password for the Administrator user for the target Collective Controller No
Admin User Name String An Administrator user for the target Collective Controller No
Collective Controller Host Name String The host name of the Collective Controller that will route the startServer request
to serverHost. If controllerHost is specified, controllerPort, admin user/password,
trustStore/trustStorePassword, and serverHost must also be given.
No
Collective Controller Port String The HTTPS port number of the target Collective Controller No
Server Host Name String The name of the collective host where the server to start resides No
Server Name(s) String The name of the server(s) to start. Multiple server names are separated by commas.
Specify ALL to start all servers in wlp.user.dir.
Yes
Trust Store File Path String The path to the trust store to be used when connecting to the collective controller No
Trust Store Password Password The password for the trust store file. No
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example: /opt/IBM/WebSphere/Liberty/.
This path is on the host where the server being started resides.
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Stop Application

Stop an application in the WebSphere Liberty profile.

Input properties for the Stop Application step
Name Type Description Required
Application Name String The name of the application to stop. Yes
Password Password The password for WebSphere Liberty. Yes
Server HTTPS Port String The HTTPS port of the server. Yes
Server Hostname String The host name or IP address of the server. Yes
Trust Store File Path String The path to the trust store file. This path can be relative or absolute. Yes
Trust Store Password Password The password for the trust store file. Yes
User Name String The user name for WebSphere Liberty. Yes

Stop Server

Stop one or more servers in the WebSphere Liberty profile. This step will create output properties named stoppedServers, alreadyStoppedServers, and failedServers. Servers that were successfully stopped will be listed in the stoppedServers output property. Servers that were already in the stopped state will be listed in the alreadyStoppedServers output property. Servers that failed to stop will be listed in the failedServers output property.

Input properties for the Stop Server step
Name Type Description Required
Admin Password Password The password for the Administrator user for the target Collective Controller No
Admin User Name String An Administrator user for the target Collective Controller No
Collective Controller Host Name String The host name of the Collective Controller that will route the stopServer request to serverHost. If controllerHost is specified, controllerPort, admin user/password,trustStore/trustStorePassword, and serverHost must also be given. No
Collective Controller Port String The HTTPS port number of the target Collective Controller No
Server Host Name String The name of the collective host where the server to stop resides No
Server Name(s) String The name of the server(s) to be stopped. Multiple server names are separated by commas.
Specify ALL to stop all servers in wlp.user.dir.
Yes
Trust Store File Path String The path to the trust store to be used when connecting to the collective controller No
Trust Store Password Password The password for the trust store file. No
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example: /opt/IBM/WebSphere/Liberty/.
This path is on the host where the server being stopped resides.
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Uninstall Application from Dropins

Uninstall an application from the WebSphere Liberty profile by using the dropins directory.

Input properties for the Uninstall Application from Dropins step
Name Type Description Required
Server Name String The name of the server to uninstall the application from. Yes
Source File Name String The full name of the archive file to uninstall. For example: JPetStore.war Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Uninstall Application with Server XML

Uninstall an application in the WebSphere Liberty profile by editing the server.xml file.

Input properties for the Uninstall Application with Server XML step
Name Type Description Required
Application Name String The name of the application to uninstall. Yes
Server Name String The name of the server to uninstall the application from. Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation. For example:
/opt/IBM/WebSphere/Liberty/
Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Unregister Host

Unregisters a host and all of its associated servers from the collective.

Input properties for the Unregister Host step
Name Type Description Required
Admin Password Password The password for the Administrator user for the target Collective Controller Yes
Admin User Name String An Administrator user for the target Collective Controller Yes
Collective Controller Host Name String The host name of the target Collective Controller Yes
Collective Controller Port String The HTTPS port number of the target Collective Controller Yes
Host Name String The name of the host that will be unregistered from the Collective Yes
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/ Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Update Host

Updates the authentication information for a host that has been registered with the collective.

Input properties for the Update Host step
Name Type Description Required
Additional command arguments String Any additional arguments that should be passed to the collective registerHost command No
Admin Password Password The password for the Administrator user for the target Collective Controller Yes
Admin User Name String An Administrator user for the target Collective Controller Yes
Collective Controller Host Name String The host name of the target Collective Controller Yes
Collective Controller Port String The HTTPS port number of the target Collective Controller Yes
Host JAVA_HOME Path String The path to the Java home directory for the registrant. No
Host Name String The name of the registered host that will be updated within the Collective Yes
Host Read Path String A readable path for the file transfer operations originated from the controller.
Specify multiple paths on separate lines.
No
Host Write Path String A writable path for the file transfer operations originated from the controller.
Specify multiple paths on separate lines.
No
RPC User String The user with which to authenticate to the RPC mechanism No
RPC User Password Password The password for the rpcUser. Only one authentication option (rpcUserPassword or sshPrivateKey) should be used, but not both. No
SSH Private Key Password Password The password for the specified SSH key No
SSH Private Key Path String The path to the SSH key to use to authenticate to the host. Only one authentication
option (rpcUserPassword or sshPrivateKey) should be used, but not both.
No
WebSphere Liberty Installation Directory String The base directory of the WebSphere Liberty profile installation, such as /opt/IBM/WebSphere/Liberty/ Yes
WebSphere Liberty User Directory String The directory where WebSphere Liberty server configuration is held. Specify a value
here when ${wlp_install_dir}/usr is not writable.
No

Upload File To Collective Host

Upload a file to the target collective host. The target host must already be registered with the collective.

Input properties for the Upload File To Collective Host step
Name Type Description Required
Admin Password Password The password for the Administrator user for the target Collective Controller Yes
Admin User Name String An Administrator user for the target Collective Controller Yes
Collective Controller Host Name String The host name of the target Collective Controller Yes
Collective Controller Port String The HTTPS port number of the target Collective Controller Yes
Install Target Directory/File String The path on the target host where the source file will be installed/expanded. If
source file is not a zip to be expanded, this value must be a file path, not a directory.
Yes
Source File Path String The path to the file to upload to the target machine Yes
Target Host Name String The name of the collective host the file will be uploaded to Yes
Trust Store File Path String The path to the trust store to be used when connecting to the collective controller Yes
Trust Store Password Password The password for the trust store file. Yes

Wait for Application to be STARTED

Wait for an application to run (have a status of Started).

Input properties for the Wait for Application to be STARTED step
Name Type Description Required
Application Name String The name of the application. Yes
Password Password The password for WebSphere Liberty. Yes
Server HTTPS Port String The HTTPS port of the server. Yes
Server Hostname String The host name or IP address of the server. Yes
Timeout (seconds) String The maximum time to wait, in seconds. Yes
Trust Store File Path String The path to the trust store file. This path can be relative or absolute. Yes
Trust Store Password Password The password for the trust store file. Yes
User Name String The user name for WebSphere Liberty. Yes

Examples

Creating a collective and installing a simple application

The CreateCollectiveSampleApp.zip file contains an example HCL Launch application that creates a WebSphere Liberty collective and deploys a simple web application to the servers in the collective. The sample application runs processes to complete the following tasks:

  • Create a Liberty server and collective.
  • Register a target host with the collective.
  • Upload a Liberty package file to the registered host.
  • Join Liberty member servers from the package file to the collective.
  • Start collective member servers.
  • Deploy a simple application to the collective servers.

The example HCL Launch application assumes that you have two hosts. One host (the collective controller host) must be running the HCL Launch agent software and also must have WebSphere Liberty installed.

Import the example application archive to your HCL Launch server. When you import the application, select Import with Snapshots.

After you import the example application archive, complete the following steps.

  1. Create a top-level resource directory, and then add the agent that is running on the collective controller host to the new top-level resource.
  2. Add the WebSphereLiberty and HelloWorld components under the agent.
  3. Go to the Test environment of the ConfigureLibertyCollective application, and then click Add Base Resources to add the new resource tree as the base resource of the Test environment.
  4. Set the environment properties for the Test environment so that the values are correct for your specific environment. Change the values for all properties other than the Collective Controller Hostname, Controller Name, and Controller Port properties. Click the Configuration tab for the Test environment, and then click Environment Properties to set the values. After you enter all of the property values, click Save.
  5. You can now run the CreateConfigureDeployCollective application process on the Test environment. In the Run Process window, select the Version1 snapshot.

The process runs and installs the HelloWorld application to the member servers of the Liberty collective. Browse to the following URLs to see the output of the HelloWorld applications. The application output is Hello Tom.

https://targetHostName:9444/HelloWorld/Hello
https://targetHostName:9445/HelloWorld/Hello
https://targetHostName:9446/HelloWorld/Hello

You can also see information about the new collective by adding the Liberty Admin Center feature to the server.xml file for the controller1 server. On the collective controller host, add the following line to the LibertyInstallDir/usr/servers/controller1/server.xml file:

<feature>adminCenter-1.0</feature>

Browse to the following URL to access the Liberty Admin Center:

https://CollectiveControllerHost:9443/adminCenter

Log in to the Liberty Admin Center. For the sample application, the default administrator ID is admin and the default password is adminpwd. Click the Explore icon to display the applications, servers, and other information that is associated with the collective that the sample application created.


Installing an application on WebSphere Application Server Liberty Profile

The following component process installs a Java EE application on the WebSphere Application Server Liberty Profile. In this example, the application binary files are in the component. Also, the environment contains an installation of the Liberty profile and a server that is running. The process runs the following steps in order:

  1. The Download Artifacts step retrieves the binary files.
  2. The Install or Update Application with Drop-ins step installs the application.
  3. The Start Application starts the application.
  4. The Wait for Application to be STARTED step pauses the process until the application starts.

Article: Deploying Liberty (Part 1)

HCL Launch provides a suite of tools to handle the build, release, and deployment phases of larger DevOps cycles. HCL Launch handles automating application deployments. It provides continuous delivery during agile development, and the auditing trails, version support, and approval trails needed in production. This article describes how to set up the deployment of a single Liberty server.

Before you start, access the HCL Launch Documentation in the HCL Information Center to install and set up your HCL Launch environment.

  • I used HCL Launch 7.1.2 but the instructions apply to previous versions as well.
  • Be aware that you will need access to a License server to complete the install.
  • Install the IBM Websphere Liberty plug-in, an add-on to the base HCL Launch Server.

The order in which the HCL Launch objects are created in this article is slightly different from the recommended path:
Application → Components → Resources/agents → Environments

This is so that you can test a component process in isolation once the component is added to the application. This eliminates the need to create an application process before testing a component. This also allows the option of grouping any properties that can be re-used across components under the application property section.

The order recommended by the HCL Launch tutorial documentation is to create the components before the application.

1. Creating the HCL Launch Liberty application

An application is the collection of the components needed for automated deployment. Artifacts are the application files need for installation and components encapsulate the artifacts needed to install an application.

Create the Liberty application on the HCL Launch dashboard:

  1. From the Applications tab, click Create Application > New Application and give the application a name, such as Liberty Profile Application.
  2. Any properties that can be referenced across multiple component designs can optionally be added to the application property section. Add the following properties:
    • liberty_directory, which resolves to the Liberty profile installation directory.
    • liberty_jar_name, which resolves to the name of the installation JAR file.
    • liberty_profile_directory, which resolves to the location of the Liberty profile server directory.
    • liberty_serverName, which resolves to the name of the Liberty profile server.
    • liberty_root, which resolves to the Liberty profile installation root directory.

Most of the properties used in the Liberty component process design are defined under Liberty Profile Application > Configuration > Application Properties. The same property can have different values by doing a re-declaration at the component, environment, and/or resource level. The property value is resolved based on object precedence.

There are exceptions: for example; properties referenced in the component ‘basic setting’ panel did not resolve when only declared in the application property section.  I added the following property in the component properties section.

  • liberty_install_resp, which resolves to the installation location of Liberty Repository.

See Properties in the Information Center.

You have now created an application called Liberty Profile Application. In the next section, create a component in the application called Liberty Component.

2. Creating an HCL Launch Liberty component

A component is the primary container for artifacts needed for the installation of the application. In this article, the Liberty Profile Installation file is the artifact.

  1. Click Create New Component and name the component Liberty Component.
  2. Set Source Config Type to File System (Versioned). This is where the HCL Launch retrieves the artifacts from. Other sources such as Subversion and Maven are also supported.
  3. In the Base Path field, type the name of the liberty_install_resp. This field does not auto-complete so ensure that you enter the name in the correct format (see Using properties).
  4. Check the Import Versions Automatically option. This makes HCL Launch poll for new artifact versions to manage.
  5. Check the Copy to CodeStation. This imports artifacts into the CodeStation. The amount of data in CodeStation can become an issue so you can configure the lifecycle of artifacts in CodeStation in the Settings view.
  6. Select the Use the system’s default version import agent/tag option to trigger the application processes using the system default agent/tag.

You have now created a component for the Liberty Profile Installation file by filling in the basic component information. Next, you must create the set of component processes needed to act on the Liberty Profile artifact.

3. Creating the component process

Create a process for the component Liberty Component.

  1. Click Create Process from the Processes tab and name the process as Liberty Profile Install.
  2. Set the Process Type to Deployment and the Inventory Status to Active.
  3. During deployment automation execution, the target system’s local HCL Launch agent creates a default working directory with the component name. The target system’s local agent will download and store the component artifact in this default directory. By default, HCL Launch sets a server property as a reference to the component’s Default Working Directory value. You can reference the same server property in your process design. Notice the Default Working Directory field is set by default.

You have now created the component process.

4. Creating the process design

We will now create the Liberty Profile Install process design for the Liberty Profile component with the following steps:

  1. Stop the previously running Liberty Profile.
  2. Delete the previous Liberty Profile installation.
  3. Download the Liberty Install artifact to a component default working directory on the target system.
  4. Install Liberty profile.
  5. Create the Liberty profile server.

TIP: Create component processes as though the target systems already have an active deployment; in this example, Liberty Profile. Processing optionally continues past steps 1 and 2 if the server is not running or installed.

All of the following steps for the process design are available in the IBM WebSphere Liberty plug-in. You just need to add them to the design and configure certain settings.

  1. Add the Liberty Profile Stop Server step to the process design.
    • In the Server Name field, type the name of the application property liberty_serverName. Manage component and application properties from the Configuration panel (see also Using properties).
    • In the WebSphere Liberty Installation Directory field, type the name of the application property liberty_root.
    • Leave the Working Directory field empty; it defaults to previously discussed Default Working Directory. HCL Launch creates a working directory with the name of the component. You can optionally reference the component’s default working directory as ${p:resource/work.dir}/${p:component.name}.
  2. Add the Liberty Profile Delete Files and Directories step to the process design.
    • Set Working Directory to the installed Liberty server location.
    • Set Base Directory to the current working directory.
      When you change the working directory path, remember to review the Base Directory and Working Directory values. The base directory value is appended to the working directory value during process execution.
  3. Add the Download Artifacts step to the process design. Accept the default settings of this design step.
  4. Add the Liberty Profile Install Server Archive step to the process design.
    Reference the application properties liberty_serverName and liberty_root again in this step.
  5. Add the Liberty Profile Create Server step to the process design.

Define other Liberty Profile component processes to be used with Liberty Profile application processes. The Liberty plug-in is used in designing the following component processes:

Component Process Design: Uninstall Liberty Server

Both steps use the Liberty plug-in support.

Component Process Design: Start Liberty Server

Component Process Design: Stop Liberty Server

The Liberty Profile Stop Server step uses Liberty plug-in support.

5. Integrating the component into the Liberty Profile application

With the Liberty Profile component processes created, associate the component with the Liberty Profile application. In the application, click Add Component and select the component name.

6. Creating resources for the Liberty Profile application

Resources are generally the HCL Launch application deployment targets; a server, for example. Any systems with HCL Launch agents installed will show up in the Resources > Agents panel of the administration dashboard. Include agents in new or existing top-level group declarations to make them available for application deployments.

  1. Create a top-level group called Liberty Windows Group.
  2. Add any target deployment system agents to the group. For the component processes to run, the component needs to be registered with the system agent.
  3. Add the component to an agent in the Resource view.

7. Creating an application environment

  1. With the resources in place, create an application environment for Liberty Profile.
  2. To complete creating the environment, add a top-level group resource.

8. Creating processes for the Liberty Profile application

With component, resource, and environment declared, the Liberty Profile application needs processes to manage the component process execution.

Create an application process:

  1. Click Create New Process.
  2. Name the process Liberty Profile Install.
  3. In the Inventory Management field, select Automatic.
  4. In the Offline Agent Handling field, select Check Before Execution.
  5. Add a Liberty Profile component > Liberty Profile Install step to the new application process design.
  6. Add a Liberty Profile component  > Liberty Profile Start Server step to the application process design.
  7. Organize the application process design steps as follows:
  8. Make sure that before doing a full deployment, test component processes. Access the Component page of the application, click Run Process, then click Submit to run the component process.

9. Running the deployment process

You’re now ready to run the deployment automation:

  1. Click the Request Process button next to the Environment definition to start the deployment.
  2. Clear the Only Changed Versions check box to force the overlay of previous deployments. This is useful for deployment automation testing.

The submitted process automation displays in an execution panel. The process request starts and completes a single Liberty deployment.

If you want to deploy across more servers, add additional agents to a new or existing top-level group resource. Applications deploy across multiple resources by adding them to an existing or new environment. Creating additional HCL Launch environments is another way to group systems and control deployments because environments are a specified option in running the application process.

In Part 2, we install a simple server application with the Liberty deployment.

 

Article: Deploying Liberty (Part 2)

Part 1 described how to set up a single Liberty server deployment using HCL Launch. In this article, we use the Liberty Profile application deployment from Part 1, and expand it to include a sample installation. Part 2 walks through adding updates to the Liberty Profile component to install a snoop application on a Liberty server.

1. Creating the Snoop component

This article uses a Snoop application as an example. You can use any simple application in place of Snoop.

The Snoop installation will go in a new HCL Launch component. The component declaration for the Snoop installation is similar to the Liberty Profile component that we created in Part 1. The difference for the new component declaration is the artifact is the Snoop WAR file.

  1. Click Create New Component.
  2. Enter the details for the new component for the Snoop application:
    • Name: Snoop Application
    • Source Config Type: File System (Versioned)
    • Base Path: ${p:snoop_rep}
  3. Add an install process to the Snoop Application component:
    • Name: Install Snoop Application
    • Process Type: Deployment
    • Inventory Status: Active
    • Default Working Directory: ${p:resource/work.dir}/${p:component.name}

The “Download Snoop Artifact” step of the “Install Snoop Application” process for the  “Snoop Application” component is similar to the Liberty Profile > Process > Liberty Profile Install > Download Artifact step. The snoop.war file is downloaded to the local system in a working directory.

This step is also supported through the Liberty plug-in. The “Install or Update Snoop Applications via Dropins” step of this Install Snoop Application process uses the liberty_serverName and liberty_root application properties defined under the Liberty Profile application. The same properties were also used in the Liberty Profile component.

2. Updating the Liberty Profile component

Create Liberty Profile component processes to start and stop a Liberty server:

  1. Go to Components > Liberty Profile > Processes > New Process:

    The Process Type field is set to Operational (No Version Needed) since this process runs a server command.
  2. Use the Shell plug-in to start the Liberty server. Edit the Shell plug-in properties.
  3. The Liberty Profile Start Server process is now created.

    • The Working Directory and Shell Script fields use properties declared at the Liberty Profile application level.
    • The Daemon option is enabled to allow step processing to continue. Tests without Daemon enabled caused processing to stop until the Liberty server shutdown has completed.
  4. Create Liberty Profile Stop Server process. The Liberty Profile Stop Server and Start Server process setups are similar.
    The “Stop Server”  design setup uses the “Stop Server” support of the Liberty plug-in. Values for the Liberty Server Name and  WebSphere Liberty Installation Directory root are required. Both fields use properties declared at the Liberty Profile application level (Liberty Profile Start Server > Design > Liberty Profile Stop Server):

 

3. Configuring environment properties

Declare component environment properties to update a template server.xml file and then add it to the Liberty Profile installation JAR file location. You then download both the install JAR file and the server.xml file as HCL Launch artifacts.

  1. Update the template server.xml file with tokens:
    The default HCL Launch token characters ('@') enclose the environment variables added in the server.xml file. In this example,  liberty_hostnameliberty_httpPort, and liberty_shttpPort are the tokens.
  2. Declare the same environment properties in the Liberty Profile component > configuration > Environment Property Definitions panel:
    The value for liberty_hostname is set  to the agent system property agent.name. By default, agent.name is set to the system host name declared during agent installation. All the tokens in the server.xml file will be resolved during process execution with a call to the “replace token” process plug-in.
  3. Add a process to the Liberty Profile component to download the server.xml artifact and do the token replace.

    The Update liberty server.xml hostname & ports process is created. Create the process as follows:

    • Create the first step; Download Artifacts:

      The Includes field is set to only download the server.xml to a local working directory.
    • Create the second step; Replace Tokens:

      Accept all the default settings in this step.
    • Create the third step; Copy Directory:

When Update liberty server.xml hostname & ports runs during deployment,  the updated server.xml file will look like this:

example2_20

4. Updating the agent resource

Add the Snoop Application component to the Liberty Profile application, and update the agent resource for the Liberty Profile application to allow the ‘Snoop’ component processes to run.

  1. Update the Liberty Profile application by adding the Snoop App component.
  2. Update the agent resource by adding the Snoop Application component to it.

5. Updating the Liberty Profile application

Create a process in the Liberty Profile application to include the Snoop Application component during a Liberty server installation:

  1. Go to Home > Liberty Profile Application > Processes and create Liberty Profile Install + Snoop Install process.
    • The Liberty Profile Install step is the same as previously defined.
    • In the second step, add the Install Component plug-in. The step calls the Liberty Profile component process that handles the server.xml template environment property token resolution:
    • In the third step, add another Install Component plug-in. The Install Snoop step calls the Snoop Application component > Install Snoop Application process.
    • The fourth step, Start the Liberty Server, which runs after installation, uses the component process.

The setup is now complete for the Liberty Profile application > Liberty Profile Install + Snoop Install deployment process.

6. Running the Liberty Profile Install + Snoop Install

To run the deployment process:

  1. Click Run Process.
  2. View the execution panel to check progress.
  3. Verify the deployment on the local system in the Liberty logs.
    • console.log:

      Starting Liberty with snoop.

    • Messages.log:example2_31

You can also access Snoop on the Liberty server in a browser:

example2_32

Troubleshooting

If, when importing artifacts into the code station, the thread that handles artifact copying hangs on previously queued requests, locate the hung request and cancel it. Running version requests appear under the component panels.

 

You can reduce the chance of a hung “component>version“` request by limiting the enabling of automatic imports.