SupportConsoleDevelopersStart a trialContact

Chapter 6. Managing application deployments

JBoss EAP features a range of application deployment and configuration options to cater to both administrators and developers. For administrators, the management console and the management CLI offer ideal graphical and command-line interfaces to manage application deployment in a production environment. For developers, the range of application deployment testing options include a configurable file system deployment scanner, the HTTP API, an IDE such as Red Hat CodeReady Studio, and Maven.

When deploying applications, you may want to enable validation for deployment descriptors by setting the org.jboss.metadata.parser.validate system property to true. This can be done one of the following ways:

  • While starting the server. 

    $ EAP_HOME/bin/standalone.sh -Dorg.jboss.metadata.parser.validate=true

  • By adding it to the server configuration with the following management CLI command. 

    /system-property=org.jboss.metadata.parser.validate:add(value=true)

6.1. Managing application deployment using the management CLI

Deploying applications using the management CLI gives you the benefit of a single command-line interface with the ability to create and run deployment scripts. You can use this scripting ability to configure specific application deployment and management scenarios. You can manage the deployments for a single server when running as a standalone server, or an entire network of servers when running in a managed domain.

6.1.1. Managing application deployments in a standalone server

6.1.1.1. Deploying an application to a standalone server using the management CLI

You can deploy an application a standalone server using the management CLI by using the deployment deploy-file command.

Prerequisites

  • JBoss EAP is running.

Procedure

  • Deploy an application packaged as a Web Archive (war) from the management CLI.

    Syntax

    deployment deploy-file <path_to_the_application>/<application_name>.war

    Example

    deployment deploy-file /my-applications/test-application.war

    A successful deployment does not produce any output to the management CLI, but the server log displays deployment messages such as the following output: 

    WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
WFLYUT0021: Registered web context: /test-application
WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

Similarly, you can use the following deployment commands:

  • Use the deployment deploy-cli-archive to deploy the content from a .cli archive file. A CLI deployment archive is a JAR file with the .cli extension. It contains application archives that should be deployed and the CLI script files, deploy.scr and undeploy.scr, containing commands and operations. One script file, deploy.scr, contains the commands and operations that deploy the application archives and set up the environment; the other script file, undeploy.scr, contains the commands to undeploy the application archives and clean up the environment.
  • Use the deployment deploy-url to deploy the content referenced by a URL.
Note

When specifying the runtime-name attribute by using the --runtime-name option, you must include the .war extension in the name or the web context will not be registered by JBoss EAP.

6.1.1.2. Undeploying an application from a standalone server using the management CLI

You can undeploy an application from a standalone server using the management CLI by using the deployment undeploy command. Undeploying an application deletes the deployment content from the repository. If you want to retain the deployment content when while making the application unavailable, you can disable the deployment instead. For more information, see Disabling an application in a standalone server using the management CLI.

Prerequisites

  • JBoss EAP is running.

Procedure

  • Undeploy an application by using the management CLI.

    Syntax

    deployment undeploy <deployment>

    Example

    deployment undeploy test-application.war

    A successful undeployment does not produce any output to the management CLI, but the server log displays undeployment messages like the following output: 

    WFLYUT0022: Unregistered web context: /test-application
WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 62ms
WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

Similarly, you can use the deployment undeploy-cli-archive to undeploy the content from a .cli archive file. You can also undeploy all deployments using a wildcard (*). 

deployment undeploy *

6.1.1.3. Disabling an application in a standalone server using the management CLI

You can disable a deployed application without removing the deployment content from the repository.

Prerequisites

  • JBoss EAP is running.

Procedure

  • You can disable a single application or all applications deployed to JBoss EAP by using the deployment disable command from the management CLI.

    • Disable a single deployment:

      Syntax

      deployment disable <deployment>

      Example

      deployment disable test-application.war

    • Disable all the deployments: 

      deployment disable-all

6.1.1.4. Enabling an application in a standalone server using the management CLI

You can enable a disabled application.

Prerequisites

  • JBoss EAP is running.

Procedure

  • You can enable a single application or all applications deployed to JBoss EAP by using the deployment enable command from the management CLI.

    • Enable a single deployment:

      Syntax

      deployment enable <deployment>

      Example

      deployment enable test-application.war

    • Enable all the deployments: 

      deployment enable-all

6.1.1.5. Listing deployments in a standalone server using the management CLI

You can list deployments in a standalone server and view deployment information such as the runtime name, status, and so on.

Prerequisites

  • JBoss EAP is running.

Procedure

  • Use the deployment info command to list deployment information. 

    deployment info

    The output will show details about each deployment, such as the runtime name, status, and whether it is enabled. 

    NAME                 RUNTIME-NAME         PERSISTENT ENABLED STATUS
helloworld.war       helloworld.war       true       true    OK
test-application.war test-application.war true       true    OK

    To display deployment information by name: 

    deployment info helloworld.war

You can also list all the deployments using the deployment list command.

6.1.2. Managing application deployments in a managed domain

6.1.2.1. Deploying an application to a managed domain using the management CLI

