Deploying solution and agent archives

You can deploy a solution or an agent to a container or development server by running the solutionManager script with the deploy command. The command copies the solution or agent to the server and updates the server.xml file to deploy the solution feature, or the agent, on the Liberty server.

About this task

You can run the solutionManager script with the local parameter or with the remote parameter. If you run the script with the local parameter, it modifies files on the local system. Using the local parameter, you can run the script with the Liberty server started or stopped. If the server is stopped when you deploy an archive, the solution or agent is taken into account when the server starts.

If you run the script with the remote parameter, it establishes an HTTP connection to a running Liberty server on the remote host. You must provide administrator authentication credentials to run the script. For information about administrator authentication in a Liberty profile, see the WebSphere® Application Server documentation.

When you make a major change to a solution, such as an update to the business object model (BOM), the previous and current solution versions become incompatible. You must deploy a new solution version to update all the required solution artifacts and clear all of the entities in the system. You do not need to deploy a complete update of the solution in the following cases:

A change to the BOM does not cause conflict between the previous and the current solution versions.
No update to the BOM.
An agent-only modification that updates one or more agents. In this situation, you can export and deploy only the updated agent. See Exporting agent updates.

In a topology where multiple servers are hosted on the same computer, you deploy a solution to one container server and then deploy the same solution to the other container servers by using the activateOnly=true parameter with the solutionManager deploy command. This parameter ensures that the server.xml file is updated, without attempting to redeploy the solution archives. Another use of the activateOnly parameter is when you undeploy a solution version and you then want to deploy it again. The undeploy command does not delete the archives from the host.

In a production topology with multiple servers, the solutionAutoStart property in the server.xml files is set to false. This auto-start property places a new version of a deployed solution on hold so that you can deploy the new solution version on all the container servers in the topology before you make it active by running the activate command. You only need to run solutionManager activate on one container server. The system propagates the solution activation to all the other container servers.

The copyOnly parameter is seldom used but it is useful in certain situations, for example, if you accidentally delete the solution archives and you want to deploy them again.

Use one of the following procedures to run the solutionManager deploy command, depending on whether the Liberty server is running on a Windows system or a Linux system. Run the script from the <InstallDir>/runtime/ia/bin directory, or make sure that this directory is included in the system path.

Procedure

Run the command on Windows with the local parameter or with the remote parameter, and provide extra parameter values that are relevant to your deployment scenario.

solutionManager deploy local C:\solution.esa --server=cisDev

solutionManager deploy remote C:\solution.esa --host=someRemoteHost --port=9080 --username=user1 --password=user1 --trustStoreLocation=C:\IBM\ODMInsights88\runtime\wlp\usr\servers\cisDev\resources\security\key.jks --trustStorePassword=truststore

Run the script on Linux with the local parameter or with the remote parameter, and provide extra parameter values that are relevant to your deployment scenario.

./solutionManager deploy local /opt/ibm/ODMInsights88/solution.esa --server=cisContainer

./solutionManager deploy remote /opt/ibm/ODMInsights88/solution.esa --host=someRemoteHost --port=9080 --username=user1 --password=user1 --trustStoreLocation=/opt/ibm/ODMInsights88/runtime/wlp/usr/servers/cisContainer/resources/security/key.jks --trustStorePassword=truststore

Optional: Deploy an updated solution agent without deploying the entire solution. If you modify or update one or more agents, but do not change the BOM, then you can export and deploy only the updated agent.
```
solutionManager deploy local C:\MyCreditCardSolution-0.6-CreditCardRules-0.6.2.esa --server=cisDev
```
Where MyCreditCardSolution-0.6 is the solution name and version, and CreditCardRules-0.6.2.esa is the updated agent archive.

Results

The solution is deployed to the <InstallDir>/runtime/wlp/usr/extension/lib directory. The solution manifest file is copied to a product extension directory named <InstallDir>/runtime/wlp/usr/extension/lib/features.

Restriction: All solution features must be referenced directly with a <feature> element in the server.xml file, not indirectly through an <include> element that points to an included file.

If the deploy command fails and displays an error because the solution was previously deployed but not activated, you can rerun the command with the activateOverride parameter to force the deployment of the solution. This error occurs when there are two servers in the same profile, and the solution is deployed and activated on one server, but not activated on the other server. In this situation, the solution files are installed at the profile level and the activation of the solutions at the server level is out of sync.

What to do next

Complete the following steps if you are upgrading or deploying a new version of a solution to a production topology.

Deploy the new version to all of the container servers in your topology.
When you are ready to start the new version, run the solutionManager activate command to set the upgraded solution version as the current version.

Note: The version of the solution with the highest version number is set as the current version.