10.5. Deploy with the Deployment Scanner

10.5.1. Manage Application Deployment in the Deployment Scanner

Deploying applications to a standalone server instance via the deployment scanner allows you to build and test applications in a manner suited for rapid development cycles. You can configure the deployment scanner to suit your needs for deployment frequency and behavior for a variety of application types.

10.5.2. Deploy an Application to a Standalone Server Instance with the Deployment Scanner

Summary

This task shows a method for deploying applications to a standalone server instance with the deployment scanner. As indicated in the Section 10.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Procedure 10.9. Use the Deployment Scanner to Deploy Applications

  1. Copy content to the deployment folder

    Copy the application file to the deployment folder found at EAP_HOME/standalone/deployments/.
  2. Deployment scanning modes

    There are two application deployment methods. You can choose between automatic and manual deployment scanner modes. Before starting either of the deployment methods, read Section 10.5.8, “Configure the Deployment Scanner with the Management CLI”.
    • Automatic deployment

      The deployment scanner picks up a change to the state of the folder and creates a marker file as defined in Section 10.5.8, “Configure the Deployment Scanner with the Management CLI”.
    • Manual deployment

      The deployment scanner requires a marker file to trigger the deployment process. The following example uses the Unix touch command to create a new .dodeploy file.

      Example 10.3. Deploy with the touch command

      [user@host bin]$ touch $EAP_HOME/standalone/deployments/example.war.dodeploy
Result

The application file is deployed to the application server. A marker file is created in the deployment folder to indicate the successful deployment, and the application is flagged as Enabled in the Management Console.

Example 10.4. Deployment folder contents after deployment

example.war
example.war.deployed

10.5.3. Undeploy an Application from a Standalone Server Instance with the Deployment Scanner

Summary

This task shows a method for undeploying applications from a standalone server instance that have been deployed with the deployment scanner. As indicated in the Section 10.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Note

The deployment scanner should not be used in conjunction with other deployment methods for application management. Applications removed from the application server by the management console will be removed from the runtime without affecting the marker files or application contained in the deployment directory. To minimize the risk of accidental redployment or other errors, use the Management CLI and Management Console for administration in production environments.

Procedure 10.10. Undeploy an Application using one of these Methods

  • Undeploy the application

    There are two methods to undeploy the application depending on whether you want to delete the application from the deployment folder or only alter its deployment status.
    • Undeploy by deleting the marker file

      Delete the deployed application's example.war.deployed marker file to trigger the deployment scanner to begin undeploying the application from the runtime.
      Result
      The deployment scanner undeploys the application and creates a example.war.undeployed marker file. The application remains in the deployment folder.
    • Undeploy by removing the application

      Note

      Undeploying an exploded WAR file using this method is not valid. Only undeployment by removing the marker file is valid. Attempting to undeploy an exploded WAR file will result in a message like the following message being logged.
      WARN  [org.jboss.as.server.deployment.scanner] (DeploymentScanner-threads - 2) JBAS015006: The deployment scanner found that the content for exploded deployment EXAMPLE.war has been deleted, but auto-deploy/undeploy for exploded deployments is not enabled and the EXAMPLE.war.deployed marker file for this deployment has not been removed. As a result, the deployment is not being undeployed, but resources needed by the deployment may have been deleted and application errors may occur. Deleting the EXAMPLE.war.deployed marker file to trigger undeploy is recommended.
      Remove the application from the deployment directory to trigger the deployment scanner to begin undeploying the application from the runtime.
      Result
      The deployment scanner undeploys the application and creates a filename.filetype.undeployed marker file. The application is not present in the deployment folder.
Result

The application file is undeployed from the application server and is not visible in the Deployments screen of the Management Console.

10.5.4. Redeploy an Application to a Standalone Server Instance with the Deployment Scanner

Summary

This task shows a method for redeploying applications to a standalone server instance that have been deployed with the deployment scanner. As indicated in the Section 10.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Procedure 10.11. Redeploy an Application to a Standalone Server

  • Redeploy the application

    There are three possible methods to redeploy an application deployed with the deployment scanner. These methods trigger the deployment scanner to initiate a deployment cycle, and can be chosen to suit personal preference.
Result

The application file is redeployed.

10.5.5. Reference for Deployment Scanner Marker Files

Marker files