You can deploy an application a standalone server using the management CLI by using the deployment deploy-file command and specifying the server groups to which the application should be deployed.

Prerequisites

  • JBoss EAP is running as a managed domain.

Procedure

  • You can deploy an application packaged as a Web Archive (war) from the management CLI to specific server groups or all the server groups.

    • Deploy the application to specific server groups:

      Syntax

      deployment deploy-file <path_to_the_application>/<application_name>.war --server-groups=<server-group_1>,..., <server-group_1>

      Example

      deployment deploy-file /my-applications/test-application.war --server-groups=main-server-group,other-server-group

    • Deploy the application to all server groups:

      Syntax

      deployment deploy-file <path_to_the_application>/<application_name>.war --all-server-groups

      Example

      deployment deploy-file /my-applications/test-application.war --all-server-groups

      A successful deployment does not produce any output to the management CLI, but the server log displays deployment messages for each affected server. 

    [Server:server-one] WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
[Server:server-one] WFLYUT0021: Registered web context: /test-application
[Server:server-one] WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")

Similarly, you can use the following deployment commands:

  • Use the deployment deploy-cli-archive command to deploy the content from a .cli archive file. A CLI deployment archive is a JAR file with the .cli extension. It contains application archives that should be deployed and the CLI script files, deploy.scr and undeploy.scr, containing commands and operations. One script file, deploy.scr, contains the commands and operations that deploy the application archives and set up the environment; the other script file, undeploy.scr, contains the commands to undeploy the application archives and clean up the environment.
  • Use the deployment deploy-url command to deploy the content referenced by a URL.
Note

When specifying the runtime-name attribute by using the --runtime-name option, you must include the .war extension in the name or the web context will not be registered by JBoss EAP.

6.1.2.2. Undeploying an application from a managed domain using the management CLI

You can undeploy an application from JBoss EAP running as a managed domain using the management CLI by using the deployment undeploy command. Undeploying an application deletes the deployment content from the repository. If you want to retain the deployment content when while making the application unavailable, you can disable the deployment instead. For more information, see Disabling an application in a managed domain using the management CLI.

Prerequisites

  • JBoss EAP is running as a managed domain.

Procedure

  • Undeploy an application from all server groups with that deployment from the management CLI.

    Syntax

    deployment undeploy <application_name>.war --all-relevant-server-groups

    Example

    deployment undeploy test-application.war --all-relevant-server-groups

    A successful undeployment does not produce any output to the management CLI, but the server log displays undeployment messages for each affected server like the following output: 

[Server:server-one] WFLYUT0022: Unregistered web context: /test-application
[Server:server-one] WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 74ms
[Server:server-one] WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")

Similarly, you can use the deployment undeploy-cli-archive command to undeploy the content from a .cli archive file. You can also undeploy all deployments using a wildcard (*). 

deployment undeploy * --all-relevant-server-groups

6.1.2.3. Disabling an application in a managed domain using the management CLI

You can disable a deployed application from specific server groups and retain its content in the repository for other server groups with that deployment.

Prerequisites

  • JBoss EAP is running as a managed domain.

Procedure

  • You can disable a single application or all applications deployed to JBoss EAP by using the deployment disable command from the management CLI.

    • Disabe a single application:

      Syntax

      deployment disable <application_name>.war --server-groups=<server-group_1>,..., <server-group_1>

      Example

      deployment disable test-application.war --server-groups=other-server-group

    • Disable all the deployments:

      Syntax

      deployment disable-all --server-groups=<server-group_1>,..., <server-group_1>

      Example

      deployment disable-all --server-groups=other-server-group

6.1.2.4. Enabling an application in a managed domain using the management CLI

Enable a disabled deployed application.

Prerequisites

  • JBoss EAP is running as a managed domain.

Procedure

  • You can enable a single application or all applications deployed to JBoss EAP by using the deployment enable command from the management CLI.

    • Enable a single deployment:

      Syntax

      deployment enable <deployment> --server-groups=<server-group_1>,..., <server-group_1>

      Example

      deployment enable test-application.war --server-groups=other-server-group

    • Enable all the deployments: 

      deployment enable-all --server-groups=<server-group_1>,..., <server-group_1>

      Example

      deployment enable-all --server-groups=other-server-group

6.1.2.5. Listing deployments in a managed domain using the management CLI

You can list deployments and view deployment information such as the runtime name, status, and so on.

Prerequisites

  • JBoss EAP is running as a managed domain.

Procedure

  • Use the deployment info command to list deployment information. 

    deployment info helloworld.war

    The output will list the deployment and its state in each server group. 

    NAME               RUNTIME-NAME
helloworld.war     helloworld.war

SERVER-GROUP       STATE
main-server-group  enabled
other-server-group added

    To display deployment information by server group: 

    deployment info --server-group=other-server-group

    The output will list the deployments and their state for the specified server group. 

    NAME                 RUNTIME-NAME         STATE
helloworld.war       helloworld.war       added
test-application.war test-application.war enabled

You can also list all deployments in the domain using the deployment list command.

