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 Server
• Delete Server
• Generate Component-Resource Properties
• Generate Plugin Config
• Install Server Archive
• Install or Update Application with Server XML
• Install or Update Applications with Dropins
• Join Collective
• Merge Plugin Config
• Propagate Plugin Config
• Register Host
• Replace Variable Values with Component-Resource Properties
• Start Application
• Start Server
• Stop Application
• Stop Server
• Uninstall Application from Dropins
• Uninstall Application with Server XML
• Unregister Host
• Update Host
• Upload File To Collective Host
• Wait for Application to be STARTED

Create Collective

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

Create Server

Create a server in the WebSphere Liberty profile.

Delete Server

Delete a server in the WebSphere Liberty profile.

Generate Component-Resource Properties

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

Generate Plugin Config

Generate plugin configuration for a WebSphere Liberty server.

Install Server Archive

Install a WebSphere Liberty archive file.

Install or Update Application with Server XML

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

Install or Update Applications with Dropins

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

Join Collective

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

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.

Propagate Plugin Config

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

Register Host

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

Replace Variable Values with Component-Resource Properties

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

Start Application

Start an application in the WebSphere Liberty profile.

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.

Stop Application

Stop an application in the WebSphere Liberty profile.

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.

Uninstall Application from Dropins

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

Uninstall Application with Server XML

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

Unregister Host

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

Update Host

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

Upload File To Collective Host

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

Wait for Application to be STARTED

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

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_hostname, liberty_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:

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:

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

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.