Marker files are a part of the deployment scanner subsystem. These files mark the status of an application within the deployment directory of the standalone server instance. A marker file has the same name as the application, with the file suffix indicating the state of the application's deployment. The following table defines the types and responses for each marker file.

Example 10.6. Marker file example

The following example shows the marker file for a successfully deployed instance of an application called testapplication.war.
testapplication.war.deployed

Table 10.1. Marker filetype definitions

Filename Suffix Origin Description
.dodeploy User generated Indicates that the content should be deployed or redeployed into the runtime.
.skipdeploy User generated Disables auto-deploy of an application while present. Useful as a method of temporarily blocking the auto-deployment of exploded content, preventing the risk of incomplete content edits pushing live. Can be used with zipped content, although the scanner detects in-progress changes to zipped content and waits until completion.
.isdeploying System generated Indicates the initiation of deployment. The marker file will be deleted when the deployment process completes.
.deployed System generated Indicates that the content has been deployed. The content will be undeployed if this file is deleted.
.failed System generated Indicates deployment failure. The marker file contains information about the cause of failure. If the marker file is deleted, the content will be visible to the auto-deployment again.
.isundeploying System generated Indicates a response to a .deployed file deletion. The content will be undeployed and the marker will be automatically deleted upon completion.
.undeployed System generated Indicates that the content has been undeployed. Deletion of the marker file has no impact to content redeployment.
.pending System generated Indicates that deployment instructions will be sent to the server pending resolution of a detected issue. This marker serves as a global deployment road-block. The scanner will not instruct the server to deploy or undeploy any other content while this condition exists.

10.5.6. Reference for Deployment Scanner Attributes

The deployment scanner contains the following attributes that are exposed to the Management CLI and able to be configured using the write-attribute operation. For more information on configuration options, refer to the topic Section 10.5.8, “Configure the Deployment Scanner with the Management CLI”.

Table 10.2. Deployment Scanner Attributes

Name Description Type Default Value
auto-deploy-exploded Allows the automatic deployment of exploded content without requiring a .dodeploy marker file. Recommended for only basic development scenarios to prevent exploded application deployment from occurring during changes by the developer or operating system. Boolean False
auto-deploy-xml Allows the automatic deployment of XML content without requiring a .dodeploy marker file. Boolean True
auto-deploy-zipped Allows the automatic deployment of zipped content without requiring a .dodeploy marker file. Boolean True
deployment-timeout The time value in seconds for the deployment scanner to allow a deployment attempt before being cancelled. Long 600
path Defines the actual filesystem path to be scanned. If the relative-to attribute is specified, the path value acts as a relative addition to that directory or path. String deployments
relative-to Reference to a filesystem path defined in the paths section of the server configuration XML file. String jboss.server.base.dir
scan-enabled Allows the automatic scanning for applications by scan-interval and at startup. Boolean True
scan-interval The time interval in milliseconds between scans of the repository. A value of less than 1 restricts the scanner to operate only at startup. Int 5000

10.5.7. Configure the Deployment Scanner

The deployment scanner can be configured using the Management Console or the Management CLI. You can create a new deployment scanner or manage the existing scanner attributes. These include the scanning interval, the location of the deployment folder, and the application file types that will trigger a deployment.

10.5.8. Configure the Deployment Scanner with the Management CLI

Summary

While there are multiple methods of configuring the deployment scanner, the Management CLI can be used to expose and modify the attributes by use of batch scripts or in real time. You can modify the behavior of the deployment scanner by use of the read-attribute and write-attribute global command line operations. Further information about the deployment scanner attributes are defined in the topic Section 10.5.6, “Reference for Deployment Scanner Attributes”.

The deployment scanner is a subsystem of JBoss EAP 6, and can be viewed in the standalone.xml.

Example 10.7. Excerpt from standalone.xml

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
</subsystem>

