This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

Java Web Application Tier

On the Apprenda Platform, all Java Web Application components are required to be packaged as Java Web Archives (WARs). When a deployment of one of these types of components is initiated, there are two steps, described in greater detail below, that occur when a Java Web App is deployed or otherwise managed on the Platform.

  • The Java Web Archive is deployed to a servlet container.
    Any Linux server that is part of the Apprenda Platform is a valid target for this type of workload.  During installation, the Apprenda Installer asks the user to denote Linux servers that will be part of the installed Apprenda environment and ensures that they are configured appropriately.  On these servers, Tomcat 6, Tomcat 7, and, on some Platform installations, JBOSS can be used as the Platform’s servlet container. During instance deployment, your Web Application Archives are deployed to an instance of one of these servlet containers (depending on configuration specified by the Development Team or Platform defaults) on a given Linux server.
  • The Apprenda Load Manager is configured to direct traffic to the actual Linux server(s) hosting the application.
    Because there can be a number of Linux servers hosting your application instances, there needs to be a Load Management layer (best described as a reverse proxy).  This server is responsible for responding to all inbound traffic for the Apprenda instance.  Apprenda uses Application Request Routing (ARR), an add-on to IIS, to route requests to the Linux server that is actually hosting your application's UI.  Like standard Linux servers, the Load Manager server (or servers) are chosen and configured appropriately during installation.

The specifics of this routing and how Apprenda chooses the initial server for deployment are discussed in the next few sub-sections.

Application URLs

Before discussing what happens when Apprenda deploys your Java application, we'll cover how the URLs used to access the Java Web App of your application are constructed. Apprenda bases your application's URL on your application's alias. This alias, coupled with the application version alias and Apprenda Root URI, is used to direct all incoming requests to your Apprenda application. 

Please Note: an application's version alias is only used in URLs of applications in the Sandbox stage in order to differentiate different versions of the same application that may be accessible in the testing Sandbox at the same time; there can be only one Published version of an application at a time, though, so the app's alias is not used in URLs for accessing the Published application version.

Apprenda supports two patterns for accessing your user interface:

  • Subdomain: http[s]://$applicationAlias[--$versionAlias].$ApprendaRootUri
  • Path: http[s]://apps.$ApprendaRootUri/$applicationAlias[--$versionAlias]

The pattern must be selected prior to deployment of the application by the Development Team that publishes the application. The default pattern can be specified for new applications by the Platform Operator. In the patterns above, items in square brackets denote optional items. In the case of http[s] this denotes an SSL connection. Apprenda will automatically redirect non-SSL traffic to SSL if SSL connections are enforced by the Platform Operator. In the case of the [--$versionAlias], traffic will route to the Published version of the application if the specific version is not defined in the URL. Note that this moniker permits multiple versions of an application to be in the Sandbox stage at the same time.

Suppose one wishes to access Version 2 of an Apprenda application called Northwind, which was deployed to an Apprenda instance available at contososoftware.com; they would use the following URLs:

  • Subdomain: http://northwind--v2.contososoftware.com
  • Path: http://apps.contososoftware.com/northwind--v2

If and only if Version 2 is in the Published stage, they could access Version 2 of the application with the following URLs:

  • Subdomain: http://northwind.contososoftware.com
  • Path: http://apps.contososoftware.com/northwind

Custom URLs

Apprenda can configure your application to respond at the URL of your choice (configured in the Developer Portal). When a custom URL is specified, the appropriate bindings are configured on the websites so that they resolve the URL. No other intervention is needed, although the Network Administrator must point this URL to your Apprenda instance so that it can properly resolve DNS for the custom URL. 

For example, assume that Contoso wishes to make the Northwind application available online at northwindonline.com. When configuring the application, their Development Team would specify the custom URL as "northwindonline.com"; the URL used to access the application would then be:

http://northwindonline.com

Deployment Mechanics

Deployment of your Web Application Archive can be triggered by any of the following events:

  • Your application is promoted to the Sandbox or Published stages (and Scaling settings for the component are not set to "0")
  • Either a Platform Operator or Development Team relocates or replicates the Java Web App
  • During a sweep to enforce Scaling settings, Apprenda finds that an instance count is below what is required by an existing setting

The following tasks must complete in order to deploy the application onto the instance (some will occur concurrently):

  • Apprenda chooses a Linux server (for more information on this process, please see here)
  • Apprenda bootstraps the Java Web Application
  • A private application server instance is started and configured on the target node
  • The Java Web Application is deployed to the Linux server instance
  • The Load Manager is configured

The remainder of this section covers the latter four steps in more detail.

How Apprenda Bootstraps the Java Web Application

Once a server has been selected to host the Java Web Application, Apprenda will:

  • Create a new directory on the server to store the extracted application archive (WAR), located at /apprenda/instances/$instanceId.
  • Configure a new instance of the application server with its own configuration and a current directory in the instance directory.
  • Add Apprenda-specific libraries to the application server.  For Tomcat, these libraries are copied to the 'lib' directory; for JBoss, the Platform configures additional "JBoss Modules" that the Apprenda bootstrap and guest applications depend on.
  • Modify the application server configuration to property initialize bootstrap components.  For Tomcat, this involves modifying the server.xml configuration; for JBoss, it involves changing the subsystem configuration (e.g., standalone.xml).
  • Copy the extracted application into the correct subdirectory in the application server instance directory (e.g., '/webapp' for Tomcat, '/deployments' for JBoss).
  • Merge in anything located in the “merge” directory included in the archive (this directory should have a shadow directory structure that mirrors that of the extracted WAR directory).
  • Modify all .xml and .properties files to apply live/local switching and token replacement.
  • Replace any log4j configuration files with Apprenda's own Platform logging configuration.
  • Merge in context.xml and tomcat-users.xml files provided in the archive, if present.
  • Apply Environment Variables, System Properties, and runtime flags from the Deployment Manifest to your process.
  • Install Platform certificates and any applicable custom certificates into the application’s private trust store.

