Configuring Liberty provisionable clusters in Docker containers or Node.js servers

You can configure a collective to support autonomic deployments of a Liberty server in a Docker container or a Node.js server. The scaling controller can install Liberty software onto a registered host and create a new server. Also, the scaling controller can start or stop deployed servers based on resource use and optional scaling policies. The number of available servers grows when application demand is high and shrinks when application demand is low.

Before you begin

Stabilized feature: Managing Node.js processes by using Liberty collectives is stabilized. V8 is the final supported Node.js version for Liberty collective members. For on-premises or bring-your-own infrastructure environments, use Docker containers that are hosted and managed by IBM Cloud® Private. For hosted environments, use Docker containers in IBM Cloud Kubernetes Service.

Procedure

Complete the steps in Configuring auto-scalable clusters for JVM elasticity.
Ensure that an existing dynamic cluster member belongs to the cluster name that will be used in the package_name.deploy.xml file to be placed in the stackGroups directory structure.

This cluster member must be the same type of member that will be deployed as defined in the package_name.deploy.xml file. For example, if the stack will be Docker, then there must be a Liberty Docker member.

package_name is the name of the server package that the scaling controller will provision to target hosts. For more information about the package, see step 5.
Optional: Add scaling policies to the scaling controller. See Defining scaling policies.
Register each target host with a scaling controller.
Registering a host enables the scaling controller to transfer files to that host, as well as access files, commands, and other resources on the host. Use the registerHost command to register a target host. Look at the server.xml file of the scaling controller to find the values for the --host, --port, --user, and --password parameters. To not use an SSH private key file, such as for target hosts on Linux® or Windows operating systems, include an operating system login user and password by setting --rpcUser and --rpcUserPassword parameters. The user specified by --rpcUser must have operating system rights to the target deployment location.
```
wlp/bin/collective registerHost targetHost --host=controllerHost --port=controllerHTTPSPort --user=controllerAdmin --password=controllerAdminPassword --rpcUser=osUser --rpcUserPassword=osUserPassword
```
If a host is already registered, you can use the updateHost command to reset registration information. If the target host is on the same computer as the controller host, you must also run the updateHost command for the controller host. For more information, see Registering host computers with a Liberty collective.
Create a file named package_name.deploy.xml that configures deployment rules for a DeployService deploy operation.
You can add name/value pairs that set values for Deploy Rule input variables.
```
<deploy>
   <useRule id="rule_ID" />
   <variable name="aName" value="aValue" />
   ...
</deploy>
```
For rule_ID, specify the id value of a deploy rule provided by Liberty or specify an id value for your own deploy rule. This package_name.deploy.xml file goes in the stack group packages directory (step 7).

For variable names and values, use inputVariables defined in the deploy rule.

For Node.js servers, see information about the application .tgz contents and location at step 2 in Deploying Node.js servers using deployment REST APIs.
Set a user name and password for the collective controller in the scaling controller server.xml file.
```
<collectiveController user="adminUser" password="adminPassword" />
```
Place the package_name.deploy.xml file in the WLP_STACK_GROUPS_DIR location, which by default is $WLP_USER_DIR/shared/stackGroups.
Scaling controllers monitor the default package location in the file system and dynamically react to updates. If you place the file in the default location, you do not need to change any of the default attributes.

You can use the default stack group, defaultStackGroup. Or you can create your own subdirectory of stackGroups, such as myStackGroup, and add to it the packages subdirectory.
```
wlp/usr
      /servers
      /shared
         ...
         /stackGroups
            /defaultStackGroup
               /installables
               /packages
            /myStackGroup
               /packages
```
The scaling controller uses the file to create a new server on a registered host.
Tip: A new server is created only if the scaling policy is enabled and requires a new server. To force a scaling controller to create a new server, adjust the min value and possibly the max value of the scaling policy for the scaling controller. For example, if your scaling controller does not have a scaling policy and your collective has three scaling members, add to the scaling controller server.xml file a policy that forces the scaling controller to have at least four running members:
```
<scalingDefinitions>
   <defaultScalingPolicy enabled="true" min="4" max="6"/>
</scalingDefinitions>
```
The cluster naming convention for Liberty elasticity is StackGroupName.PackageName. When a stack is deployed, <clusterMember name="StackGroupname.PackageName" is automatically set in the server.xml file of the deployed server. The corresponding <scalingPolicy> element includes a <bind clusters="StackGroupName.Packagename"/> statement. However, the deploy rules provided by Liberty for Docker and Node.js allow you to set clusterName to any value.
Examine the deploy variables and revise them as needed for your environment.

The deployVariable child element specifies a substitution variable which gets injected into the deployed stack. You can specify that the substitution variable automatically increment each time the stack is deployed. For example, use a deployVariable attribute to specify an initial port number value and increment the value each deployment. The purpose of deployVariable in this situation is to avoid port conflicts on the target host.

Set the deploy variables for a Docker image as described in step 1c of Deploying Docker containers using deployment REST APIs.

Set the deploy variables for a Node.js server deployment as described in step 3 of Deploying Node.js servers using deployment REST APIs.
Optional: Change the interval at which the scaling controller checks the file system for stack group additions, updates, and deletions.
The scaling controller scans the contents of the stackGroups directory and its subdirectories for changes. Content changes can cause the controller to provision clusters that previously did not have packages available. Updating packages does not cause the controller to provision existing clusters again.

By default, the controller scans the WLP_STACK_GROUPS_DIR location every 5000 milliseconds (five seconds). To change the scanning interval or disable scanning, set new values for the stack manager attributes scanningInterval and scanningEnable in the scaling controller server.xml file. For example, to set the scanning interval to six seconds and enable scanning, add a statement resembling the following to the scaling controller server.xml file:
```
<stackManager groupsDir="${wlp.install.dir}/usr/shared/stackGroups/"
              controllerUser="adminUser" controllerUserPassword="adminPassword"
              scanningInterval="6000" scanningEnable="true">
</stackManager>
```
To disable scanning, set scanningEnable to false.
Optional: Instruct the scaling controller to scan the file system for new stack group additions, updates, and deletions.

Run a StackManager MBean operation to force the scaling controller to check the WLP_STACK_GROUPS_DIR location for stack group additions, updates, and deletions. Even if the scaling controller server.xml file has scanningEnable="false", you can run a StackManager MBean operation to force a scanning for additions, updates, and deletions.

See List of provided MBeans for information about the StackManager MBean.
Optional: Start IHS to enable routing to servers.

For IBM HTTP Server (IHS) to discover and route to web applications on dynamically provisioned clusters, enable dynamic routing on the host where the scaling controller will reside. IHS will retrieve the routing information for the provisioned servers from the dynamic routing service. If server status is enabled, you can view the routing information.

If you do not have IHS installed, see Setting up dynamic routing for Liberty collectives. Also, the following video demonstrates how to install support for dynamic routing using IBM Installation Manager:

Watch: The Enabling IHS for Liberty Dynamic Routing video shows how to install IHS, install Web Server Plug-in for WebSphere Application Server, and apply the interim fix for Dynamic Routing. [Transcript]