Procedure 10.12. Configure the Deployment Scanner

  1. Determine the deployment scanner attributes to configure

    Configuring the deployment scanner via the Management CLI requires that you first expose the correct attribute names. You can do this with the read-resources operation at either the root node, or by using the cd command to change into the subsystem child node. You can also display the attributes with the ls command at this level.
    • Expose the deployment scanner attributes with the read-resource operation

      Use the read-resource operation to expose the attributes defined by the default deployment scanner resource.

      Example 10.8. Sample read-resource output

      [standalone@localhost:9999 /]/subsystem=deployment-scanner/scanner=default:read-resource
      {
          "outcome" => "success",
          "result" => {
              "auto-deploy-exploded" => false,
              "auto-deploy-xml" => true,
              "auto-deploy-zipped" => true,
              "deployment-timeout" => 600,
              "path" => "deployments",
              "relative-to" => "jboss.server.base.dir",
              "scan-enabled" => true,
              "scan-interval" => 5000
          }
      }
    • Expose the deployment scanner attributes with the ls command

      Use the ls command with the -l optional argument to display a table of results that include the subsystem node attributes, values, and type. You can learn more about the ls command and its arguments by exposing the CLI help entry by typing ls --help. For more information about the help menu in the Management CLI, refer to the topic Section 3.4.5, “Obtain Help with the Management CLI”.

      Example 10.9. Sample ls -l output

      [standalone@localhost:9999 /] ls -l /subsystem=deployment-scanner/scanner=default
      ATTRIBUTE            VALUE                 TYPE    
      auto-deploy-exploded false                 BOOLEAN 
      auto-deploy-xml      true                  BOOLEAN 
      auto-deploy-zipped   true                  BOOLEAN 
      deployment-timeout   600                   LONG    
      path                 deployments           STRING  
      relative-to          jboss.server.base.dir STRING  
      scan-enabled         true                  BOOLEAN 
      scan-interval        5000                  INT
  2. Configure the deployment scanner with the write-attribute operation

    Once you have determined the name of the attribute to modify, use the write-attribute to specify the attribute name and the new value to write to it. The following examples are all run at the child node level, which can be accessed by using the cd command and tab completion to expose and change into the default scanner node.
    [standalone@localhost:9999 /] cd subsystem=deployment-scanner/scanner=default
    1. Enable automatic deployment of exploded content

      Use the write-attribute operation to enable the automatic deployment of exploded application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-exploded,value=true)
      {"outcome" => "success"}
    2. Disable the automatic deployment of XML content

      Use the write-attribute operation to disable the automatic deployment of XML application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-xml,value=false)     
      {"outcome" => "success"}
    3. Disable the automatic deployment of zipped content

      Use the write-attribute command to disable the automatic deployment of zipped application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-zipped,value=false)
      {"outcome" => "success"}
    4. Configure the path attribute

      Use the write-attribute operation to modify the path attribute, substituting the example newpathname value for the new path name for the deployment scanner to monitor. Note that the server will require a reload to take effect.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=path,value=newpathname)            
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
    5. Configure the relative path attribute

      Use the write-attribute operation to modify the relative reference to the filesystem path defined in the paths section of the configuration XML file. Note that the server will require a reload to take effect.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=relative-to,value=new.relative.dir)
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
    6. Disable the deployment scanner

      Use the write-attribute operation to disable the deployment scanner by setting the scan-enabled value to false.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-enabled,value=false)        
      {"outcome" => "success"}
    7. Change the scan interval

      Use the write-attribute operation to modify the scan interval time from 5000 milliseconds to 10000 milliseconds.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-interval,value=10000)
      {"outcome" => "success"}
Result

Your configuration changes are saved to the deployment scanner.

10.5.9. Define a Custom Deployment Scanner

Summary

A new deployment scanner can be added using the Management Console or the Management CLI. This will define a new directory to scan for deployments. The default deployment scanner monitors EAP_HOME/standalone/deployments/. See Section 10.5.8, “Configure the Deployment Scanner with the Management CLI” for details on configuring an existing deployment scanner.

Procedure 10.13. Define a Custom Deployment Scanner with the Management CLI

  1. Add a deployment scanner using the Management CLI add operation:
    [standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
    {"outcome" => "success"}

    Note

    The specified directory must already exist or this command will fail with an error.
  2. The new deployment scanner is now visible in the standalone.xml file and management interfaces.

    Example 10.10. Excerpt from standalone.xml

    <subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    	<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
    	<deployment-scanner name="new-scanner" path="new_deployment_dir" relative-to="jboss.server.base.dir" scan-interval="5000"/>
    </subsystem>
  3. The specified directory will now be scanned for deployments. See Section 10.5.2, “Deploy an Application to a Standalone Server Instance with the Deployment Scanner” for details on deploying an application with the deployment scanner.
Result

A new deployment scanner has been defined and is monitoring for deployments.