Application Server Installation/Configuration

During the Java Web Application bootstrapping process, a private application server instance is installed to the target machine to handle hosting duties for the Java Web App instance; no additional configuration is needed.  Any necessary configuration is set according to previously-selected settings defined in an application's Deployment Manifest, through its configuration in the Developer Portal, or through Platform Operator-defined settings in the System Operations Center (SOC).

How Apprenda Configures the Load Manager

DNS or HOST file entries result in all inbound traffic being routed to the Load Manager. Apprenda creates the necessary ARR URL re-write rules to break down the requested URL for the application and forwards it to the appropriate Linux server chosen above that is now hosting the application. Custom URLs, if specified, are re-written here as well.

So that the Load Manager may also host Apprenda applications, Apprenda uses internal ports when the request is forwarded from the Load Manager to the web server hosting the application (which may or may not be the same server). By default, the primary web server's processing of URLs occurs on Port 80 and the internal port used for forwarding the request is Port 8080. Stated differently, all Java Web Apps deployed by Apprenda respond to Port 8080.

To secure actions involving sensitive data such as login and application usage in general, Apprenda supports SSL natively and seamlessly with no further action needed by the application Developer. Apprenda will automatically configure a wildcard security certificate on all Linux servers participating on your Apprenda instance. Whereas ports 80 (and 8080 internally) are used for your http connection by default, ports 443 will be used for your https connection by default. To ensure better performance, Apprenda terminates external SSL connections at the Load Manager server using the ARR module and uses http connections internally. This strategy of SSL traffic management is known as SSL Offloading and is a common technique to route HTTP traffic among servers that inherently trust one another.

Java Web Applications on Apprenda are not considered durable resources. In other words, a server may go offline either in a planned or unplanned scenario. To provide high availability for Java Web Apps (and assist with performance under high load), Apprenda natively supports the replication of the Java Web App on multiple servers. If the deployment request is to replicate the Java Web App, Apprenda will create a web farm in IIS on the Load Manager server, and route requests through the web farm. This web farm is updated when one subsequently removes, relocates, or again replicates the Java Web App in a future action.

Apprenda's Authentication Gateway

Note: This section applies only to applications requiring authentication.

Once a Java Web Application is deployed on Apprenda, it can start accepting HTTP requests. Apprenda uses cookies to manage authorized interactions with the User's browser. When a browser makes a request and doesn’t provide Apprenda with a well-known cookie, Apprenda’s HTTP pipeline requests that the User authenticate. Login is either conducted through a special website controlled by Apprenda called authentication, or by supplying claims as part of a SAML or WS-Federation token if the environment and Tenant are configured to support Federated Identity.

Once the User provides authentication information, this creates an active session on the entire Apprenda system (this session is omnipresent and has nothing to do with HTTP) and creates an encrypted, tamper-proof cookie that is used as a trust token for future requests. A screenshot of the cookie (as per Chrome Developer tools) can be seen in the illustration below:
 

When the User logs in and an Apprenda session is created, Apprenda also establishes an inactivity window (configurable by the Tenant's Company Administrator); if the User is inactive for some period of time beyond the established inactivity window, the session is expired. The cookie is subservient to the Apprenda session, so even if future requests have a valid Apprenda authorization cookie, the request will be rejected and the User will be required to log in.

Web Farms

In Apprenda, web farms are created when a new Java Web Application partition is deployed to a new Linux server, effectively creating another copy of the Java Web App. When a Developer or Platform Operator sends a request for a new Java Web App deployment, Apprenda does the following:

  1. Apprenda will deploy a new copy of the Java Web App to a Linux server that is currently not hosting this application.
  2. The Load Manager service will be notified of this new deployment and take the following actions:
    1. Create a web farm in IIS for this particular application if there is none. If there is a web farm available for this application, the new server will be added to it.
    2. Modify the rewrite rules to route requests for that application to the web farm.

Diagram of the Java Web Application Tier with a Web Farm

The following steps represent the path taken by the request across the Java Web App tier of the Apprenda instance when a web farm is in place:

  1. A request is received for a particular application.
  2. The request is forwarded to the Load Manager server, which is where the root URL is pointing to.
  3. The Load Manager server has the Application Request Routing (ARR) module installed, which handles the rewrite and forwarding of the request.
  4. ARR will rewrite and forward the request to the web farm. The web farm will choose a server to handle the request using a Round Robin strategy.

Deploying a Java Web Application with Multi-tenancy

Thus far you've learned general details about how Apprenda deploys Java Web Applications, but with a multi-tenant deployment there are additional considerations to be aware of.

Java Web Application Multi-tenancy

Like .NET services, user interfaces, and databases, Java Web Applications should be designed as though one and only one Tenant is using the Java Web App at any particular time (as though it were deployed on-the-premises). Apprenda will deploy your Java Web Apps in a multi-tenant fashion at deployment time as specified by the Commingled sharing model, where one Java Web App serves the web requests of multiple Tenants, and many Tenants share the same memory and process.

Each process that hosts your Java Web App instance is a partition, so each partition corresponds to the process. 

Application URLs

For Commingled Java Web Apps, this is no different than single-tenant applications.

Deployment Mechanics

For Commingled Java Web Apps, this is no different than single-tenant applications.