6.2. Managing application deployment using the management console

Deploying applications using the management console gives you the benefit of a graphical interface that is easy to use. You can see at a glance which applications are deployed to your server or server groups, and you can enable, disable or remove applications from the content repository as required.

6.2.1. Application deployment on a standalone server using the management console

Deployments can be viewed and managed from the Deployments tab of the JBoss EAP management console.

Deploy an Application

Click the Add (+) button. You can choose to deploy an application by uploading a deployment, adding an unmanaged deployment, or creating an empty deployment. Deployments are enabled by default.

  • Upload a deployment

    Upload an application that will be copied to the server’s content repository and managed by JBoss EAP.

  • Adding an unmanaged deployment

    Specify the location of a deployment. This deployment will not be copied to the server’s content repository and will not be managed by JBoss EAP.

  • Creating an empty deployment

    Create an empty, exploded deployment. You can add files to the deployment after it has been created.

Undeploy an Application

Select the deployment and choose the Undeploy option. JBoss EAP removes the deployment from the content repository.

Disable an Application

Select the deployment and choose the Disable option to disable the application. This undeploys the deployment, but does not remove it from the content repository.

Replace an Application

Select the deployment and choose the Replace option. Select the new version of the deployment, which must have the same name as the original, and click Finish. This undeploys and removes the original version of the deployment, and then deploys the new version.

6.2.2. Managing application deployment in a managed domain using the management console

From the Deployments tab of the JBoss EAP management console, deployments can be viewed and managed by:

  • Content Repository

    All managed and unmanaged deployments are listed in the Content Repository section. Deployments can be added and deployed to server groups here.

  • Server Groups

    Deployments that have been deployed to one or more server groups are listed in the Server Groups section. Deployments can be enabled and added directly to a server group here.

6.2.2.1. Adding an application to the content repository using the management console

You can add an application to the content repository using the management console.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.

Procedure

  1. Log in to the management console.

    By default the management console is available on http://localhost:9990.

  2. From Content Repository, click the Add button.
  3. Choose to add an application by uploading a deployment or adding an unmanaged deployment.

  4. Follow the prompts to deploy the application.

    Note that a deployment must be deployed to a server group before it can be enabled.

6.2.2.2. Deploying an application to a server group using the management console

You can deploy an application to a server group using the management console.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.
  • You have added the application to the content repository.

Procedure

  1. Log in to the management console.

    By default the management console is available on http://localhost:9990.

  2. From Content Repository, select a deployment and click the Deploy button.
  3. Select one or more server groups to which this deployment should be deployed.
  4. Optionally, select the option to enable the deployment on the selected server groups.

6.2.2.3. Undeploying an application from a server group using the management console

You can undeploy an application from a server group using the management console.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.

Procedure

  1. From Server Groups, select the appropriate server group.
  2. Select the desired deployment and click the Undeploy button.

Deployments can also be undeployed from multiple server groups at once by selecting the Undeploy button for the deployment in Content Repository.

6.2.2.4. Removing an application from a managed domain using the management console

You can remove an application from a managed domain using the management console.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.

Procedure

  1. If the deployment is still deployed to any server groups, be sure to undeploy the deployment.
  2. From Content Repository, select the deployment and click the Remove button.

This removes the deployment from the content repository.

6.2.2.5. Disabling an application in a managed domain using the management console

You can disable an application in a managed domain using the management console. Disabling an application only undeploys it from the server but does not remove it from the content repository.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.

Procedure

  1. From Server Groups, select the appropriate server group.
  2. Select the desired deployment and click the Disable button.

This undeploys the deployment, but does not remove it from the content repository.

6.2.2.6. Replacing an application in a managed domain using the management console

You can replace an application deployment with its newer version in a managed domain using the management console.

Prerequisites

  • JBoss EAP is running.
  • You have created a user in JBoss EAP.

Procedure

  1. From Content Repository, select the deployment and click the Replace button.
  2. Select the new version of the deployment, which must have the same name as the original, and click Replace.

This undeploys and removes the original version of the deployment, and then deploys the new version.

6.3. Application deployment using the deployment scanner

The deployment scanner monitors the deployment directory for applications to deploy. By default, the deployment scanner scans the EAP_HOME/standalone/deployments/ directory every five seconds for changes. Marker files are used to indicate the status of a deployment and to trigger actions against deployments, such as undeploying or redeploying.

While it is recommended to use the management console or management CLI for application deployment in a production environment, deploying using the deployment scanner is provided for the convenience of developers. This allows users to build and test applications in a manner suited for rapid development cycles. Additionally, the deployment scanner should not be used in conjunction with other deployment methods.

The deployment scanner is only available when running JBoss EAP as a standalone server.

6.3.1. Application deployment management in a standalone server using the deployment scanner

The deployment scanner can be configured to allow or disallow automatic deployment of XML, zipped, and exploded content. If automatic deployment is disabled, you must manually create marker files to trigger deployment actions. For more information about the available marker file types and their purposes, see the Deployment Scanner Marker Files section.

