Deploying Liberty servers using deployment REST APIs

You can deploy Liberty servers as members of a collective using the DeployService REST APIs.

Before you begin

Create and package a Liberty server to deploy.

If you do not have an existing server to package, run the create command to create a new server.
```
./server create member1
```
If you have an existing server to package, ensure the server that you want to package is stopped.
Run the package command to create the server package.
```
./server package member1
```
The command creates a server package named, for example, member1.zip. The zip file should include a Liberty runtime, which a "collective join" operation needs and an expected path in the package for a deploying the Liberty server, like /wlp/usr/servers.

Ensure the target host is set up for Remote Execution Agent (RXA). See Setting up RXA for Liberty collective operations.

Also ensure the target host has the cURL utility, an unzip utility, and Java support for the jar utility in the environment (path) of a user that has operating system rights to the target deployment location. This user must be the same user specified for --rpcUser, a Remote Procedure Call (RPC) user, during registration of the host. You register a host in step 3.

Procedure

Add a collectiveController statement to the controller server.xml file. Set the user and password values to the controller administrative user ID and password. For example, use the values that are in the <quickStartSecurity userName="admin" userPassword="adminpwd" /> statement in the controller server.xml file.
```
<collectiveController user="admin" password="adminpwd" />
```

Review the available deployment rules.

Invoke a REST API that returns the available deployment rules in JSON structure.

Use a tool that can invoke REST APIs to get the available deployment rules.

GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/rule

The invocation returns the deployment rules in JSON structure:

{
-"id": "Liberty Server Rule",
-"description": "Deploy rule for Liberty servers.",
-"type": "Liberty",
-"deployCommands": "curl -X GET https://${wlp.admin.host}:${wlp.admin.port}/IBMJMXConnectorREST/file/${serverPackageDir}%2F${serverPackage} --user ${wlp.admin.user}:${wlp.admin.password} -k --create-dirs -o ${targetDir}/${serverPackage}.tmp --verbose && unzip ${targetDir}/${serverPackage}.tmp -d ${targetDir}/${serverPackage} && ${targetDir}/${serverPackage}/${binDir}/collective join ${serverName} --host=${wlp.admin.host} --port=${wlp.admin.port} --user=${wlp.admin.user} --password=${wlp.admin.password} --keystorePassword=${keystorePassword} --hostName=${wlp.deploy.host} --useHostCredentials --createConfigFile=${targetDir}/${serverPackage}/wlp/usr/servers/${serverName}/configDropins/defaults/additionalConfig.xml --autoAcceptCertificates",
-"undeployCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName}; ${targetDir}/${serverPackage}/${binDir}/collective remove ${serverName} --host=${wlp.admin.host} --port=${wlp.admin.port} --user=${wlp.admin.user} --password=${wlp.admin.password} --autoAcceptCertificates --hostName=${wlp.deploy.host}",
-"startCommands": "${targetDir}/${serverPackage}/${binDir}/server start ${serverName}",
-"stopCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName}",
-"restartCommands": "${targetDir}/${serverPackage}/${binDir}/server stop ${serverName} && ${targetDir}/${serverPackage}/${binDir}/server start ${serverName}",
-"inputVariables": [
-{
-"name": "targetDir",
-"type": "filePath",
-"description": "The target directory for the Liberty server package to be installed.",
-"displayName": "Target Directory"},
-{
-"name": "keystorePassword",
-"type": "password",
-"description": "Password for keystores of the deployed server",
-"displayName": "Keystore Password"},
-{
-"name": "serverPackage",
-"type": "file",
-"description": "Name of the Liberty server package to install.",
-"displayName": "Server Package File"},
-{
-"name": "serverPackageDir",
-"type": "filePath",
-"description": "Location of directory on the controller containing the server package to deploy.",
-"displayName": "Package directory"}],
-"name": "Liberty Server",
-"default": true,
-"runtimeTypes": [
-{
-"displayName": "Liberty"}],
-"packageType": "Server Package"}

If necessary, create your own deployment rules by adding DeployRules to your controller configuration. See Deploy Rule (deployRule).
Make the server package available to the controller.
Complete either of the following actions:
- Put the server package in one of the default readDir directories, which include ${wlp.install.dir}, ${wlp.user.dir}, and ${server.output.dir}, or in a subdirectory of a default readDir directory.
- Add to the controller server.xml file a remoteFileAccess statement that points to the location of the server package. The first readDir statement provides the location of the server package. This directory is the serverPackageDir input variable that is specified for the deployService deployment in step 4. The serverPackageDir directory is on the controller host. The next three readDir statements re-enable the default readDir directories; for example:
```
<remoteFileAccess>
   <readDir>/tmp/serverPackageDir</readDir>
   
   <readDir>${wlp.install.dir</readDir>
   <readDir>${wlp.user.dir}</readDir>
   <readDir>${server.output.dir}</readDir>
</remoteFileAccess>
```

