Deploying solution and agent archives

You can deploy a solution or an agent to a runtime 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 that impacts compatibility with a previous version, such as an update to the business object model (BOM), you must deploy a new solution version to update all the required solution artifacts and clear all of the entities in the system. For more information about the elements that you can modify in your BOM between two solution versions, see Restrictions on BOM changes between solution versions. 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 runtime server and then deploy the same solution to the other runtime servers by using the enableOnly=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 enableOnly 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 second or greater solution version on all the runtime servers in the topology before you make it active by running the activate command. You need only to run the solutionManager activate command on one runtime server. The system propagates the solution activation to all the other runtime 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.
The server parameter is only necessary if the ia/etc/connection.properties file does not set the intended server name. The default server name is cisDev. You can overwrite the connection.properties file by using the propertiesFile parameter from which to read properties.

A remote deploy command does not require a server name. It uses the host and port to connect to the remote server over HTTP.
```
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\ODMInsights881\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/ODMInsights881/solution.esa --server=cisContainer

./solutionManager deploy remote /opt/ibm/ODMInsights881/solution.esa --host=someRemoteHost --port=9080 --username=user1 --password=user1 --trustStoreLocation=/opt/ibm/ODMInsights881/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 <WLP_USER_DIR>/extension/lib directory. The solution manifest file is copied to an extension directory named <WLP_USER_DIR>/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

If you are upgrading or deploying a new version of a solution to a production topology, complete the following steps:

Deploy the new version to all of the runtime 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.