By default, automatic deployment for XML and zipped content is enabled. For details on configuring automatic deployment for each content type, see Configure the Deployment Scanner.

Warning

Deploying using the deployment scanner is provided for the convenience of developers and is not recommended for use in a production environment. It should also not be used in conjunction with other deployment methods.

Deploy an Application

Copy the content to the deployment folder. 

$ cp /path/to/test-application.war EAP_HOME/standalone/deployments/

If auto-deployment is enabled, this file will be picked up automatically, deployed, and a .deployed marker file will be created. If auto-deployment is not enabled, then you will need to manually add a .dodeploy marker file to trigger deployment. 

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy
Undeploy an Application

Trigger an undeployment by removing the .deployed marker file. 

$ rm EAP_HOME/standalone/deployments/test-application.war.deployed

If auto-deployment is enabled, you can also remove the test-application.war file, which will trigger the undeployment. Note that this does not apply for exploded deployments.

Redeploy an Application

Create a .dodeploy marker file to initiate redeployment. 

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy

6.3.2. Deployment scanner configuration

The deployment scanner can be configured using the management console or the management CLI. You can configure the deployment scanner’s behavior, such as the scan interval, deployment folder location, and autodeployment of certain application file types. You can also disable the deployment scanner entirely.

For details on all available deployment scanner attributes, see the Deployment Scanner Attributes section.

Use the below management CLI commands to configure the default deployment scanner.

Disable the Deployment Scanner
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)

This disables the default deployment scanner.

Change the Scan Interval
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-interval,value=10000)

This updates the scan interval time from 5000 milliseconds (five seconds) to 10000 milliseconds (ten seconds).

Change the Deployment Folder
/subsystem=deployment-scanner/scanner=default:write-attribute(name=path,value=/path/to/deployments)

This changes the location of the deployment folder from the default location of EAP_HOME/standalone/deployments to /path/to/deployments.

The path value will be treated as an absolute path unless the relative-to attribute is specified, in which case it will be relative to that path.

Enable the Automatic Deployment of Exploded Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-exploded,value=true)

This enables the automatic deployment of exploded content, which is disabled by default.

Disable the Automatic Deployment of Zipped Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-zipped,value=false)

This disables the automatic deployment of zipped content, which is enabled by default.

Disable the Automatic Deployment of XML Content
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-xml,value=false)

This disables the automatic deployment of XML content, which is enabled by default.

6.3.3. Custom deployment scanner

A new deployment scanner can be added using the management CLI or by navigating to the Deployment Scanners subsystem from the Configuration tab in the management console. This will define a new directory to scan for deployments. The default deployment scanner monitors EAP_HOME/standalone/deployments. See Deployment scanner configuration for details on configuring an existing deployment scanner.

The following management CLI command adds a new deployment scanner that will check EAP_HOME/standalone/new_deployment_dir every five seconds for deployments. 

/subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
Note

The specified directory must already exist or this command will fail with an error.

A new deployment scanner has been defined and the specified directory will be monitored for deployments.

6.4. Managing application deployment using Maven

Deploying applications using Apache Maven allows you to easily incorporate deployment to JBoss EAP into your existing development workflow.

You can use Maven to deploy applications to JBoss EAP using the WildFly Maven Plugin, which provides simple operations to deploy and undeploy applications to the application server.

6.4.1. Managing application deployment on a standalone server using Maven

You can deploy and undeploy applications to JBoss EAP running as a standalone server by using the WildFly Maven Plugin.

6.4.1.1. Deploying an application to a standalone server using Maven

The following instructions show how to undeploy the JBoss EAP helloworld quickstart to a standalone server using Maven.

See Using the Quickstart Examples in the JBoss EAP Getting Started Guide for more information on the JBoss EAP quickstarts.

Procedure

  1. Initialize the WildFly Maven Plugin in your Maven pom.xml file. This should already be configured in the JBoss EAP quickstart pom.xml files. 

    <plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
</plugin>

  2. From the helloworld quickstart directory, execute the following Maven command. 

    $ mvn clean install wildfly:deploy

    After issuing the Maven command to deploy, the terminal window shows the following output indicating a successful deployment. 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.981 s
[INFO] Finished at: 2015-12-23T15:06:13-05:00
[INFO] Final Memory: 21M/231M
[INFO] ------------------------------------------------------------------------

Verification

  • The deployment can also be confirmed by viewing the server log of the active server instance. 

    WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")

6.4.1.2. Undeploying an application from a standalone server using Maven

The following instructions show how to undeploy the JBoss EAP helloworld quickstart to a standalone server using Maven.

Prerequisites

  • You have initialized the WildFly Maven Plugin in your Maven pom.xml file.

Procedure

  • From the helloworld quickstart directory, execute the following Maven command. 

    $ mvn wildfly:undeploy

    After issuing the Maven command to undeploy, the terminal window shows the following output indicating a successful undeployment. 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.237 s
[INFO] Finished at: 2015-12-23T15:09:10-05:00
[INFO] Final Memory: 10M/183M
[INFO] ------------------------------------------------------------------------