Register the host on which you want to install a Liberty server with the collective controller.
Registering a host enables the collective controller to access files, commands, and other resources on the host. Use the registerHost command to register the target host. If a host is already registered, you can use the updateHost command to reset registration information.

Important: Ensure you run the collective registerHost or updateHost command as the user that you will later use to deploy the member server. For example, if you run the command as the root user and then later deploy a member as a different user, the deployment fails because DeployService does not have rights to push a file to the /root/wlp directory.
```
collective registerHost targetHost --host=controllerHost --port=controllerHTTPSPort 
--user=controllerAdmin --password=controllerAdminPassword --rpcUser=osUser --rpcUserPassword=osUserPassword --autoAcceptCertificates --hostWritePath=targetDir
```
- --host, --port, --user, and --password are required. To find the values for these parameters, look at the server.xml file of the controller.
- If the remote target host does not support SSH or you do not want to use SSH keys, such as for target hosts on Linux® or Windows operating systems, --rpcUser and --rpcUserPassword are required. Set --rpcUser to an operating system login user and set --rpcUserPassword to the password. The user specified by --rpcUser must have operating system rights to the target deployment location.
- --autoAcceptCertificates is required.
- --hostWritePath=directory is required. The directory value for --hostWritePath must be the targetDir specified in the deployment rules, or a parent directory of the targetDir on the host on which you want to install a Liberty server. You can specify more than one --hostWritePath parameter; for example: --hostWritePath=/dir1 --hostWritePath=/dir2
For more information about the registerHost and updateHost commands, see Registering host computers with a Liberty collective.
Deploy the Liberty server.
Use a tool that can invoke REST APIs to deploy the Liberty server. The deployment rule contains variables that can specify input values for the invocation, such as the Liberty server to use. The return body contains a token that you can use to request status and results.
```
POST https://controller_host:controller_port/ibm/api/collective/v1/deployment/deploy

{
   "rule":"Liberty Server Rule",
   "hosts":["target_host_name"],
   "variables": [
      { "name":"serverPackage","value":"member.zip" },
      { "name":"targetDir","value":"%2Fhome%2FmyHome%2Fdeploy" },
      { "name":"keystorePassword","value":"password" },
      { "name":"serverPackageDir","value":"%2Fusr%2Ftest%2Fsource" }
   ]
}
```
Attention: The targetDir and serverPackageDir variables are UTF-8 encoded directory paths. The serverPackageDir variable is the location of the Liberty server package ZIP file on the collective controller.
Use the return token, which might resemble {"id":3}, to get status and results. You can get the output in JSON format.

What to do next

Request and review the deployment status and results.

Get a list of deployment tokens for requested deployment operations.

GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/deploy

Get a short status of the deployment operations. Use the token from step 6 for {token}. Thus, for a {"id":3} return token from step 6, use 3 for {token}.
```
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/{token}/status 
```
During deployment, the API returns IN_PROGRESS:
```
{"status":{"target_host":"IN_PROGRESS"}}
```
After deployment, the API returns FINISHED:
```
{"status":{"target_host":"FINISHED"}}
```
You can also get a final status of ERROR if the deployment has problems. Use the following information to get the complete results. The stdout and stderr information that is returned can help you diagnose the problems.

Get the complete results of a deployment operation. Use the token from step 6 for {token}. Thus, for a {"id":3} return token from step 6, use 3 for {token}.

GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/{token}/results

After deployment completes, the results contain information about the operation. The following example shows results for FINISHED:

{"results":[{"host_name":"target_host","status":"FINISHED","result":0,"stdout":"deployment_stdout", "stderr":"deployment_stderr", "deployedArtifactName":"serverName_from_inputVars", "deployedUserDir":"target_host_directory_for_deployed_server"}]}

Undeploy the Liberty server. You do not need to specify a deploy rule. The rule that is used for deployment was stored at deploy time. You can use the rule for undeployment. The server tuple of host name, user directory, and server name is used to undeploy the server. This tuple is shown on server pages in the Explore tool of Admin Center.

Undeploy a Liberty server.


POST https://controller_host:controller_port/ibm/api/collective/v1/deployment/undeploy
{     
   "host": "myHostName",
   "userDir":"myUserDir",     
   "serverName":"myServerName"
}

Get a list of tokens for undeployment operations.
```
GET https://controller_host:controller_port/ibm/api/collective/v1/deployment/undeploy
```
To get status and results, follow steps similar to deployments.