32.5. Deploying Web Applications
Web applications are a unique type of resource. They are added as child resources of servers, so they have a place within the inventory with their own entries, possibly even their own child resources, and independent configuration for monitoring, alerting, and operations. However, web applications are content-backed resources. Ultimately, they are software packages, not true servers or services.
Managing a content-backed resource requires a path to make the initial deployment (creating the deployment as a child resource) and also a path for patches and updates (content updates).
Important
Deploying content-backed resources can have a significant impact on disk space requirements.
JBoss ON stores all versions of content. This is part of versioning control, allowing changes to content-backed resources to be reverted and managed and for different versions to be deployed at different times.
Therefore, the system which hosts the backend database (Oracle or PostgreSQL) must have enough disk space to store all versions of all bundles. Additionally, the database itself must have adequate tablespace for the content.
When calculating the required amount of space, estimate the size of every artifact, and then the number of versions for each artifact. At a minimum, have twice that amount of space available; both PostgreSQL and Oracle require twice the database size to perform cleanup operations like vacuum, compression, and backup and recovery.
32.5.1. Runtime Information and Deployment Resources
32.5.1.1. Views of Deployments
Both EAP 6 and JBoss ON offer clear workflows for adding web applications to a central content repository and then associating that content with a server group. But the perspectives they offer are very different, so deciding which console to use depends on what needs to be accomplished at that particular moment.
The EAP 6 console is focused on immediately associating content with a server group. In the EAP 6 console, deployments are treated similarly to shared configuration, like a JVM definition. A content package is deployed to a domain controller or a server group and is then associated with a managed server.
Figure 32.13. Deployments in the Runtime Page
JBoss ON is focused on lifecycle management for web application, an historical and changing perspective. There are a few fundamental differences in how JBoss ON defines web applications:
- A web application is treated as a separate entity, in and of itself. It has its own place in the inventory; its association with domains and server groups is reflected as it is a child of those resources.JBoss ON also records package details, like its file size and an identifying SHA256 hash.
- A web application has a history. Updates to packages are recorded in a changelog which makes it possible to track how the application has been maintained.
- Web applications can be monitored. Response time metrics specifically track the performance of web applications, apart from the performance or monitoring of the underlying server.
Figure 32.14. Deployment Resource Details in JBoss ON
The reason for this emphasis on web applications as a resource is that the core purpose is not the simple task of deploying content to a server. The EAP 6 console does that very simply and cleanly. The purpose of JBoss ON management is administration of that content of a web application:
- Creating content repositories to store patches and updates
- Tracking multiple versions of content
- Reverting software packages to a previous version (particularly for standalone servers)
- Using the same content repository for multiple EAP instances, including multiple domains and standalone server
- Tracking (and auditing) changes to content
32.5.1.2. Deployment Paths for Standalone Servers and Domains
There is a radically different structure between standalone servers and domains, and that impacts the content flow for deploying web applications.
Web application deployments in standalone servers are similar to EAP 5, in that there is a local filesystem directory which is used for deployments. Locally, applications can be added to that deployment directory and hot-deployed. Using JBoss ON, there are two paths for deploying web applications:
- Create a deployment as a child resource
- Use a bundle to provision the application in the deployment directory
Using bundles is a versatile and practical management method, because the bundle system has capabilities to store multiple versions, rollback updates, skip versions for updates, or purge deployments, all with a single button.
Unfortunately, the bundles system only works with real filesystem locations. The distributed and modular structure for JBoss EAP 6 domains means that bundles are not an option.
For EAP 6 domains, the content is deployed as a child resource to the domain and then is propagated to server groups by administrators.
It lacks the flexibility and finesse of the bundles system, but using the ordinary content system still offers ways to control content versions and updates. Content-backed resources can be associated with content repositories in JBoss ON. These repositories can store all sorts of software packages, from different content sources. Packages from the repo can be installed on the resource selectively. Additionally, a resource can be associated with multiple repos. While not as fluid as updating or reverting changes with bundles, the content repositories in JBoss ON provide a pathway to apply individual patch files to a web application or to roll out full updates.
Content management in general is described in Chapter 28, Managing Resource-Level Content Updates. This covers setting up content repositories, subscribing resources, and pushing updates.
32.5.2. Deploying Web Applications to a Domain
32.5.2.1. Deploying Web Applications to a Domain as a Child Resource
Note
As with creating other child resources, it can take several minutes for the new deployment to be added and visible in the JBoss ON inventory because the new resource has to be created on the local system and then discovered by the agent. If the discovery scan is running when the resource is created, then it may take until the next discovery scan to be detected, as long as 15 minutes.
- Click the Inventory tab in the top menu.
- Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss EAP 6 domain controller.
- Right-click the domain controller entry.
- In the Create New menu, select the item for DomainDeployment.
- Enter the version number.
- Upload the EAR, WAR, or JAR file.
- Optionally, enter a runtime name for the deployment.
- At the bottom of the wizard, set an optional timeout period. This is how long the JBoss ON server will wait during the deployment process before determining that the deployment has failed.NoteThe timeout period only applies to the server's reporting a result. If the operation continues running, it can still complete successfully, and the web application is deployed.Particularly for large application files, do not set a low timeout period, or the server will mark the deployment as having failed. If the deployment completes later, the web application must be imported into the inventory manually; it will not be discovered by the agent.
- Click Finish.
Once the package is uploaded, a new resource entry is added to the DomainDeployments directory for the domain.
Figure 32.15. Domain Deployments Directory
32.5.2.2. Deploying Web Applications to a Domain Through Bundles
Applications may be deployed to a JBoss Enterprise Application Platform 6 domain with the rhq:handover element using an ant bundle recipe. For more information on ant bundle recipes in general, see Chapter 27, Deploying Content and Applications Through Bundles.
The sample ant bundle recipe below deploys "website.war" to the "main-server-group-01" JBoss Enterprise Application Platform 6 domain server group.
<project name="handover-test-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">
<rhq:bundle name="example.com (EAP 6)" version="1.0" description="example.com corporate website hosted on EAP 6">
<rhq:input-property name="myapp.runtime.name" defaultValue="website.war" required="true"/>
<rhq:input-property name="myapp.serverGroup.name" defaultValue="main-server-group-01" required="true"/>
<rhq:deployment-unit name="example.com deployment unit" compliance="filesAndDirectories">
<rhq:file name="prepareDatasource.cli" replace="true">
<rhq:handover action="execute-script"/>
</rhq:file>
<rhq:archive name="website.war">
<rhq:handover action="deployment">
<rhq:handover-param name="runtimeName" value="${myapp.runtime.name}"/>
<rhq:handover-param name="serverGroup" value="${myapp.serverGroup.name}"/>
</rhq:handover>
</rhq:archive>
</rhq:deployment-unit>
</rhq:bundle>
<target name="main"/>
</project>
For the specific handover actions, handover parameters, and example recipes, please see the JBoss Enterprise Application Platform 6 plug-in documentation found by navigating to Administration > Configuration > Agent Plugins > JBoss Application Server 7.x.
To deploy an Ant Bundle to an JBoss Enterprise Application Platform domain:
- In the top menu, click the Bundles tab.
- Click the New button in the Bundle section.
- Select Upload and click Choose to navigate to and select the desired distribution file.
- Click Next.
- Choose any desired bundle groups and click Next.
- Click Next and then Finish.
- Click on the newly uploaded bundle from in the Bundle section.
- Click on the Deploy button in the bundle details.
- Fill in the destination information and proceed through the wizard.
Note
When specifying the destination information for a bundle, it should be based on the domain controller resource group.
When specifying the server group parameter in the ant bundle, this is the server group in the JBoss Enterprise Application Platform domain where the application will be deployed.
32.5.3. Assigning Web Applications to a Server Group
Assigning web applications to different groups manually allows administrators to control the lifecycle for applications, as expanded in Section 32.5.4, “Extended Example: Assigning Web Applications and Managing Updates”. The same content is used in different operating environments.
Note
Web applications can be deployed directly to a server group, much like the process to deploying it to a domain, in Section 32.5.2, “Deploying Web Applications to a Domain”.
The deployment path for a domain is to upload the content to the domain controller and then to distribute that content to a server group. Creating a deployment on a server group follows the same process; it deploys it to the domain and then sends it to the server group. It just provides a shortcut.
If the content already exists on the domain controller, then the content must be deployed through the domain controller operation described here.
Deploying the content to a domain first uses the domain as a kind of repository. From the domain, the same package can be deployed to multiple groups. Additionally, deploying to a domain allows administrators to deploy multiple packages in the same operation to a group, either simultaneously or in a specified order. This can help control content streams to servers.
Important
Newly-deployed content for a server group may not show up in the JBoss ON inventory for as long as 24 hours, even if it was successfully created. By default, discovery scans for services are only made every 24 hours. To see the new content-backed resource, run the agent's discovery scan and manually discover it.
Note
The deployment is created in the domain as a child resource, then assigned to a server group as an operation, and finally updated through the domain's Content tab.
- Click the Inventory tab in the top menu.
- Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss EAP 6 domain controller.
- Expand the DomainDeployments folder.To deploy all web applications in the deployments folder, select the deployments folder itself to run the operation.To deploy a single web application, select the specific web application.
- Open the Operations tab for the server.
- Click the New button at the bottom of the page.
- Select the Assign to Server-Group option from the drop-down menu.
- Select which group (or all groups) to deploy the application to.
- Enter the standard information for operations, like the schedule for when to run the operation and the timeout period.NoteThe timeout period sets how long the server waits before assuming that the operation has timed out and failed. This does not necessarily mean that the operation has failed or stopped running; it could complete successfully past the time out period.
- If there are multiple web applications being deployed, then set the Execute radio button to the way set the order that the packages are deployed. All packages can be deployed at once, or they can be deployed in a specific order.
- Click the Schedule button.
- Optionally, run a discovery scan on the agent to discover the new content resource. By default, discovery scans for services are only made every 24 hours, so there could be a long delay in discovering new content.
- Open the agent entry in the UI.
- Open the Operations tab, and select the execute prompt command operation.
- Enter the discovery command as an operation rgument. This runs a discovery scan.
- Click the Schedule button.
32.5.4. Extended Example: Assigning Web Applications and Managing Updates
The Setup
Tim the IT Guy wants to have a clear progression for web applications, from development through staging and production. The native structure in EAP 6 allows him to create different server groups and deploy content from his central domain controller to the appropriate server groups as it passes testing at each stage.
What Tim the IT Guy wants is to add a layer on top of that path that allows him to create an apply patches and updates. He has to be able to manage fixes and to audit when they were applied as part of his maintenance schedule.
The Plan
- Tim first outlines what server groups he needs to maintain. For a simple environment, he just wants three groups: testing, staging, and production.
- He creates two content repositories, one for patches and one for new versions of the web application.
- He creates the domain deployment and then promotes the web application to the testing server group.
- Tim configures response time monitoring for the web application. Once it meets the required performance parameters in the testing area, Tim promotes the deployment to the staging and then production server groups.
The Result
The package history for each deployment allows Tim to track when the web application was deployed, its version, and its content.
Tim can apply patches or full updates by deploying content to his repositories and installing it on every subscribed resource. These package changes, including new version numbers for the content, are included in the package history.
Because the patch and update repositories are configured in JBoss ON itself, not a specific JBoss Enterprise Application Platform 6 domain, the packages there can be used with other domains and standalone servers, if need be.
32.5.5. Enabling and Disabling Web Applications in a Domain Server Group
- Click the Inventory tab in the top menu.
- Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss Enterprise Application Platform 6 domain controller.
- In the inventory tree, expand the DomainDeployments folder, and select the web application to enable or disable from the list.
- Open the Configuration tab for the web app.
- In the Assigned to section, click on the blue pencil in the Server Group row that corresponds with the server group where the web app will be enabled or disabled.
- Select Yes or No in the Enabled row and click OK.
- Click the Save button.
32.5.6. Updating Deployment Content
- Click the Inventory tab in the top menu.
- Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss Enterprise Application Platform 6 server.
- Open the DomainDeployments folder (for standalone server use the Deployment folder), and select the web application to update.
- On the web application details page, open the Content tab, and click the New subtab.
- Click the UPLOAD NEW PACKAGE button.
- Click the UPLOAD FILE button.
- In the pop-up window, click the Add button, and browse the local filesystem to the updated content file to be uploaded.
- Click the UPLOAD button.
- Select the repository where the web application package should be stored. While this is not required, it is beneficial to store the updated package in JBoss ON so that it is available to other JBoss EAP 6 deployments.
- Fill in the version information.
- Confirm the details for the new package, then click CONTINUE.
When the package is successfully uploaded, the UI redirects to the history page on the Content tab.
Figure 32.16. Deployment History for a Resource
32.5.7. Deploying Web Applications to a Standalone Server
The standalone server uses a specific, filesystem directory as a deployment directory. As with domain deployments, content can be deployed by creating a child resource. However, because of the simpler structure of the standalone server, content can also be deployed through content bundles. Bundles provide simplified update and revert paths, as well as a clearer versioning system.
32.5.7.1. Deploying a Web Application as a Child Resource
Important
New deployments may not show up in the JBoss ON inventory for a few minutes or for as long as 24 hours, even if it was successfully created. This is because the new resource must be discovered by the agent after it is created for it to be added to the inventory. By default, discovery scans for services are only made every 24 hours.
To see it immediately, run an execute prompt command operation on the agent and enter the discovery command. This runs a discovery scan.
- Click the Inventory tab in the top menu.
- Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss EAP 6 standalone server.
- Right-click the standalone server entry in the navigation tree.
- In the Create New menu, select the item for Deployment.
- Enter the version number.
- Upload the EAR, WAR, or JAR file.
- Optionally, enter a runtime name for the deployment.
- At the bottom of the wizard, set an optional timeout period. This is how long the JBoss ON server will wait during the deployment process before determining that the deployment has failed.NoteThe timeout period only applies to the server's reporting a result. If the operation continues running, it can still complete successfully, and the web application is deployed.Particularly for large application files, do not set a low timeout period, or the server will mark the deployment as having failed. If the deployment completes later, the web application must be imported into the inventory manually; it will not be discovered by the agent.
- Click Finish.
32.5.7.2. Deploying Web Applications Through Bundles
Creating bundle archives and recipes, defining destinations, and managing bundle versions are described in Chapter 27, Deploying Content and Applications Through Bundles.
- In the top menu, click the Bundles tab.
- Upload the distribution file, and go through the deployment wizard to create the bundle version.
- Scroll to the bottom of the window and click the Deploy button.
- Select the bundles to deploy.
- Define the destination information for the JBoss standalone server. A destination is a combination of a compatible group (containing the JBoss resource) and the directory to which to deploy the bundle.
- Complete the deployment wizard, setting any require properties.
32.5.8. Tracking Content History and Reverting Changes
The deployment history page tracks changes to a content-backed resource, meaning it lists all update attempts, timestamps, and version numbers.
Figure 32.17. Deployment History for a Resource
Web applications deployed to standalone servers through the bundles provisioning system have a straightforward path to revert changes. There is a Revert button on the details page for the latest deployment which goes back to the immediate past deployed version.
Deployments to a server group or domain, however, do not have the same clear path. Any attempt to revert a content deployment ultimately means to replace it with a different version.
There are options for how to change the package when a direct reversion is not possible:
- If the domain deployment or server group deployment is associated with a content repository, then upload an updated package to the content repository and sync the change over to the associated resources.
- Upload an updated package to the domain deployment and use the deploy to group operation to send the updated package to the server groups.
32.5.9. Versioned Deployments and Subdeployments
JBoss ON 3.3 and the JBoss ON JBoss Enterprise Application Platform 6 plugin supports Versioned Deployments (e.g. EARs, WARs, etc) and Subdeployments (e.g. WARs, SARs, JARs, EJBs, etc within EARs) in both managed deployments and standalone deployments of JBoss Enterprise Application Platform 6. A Versioned Deployment (or Subdeployment) exists when an artifact's version is incorporated into it's name (e.g. myapp-1.0.war, myapp-1.1.war, myapp-2.0.war). By default, when an artifact is recognized as a Versioned Deployment (or Subdeployment), its version number is stripped out and the resource matching that name in the inventory will be updated or created with the specified version number.
For example, if there is an artifact "myapp-1.1.war" being deployed, the JBoss ON JBoss Enterprise Application Platform 6 plugin will look for a resource named "myapp.war" in the inventory and reset the version number to "1.1". Otherwise, a new resource named "myapp.war" will be created with a version number of "1.1". The benefit to this approach being that JBoss ON can track versioned artifacts as a single resource (e.g. myapp.war) as opposed to multiple, distinct resources (e.g. myapp-1.0.war and myapp-1.1.war). This also enables all historical data for a resource to remain intact as well as avoiding previous versions of a resource being seen as permanently in the "DOWN" state.
JBoss ON by default uses "Maven-style" versions for artifacts. This requires that the version stamp be delimited by a dash and must contain at least a Major and a Minor version separated by periods.
JBoss ON uses the following regular expression by default:
^(.*?)-([0-9]+\\.[0-9].*)(\\..*)$
Note
Artifacts not matching the versioning scheme will be seen as distinct resources. For example: myapp-1.war, myapp-2.war, myapp1.war, and myapp2.war would be seen as 4 distinct resources.
Note
To disable Versioned Deployments and Subdeployments, the versionedSubsystemDiscovery parameter may be disabled in the JBoss ON JBoss Enterprise Application Platform 6 plugin. For updates to this property to have any effect, it must be updated on every applicable Agent prior to its startup.
32.5.9.1. Existing Resources
On first start up, the Agent will attempt convert any existing resources matching the version scheme. Additionally, if multiple versions of the same resource are simultaneous deployed (e.g. myapp-1.1.war and myapp-2.0.war), JBoss ON will attempt to upgrade them both to the same logical resource (myapp.war). To resolve issues in cases like this, unnecessary resources should be uninventoried, or Versioned Deployments should be disabled prior to any upgrades.
Note
When utilizing Versioned Deployments, the MISSING Policy should be set as DOWN (the default). Changing this setting may result in resources being removed or ignored during the update window while updating versions.
32.5.10. Troubleshooting Deployments
- Q: My deployment says it failed, but when I tried to redeploy the package, it fails because it says the resource already exists.
- Q: I tried to deploy a package to a server group and it seemed to be successful, but I don't see the deployment listed.
Q:
My deployment says it failed, but when I tried to redeploy the package, it fails because it says the resource already exists.
A:
One possible cause is the timeout setting when the package was originally deployed. The timeout period sets how long the JBoss ON server waits before assuming the deploy operation failed — it does not actually stop or limit the deploy operation itself. Even if the operation hits the timeout limit, the operation can still complete successfully, which successfully deploys the web application.
If the operation times out, then the agent will not discover the new resource automatically. The web application must be imported into the inventory manually.
Q:
I tried to deploy a package to a server group and it seemed to be successful, but I don't see the deployment listed.
A:
There are a couple of possible causes:
- The agent discovery scan hasn't run. There can be several hours between discovery runs, so it can take awhile for the application to appear in the discovery queue. To work around this, run a discovery scan on the agent.
- The package has already been deployed to the domain. Creating a deployment child on a server group actually attempts to create the deployment on the domain (where the content is stored) and then deploys it to the server group. If the package already exists in the domain, then attempting to re-create the deployment on the server group fails as a duplicate.In this case, use the deploy to server group operation on the domain controller to deploy the application.