Verification

  • The undeployment can also be confirmed by viewing the server log of the active server instance. 

    WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 27ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

6.4.2. Managing application deployment on a managed domain using Maven

You can deploy and undeploy applications to JBoss EAP running as a managed domain by using the WildFly Maven Plugin.

6.4.2.1. Deploying an application to a managed domain using Maven

The following instructions show how to deploy the JBoss EAP helloworld quickstart in a managed domain using Maven.

See Using the Quickstart Examples in the JBoss EAP Getting Started Guide for more information on the JBoss EAP quickstarts.

Procedure

  1. Specify the server groups to which the application should be deployed in the Maven pom.xml file. The following configuration in the pom.xml initializes the WildFly Maven Plugin and specifies main-server-group as the server group to which the application should be deployed. 

    <plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>${version.wildfly.maven.plugin}</version>
  <configuration>
    <domain>
      <server-groups>
        <server-group>main-server-group</server-group>
      </server-groups>
    </domain>
  </configuration>
</plugin>

  2. From the helloworld quickstart directory, execute the following Maven command. 

    $ mvn clean install wildfly:deploy

    After issuing the Maven command to deploy, the terminal window shows the following output indicating a successful deployment. 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.005 s
[INFO] Finished at: 2016-09-02T14:36:17-04:00
[INFO] Final Memory: 21M/226M
[INFO] ------------------------------------------------------------------------

    Verification

    • The deployment can also be confirmed by viewing the server log of the active server instance. 

      WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
WFLYUT0021: Registered web context: /helloworld
WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")

6.4.2.2. Undeploying an application from a managed domain using Maven

The following instructions show how to deploy the JBoss EAP helloworld quickstart in a managed domain using Maven.

Prerequisites

  • You have initialized the WildFly Maven Plugin.

Procedure

  • From the helloworld quickstart directory, execute the following Maven command. 

    $ mvn wildfly:undeploy

    After issuing the Maven command to undeploy, the terminal window shows the following output indicating a successful undeployment. 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.750 s
[INFO] Finished at: 2016-09-02T14:45:10-04:00
[INFO] Final Memory: 10M/184M
[INFO] ------------------------------------------------------------------------

Verification

  • The undeployment can also be confirmed by viewing the server log of the active server instance. 
WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 106ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")

6.5. Managing application deployment using the HTTP API

Applications can be deployed to JBoss EAP using the HTTP API with the curl command. For more information on using the HTTP API, see the HTTP API section.

6.5.1. Application deployment management on a standalone server using the HTTP API

By default, the HTTP API is accessible at http://HOST:PORT/management, for example, http://localhost:9990/management.

Deploy an Application

$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}]},{"operation" : "deploy", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'

Undeploy an Application

$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "test-application.war"}},{"operation" : "remove", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'

See this Red Hat Knowledgebase article to learn more about programmatically generating the JSON requests.

6.5.2. Application deployment management on a managed domain using the HTTP API

You can deploy and undeploy applications on a managed domain using the HTTP API.

6.5.2.1. Deploying an application in a managed domain using the HTTP API

By default, the HTTP API is accessible at http://HOST:PORT/management, for example, http://localhost:9990/management.

Procedure

  1. Add the deployment to the content repository. 

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:</path/to>/test-application.war"}],"json.pretty":1}'

  2. Add the deployment to the desired server group. 

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "add", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'

  3. Deploy the application to the server group. 

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "deploy", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'

6.5.2.2. Undeploying an application in a managed domain using the HTTP API

By default, the HTTP API is accessible at http://HOST:PORT/management, for example, http://localhost:9990/management.

Procedure

  1. Remove the deployment from all server groups to which it is assigned. 

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "remove", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'

  2. Remove the deployment from the content repository. 

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "remove", "address" : {"deployment" : "test-application.war"}, "json.pretty":1}'

6.6. Customizing deployment behavior

6.6.1. Custom directory for deployment content

You can define a custom location for JBoss EAP to store deployed content.

Define a Custom Directory for a Standalone Server

By default, deployed content for a standalone server is stored in the EAP_HOME/standalone/data/content directory. This location can be changed by passing in the -Djboss.server.deploy.dir argument when starting the server. 

$ EAP_HOME/bin/standalone.sh -Djboss.server.deploy.dir=/path/to/new_deployed_content

The chosen location should be unique among JBoss EAP instances.

Note

The jboss.server.deploy.dir property specifies the directory to be used for storing content that has been deployed using the management console or management CLI. To define a custom deployment directory to be monitored by the deployment scanner, see Deployment scanner configuration.

Define a Custom Directory for a Managed Domain

By default, deployed content for a managed domain is stored in the EAP_HOME/domain/data/content directory. This location can be changed by passing in the -Djboss.domain.deployment.dir argument when starting the domain. 

$ EAP_HOME/bin/domain.sh -Djboss.domain.deployment.dir=/path/to/new_deployed_content

The chosen location should be unique among JBoss EAP instances.

6.6.2. Control the order of deployments

JBoss EAP offers fine-grained control over the order of deployments when the server is started. Strict order of the deployment of applications present in multiple EAR files can be specified along with persistence of the order after a restart.

You can use the jboss-all.xml deployment descriptor to declare dependencies between top-level deployments.

For example, if you have an app.ear that depends on framework.ear being deployed first, then you can create an app.ear/META-INF/jboss-all.xml file as shown below. 

<jboss xmlns="urn:jboss:1.0">
  <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
    <dependency name="framework.ear" />
  </jboss-deployment-dependencies>
</jboss>
Note

You can use the deployment’s runtime name as the dependency name in the jboss-all.xml file.

This ensures that framework.ear is deployed before app.ear.

Important

If you create a jboss-all.xml file in app.ear and you do not deploy framework.ear, the server attempts to deploy app.ear and fails.

6.6.3. Overriding deployment content

6.6.3.1. About deployment overlay

A deployment overlay can be used to overlay content into an existing deployment without physically modifying the contents of the deployment archive. It allows you to override deployment descriptors, library JAR files, classes, Jakarta Server Pages pages, and other files at runtime without rebuilding the archive.

This can be useful if you need to adapt a deployment for different environments that need different configurations or settings. For example, when moving a deployment through the application lifecycle from development, to testing, to stage, and finally into production, you might want to swap deployment descriptors, modify static web resources to change the branding of the application, or even replace JAR libraries with different versions depending on the target environment. It is also a useful feature for installations that need to change a configuration but can not modify or crack an archive due to policy or security restrictions.

When defining a deployment overlay, you specify the file on a file system that will replace the file in the deployment archive. You must also specify which deployments should be affected by the deployment overlay. Any affected deployments must be redeployed in order for the changes to take effect.

Parameters

You can use any of the following parameters to configure your deployment overlay:

  • name: The name of the deployment overlay.
  • content: A comma-separated list that maps the file on the file system to the file in the archive that it replaces. The format for each entry is ARCHIVE_PATH=FILESYSTEM_PATH.
  • deployments: Comma-separated list of deployments to which this overlay is linked.
  • redeploy-affected: Redeploys all affected deployments.

For full usage details, execute deployment-overlay --help.

6.6.3.2. Defining a deployment overlay

You can define a deployment overlay to overlay content into an existing deployment without physically modifying the contents of the deployment archive.

Procedure

  1. Use the deployment-overlay add management CLI command to add a deployment overlay: 

    deployment-overlay add --name=new-deployment-overlay --content=WEB-INF/web.xml=/path/to/other/web.xml --deployments=test-application.war --redeploy-affected
    Note

    In a managed domain, specify the applicable server groups by using --server-groups or specify all server groups with --all-server-groups.

  2. After you created a deployment overlay, you can add content to an existing overlay, link the overlay to a deployment, or remove the overlay.

  3. Optional: You can specify an overlay configuration to link to an external directory that contains static web resources, such as HTML, images, or videos, using the <overlay> element.

    The <overlay> element specifies static files that overlay the static files of a web application, similar to the procedure of JAR overlays. This element is located in the application file jboss-web.xml. With this element configuration, you do not need to repackage the application.

    The following example shows system property substitution in the <overlay> element, where {example.path.to.overlay} defines the /PATH/TO/STATIC/WEB/CONTENT location.

    Example: <overlay> element in a jboss-web.xml file

    <jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_10_0.xsd"
           version="10.0">
        <overlay>{example.path.to.overlay}</overlay>
</jboss-web>

    You can specify a system property in the <overlay> element if jboss-descriptor-property-replacement is set to true, which is the default value for the descriptor property.

    To configure jboss-descriptor-property-replacement, use the following management CLI command: 

    /subsystem=ee:write-attribute(name=jboss-descriptor-property-replacement,value=true)

    This command adds the following XML content to the ee subsystem in the JBoss EAP configuration: 

    <subsystem xmlns="urn:jboss:domain:ee:4.0">
    <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
</subsystem>
    Note

    The <overlay> element does not override deployment files that already exist in your EAP project. If multiple <overlay> elements include the same file, the precedence order is determined based on the sequence of the overlay elements in the application jboss-web.xml file.

6.6.4. Using rollout plans

In a managed domain, operations targeted at domain or host level resources can potentially impact multiple servers. Such operations can include a roll out plan detailing the sequence in which the operation would be applied to the servers, as well as the policies for detailing whether the operation could be reverted if it fails to execute successfully on some servers. If no rollout plan is specified, the default rollout plan is used.

6.6.4.1. Example rollout plan

Below is an example rollout plan involving five server groups. Operations can be applied to server groups serially, in-series, or concurrently, concurrent-groups. For more information, see Rollout plan syntax. 

{"my-rollout-plan" => {"rollout-plan" => {
    "in-series" => [
        {"concurrent-groups" => {
            "group-A" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-B" => undefined
        }},
        {"server-group" => {"group-C" => {
            "rolling-to-servers" => "false",
            "max-failed-servers" => "1"
        }}},
        {"concurrent-groups" => {
            "group-D" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-E" => undefined
        }}
    ],
    "rollback-across-groups" => "true"
}}}

Looking at the example above, applying the operation to the servers in the domain is done in three phases. If the policy for any server group triggers a rollback of the operation across the server group, all other server groups will be rolled back as well.

  1. Server groups group-A and group-B will have the operation applied concurrently. The operation will be applied to the servers in group-A in series, while all servers in group-B will handle the operation concurrently. If more than 20% of the servers in group-A fail to apply the operation, it will be rolled back across that group. If any servers in group-B fail to apply the operation it will be rolled back across that group.
  2. Once all servers in group-A and group-B are complete, the operation will be applied to the servers in group-C. Those servers will handle the operation concurrently. If more than one server in group-C fails to apply the operation it will be rolled back across that group.
  3. Once all servers in group-C are complete, server groups group-D and group-E will have the operation applied concurrently. The operation will be applied to the servers in group-D in series, while all servers in group-E will handle the operation concurrently. If more than 20% of the servers in group-D fail to apply the operation, it will be rolled back across that group. If any servers in group-E fail to apply the operation it will be rolled back across that group.

6.6.4.2. Rollout plan syntax

You can specify a rollout plan in either of the following ways.

Although each method has a different initial command, both methods use the rollout operation header to define the rollout plan. This uses the following syntax. 

rollout (id=PLAN_NAME | SERVER_GROUP_LIST) [rollback-across-groups]
  • PLAN_NAME is the name for the rollout plan that was stored using the rollout-plan command.

  • SERVER_GROUP_LIST is the list of server groups. Use a comma (,) to separate multiple server groups to indicate that operations should be performed on each server group sequentially. Use a caret (^) separator to indicate that operations should be performed on each server group concurrently.

    • For each server group, set any of the following policies in parentheses. Use a comma to separate multiple policies.

      • rolling-to-servers: A boolean that, if set to true, applies the operation to each server in the group in series. If the value is false or not specified, the operation will be applied to the servers in the group concurrently.
      • max-failed-servers: An integer which takes the maximum number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is 0, meaning that a failure on any server will trigger rollback across the group.

      • max-failure-percentage: An integer between 0 and 100 that represents the maximum percentage of the total number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is 0, meaning that a failure on any server will trigger rollback across the group.

        Note

        If both max-failed-servers and max-failure-percentage are set to non-zero values, max-failure-percentage takes precedence.

  • rollback-across-groups: A boolean that indicates whether the need to rollback the operation on all the servers in one server group triggers a rollback across all the server groups. This defaults to false.

6.6.4.3. Deploy an application using a rollout plan

You can provide the full details of a rollout plan directly to the deploy command by passing the rollout settings into the headers argument. See the Rollout Plan Syntax for more information on the format.

The following management CLI command deploys an application to the main-server-group server group using a deployment plan that specifies rolling-to-servers=true for serial deployment. 

deploy /path/to/test-application.war --server-groups=main-server-group --headers={rollout main-server-group(rolling-to-servers=true)}

6.6.4.4. Deploying an application using a stored rollout plan

Since rollout plans can be complex, you have the option to store the details of a rollout plan. This allows you to reference the rollout plan name when you want to use it instead of requiring the full details of the rollout plan each time.

Procedure

  1. Use the rollout-plan management CLI command to store a rollout plan. See the Rollout plan syntax for more information on the format. 

    rollout-plan add --name=my-rollout-plan --content={rollout main-server-group(rolling-to-servers=false,max-failed-servers=1),other-server-group(rolling-to-servers=true,max-failure-percentage=20) rollback-across-groups=true}

    This creates the following deployment plan. 

    "rollout-plan" => {
    "in-series" => [
        {"server-group" => {"main-server-group" => {
            "rolling-to-servers" => false,
            "max-failed-servers" => 1
        }}},
        {"server-group" => {"other-server-group" => {
            "rolling-to-servers" => true,
            "max-failure-percentage" => 20
        }}}
    ],
    "rollback-across-groups" => true
}

  2. Specify the stored rollout plan name when deploying the application.

    The following management CLI command deploys an application to all server groups using the my-rollout-plan stored rollout plan. 

    deploy /path/to/test-application.war --all-server-groups --headers={rollout id=my-rollout-plan}

6.6.4.5. Stored rollout plan removal

You can remove a stored rollout plan using the rollout-plan management CLI command by specifying the name of the rollout plan to remove. 

rollout-plan remove --name=my-rollout-plan

6.6.4.6. Default rollout plan

All operations that impact multiple servers will be executed with a rollout plan. If no rollout plan is specified in the operation request, a default rollout plan will be generated. The plan will have the following characteristics.

  • There will only be a single high-level phase. All server groups affected by the operation will have the operation applied concurrently.
  • Within each server group, the operation will be applied to all servers concurrently.
  • Failure on any server in a server group will cause rollback across the group.
  • Failure of any server group will result in rollback of all other server groups.

6.7. Manage exploded deployments

You can manage exploded deployments using the management interfaces. This allows you to change the contents of an exploded application without deploying a new version of the application.

Note

Updates to static files in a deployment, such as JavaScript and CSS files, take effect immediately. Changes to other files, such as Java classes, might require an application redeployment for the changes to take effect.

You can either start with an empty deployment or explode an existing archive deployment and then add or remove content.

See Viewing Deployment Content to browse the files in a deployment or read the contents of the files.

Create an Empty Exploded Deployment

You can create an empty exploded deployment to which you can later add content as necessary. Use the following management CLI command to create an empty exploded deployment. 

/deployment=DEPLOYMENT_NAME.war:add(content=[{empty=true}])

The empty=true option is required to confirm that you intended to create an empty deployment.

Explode an Existing Archive Deployment

You can explode an existing archive deployment to be able to update its contents. Note that a deployment must be disabled before it can be exploded. Use the following management CLI command to explode a deployment. 

/deployment=ARCHIVE_DEPLOYMENT_NAME.ear:explode

You can now add or remove content from this deployment.

Note

You can also explode an existing archive deployment from the management console. From the Deployments tab, select the deployment and select the Explode drop down option.

Add Content to an Exploded Deployment

To add content to a deployment, use the add-content management CLI operation. Provide the path to the location in the deployment where the content should be added, and provide the content to be uploaded. The content to upload can be provided as a local file stream, URL, hash of content that already exists in the JBoss EAP content repository, or a byte array of the content. The following management CLI command uses the input-stream-index option to upload the contents of a local file to the deployment. 

/deployment=DEPLOYMENT_NAME.war:add-content(content=[{target-path=/path/to/FILE_IN_DEPLOYMENT, input-stream-index=/path/to/LOCAL_FILE_TO_UPLOAD}]
Note

When adding content to a deployment using the add-content operation, content in the deployment is overwritten by default. You can change this behavior by setting the overwrite option to false.

Remove Content from an Exploded Deployment

To remove content from a deployment, use the remove-content management CLI operation and provide the path of the content in the deployment to remove. 

/deployment=DEPLOYMENT_NAME.war:remove-content(paths=[/path/to/FILE_1, /path/to/FILE_2])

6.8. Viewing deployment content

You can browse information about files in a managed deployment and read the contents of the files using the JBoss EAP management interfaces.

6.8.1. Browse files in a deployment

Use the browse-content operation to view the files and directories in a managed deployment. Provide no arguments to return the entire deployment structure or use the path argument to provide the path to a specific directory.

Note

You can also browse contents of a deployment from the management console by navigating to the Deployments tab, selecting the deployment, and selecting View from the drop down. 

/deployment=helloworld.war:browse-content(path=META-INF/)

This displays the files and directories in the META-INF/ directory of the helloworld.war deployment. 

{
    "outcome" => "success",
    "result" => [
        {
            "path" => "MANIFEST.MF",
            "directory" => false,
            "file-size" => 827L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.properties",
            "directory" => false,
            "file-size" => 106L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.xml",
            "directory" => false,
            "file-size" => 2713L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/",
            "directory" => true
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/",
            "directory" => true
        },
        {
            "path" => "maven/",
            "directory" => true
        },
        {
            "path" => "INDEX.LIST",
            "directory" => false,
            "file-size" => 251L
        }
    ]
}

You can also specify the following arguments to the browse-content operation.

archive
Whether to only return archive files.
depth
Specify the depth of files to return.

6.8.2. Read deployment content

You can read the contents of a file in a managed deployment using the read-content operation. Provide no arguments to return the entire deployment or use the path argument to provide the path to a specific file. For example: 

/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

This returns a file stream, which can be displayed in the management CLI or saved to the file system. 

{
    "outcome" => "success",
    "result" => {"uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95"},
    "response-headers" => {"attached-streams" => [{
        "uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95",
        "mime-type" => "text/plain"
    }]}
}

6.8.2.1. Display the Contents of a File

Use the attachment display command to read the contents of the MANIFEST.MF file. 

attachment display --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)

This displays the contents of the MANIFEST.MF file from the helloworld.war deployment to the management CLI. 

ATTACHMENT 8af87836-2abd-423a-8e44-e731cc57bd80:
Manifest-Version: 1.0
Implementation-Title: Quickstart: helloworld
Implementation-Version: 7.4.0.GA
Java-Version: 1.8.0_131
Built-By: username
Scm-Connection: scm:git:git@github.com:jboss/jboss-parent-pom.git/quic
 kstart-parent/helloworld
Specification-Vendor: JBoss by Red Hat
...

6.8.2.2. Save the Contents of a File

Use the attachment save command to save the contents of the MANIFEST.MF file to the file system. 

attachment save --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF) --file=/path/to/MANIFEST.MF

This saves the MANIFEST.MF file from the helloworld.war deployment to the file system at path/to/MANIFEST.MF. If you do not specify a file path using the --file argument, the file will be named using its unique attachment ID and saved in the working directory of the management CLI, which by default is EAP_HOME/bin/.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.