This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

User Interface Tier

For any .NET application deployed to the Apprenda Platform, besides application data and services, Apprenda natively manages the deployment of your user interfaces to the Apprenda instance. There are two steps, described in detail further below, that occur whenever a user interface is deployed to or otherwise managed by Apprenda.

  • The user interface is deployed to one of the web servers. 
    Any Apprenda server that has Internet Information Services (IIS) and Apprenda's User Interface Manager service running is designated as a web server. During installation, Apprenda asks the user to denote which servers should be used for hosting user interfaces and ensures that they are configured appropriately.

  • The Apprenda Load Manager is configured to direct traffic to the actual web server hosting the application UI.
    Because there can be many web servers hosting application UIs, there needs to be a Load Management layer. 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 web server that is actually hosting your application's UI.  Like standard web servers, the Load Manager server (or servers) are chosen and configured appropriately during installation.

It should be noted that (as long as certain environmental conditions are true, such as shared IIS configuration not being enabled) the Load Manager server can also be configured as a web server for .NET applications; this is common for single-node and smaller instances of the Apprenda Platform. The only difference in this scenario is that traffic for a given user interface may simply be redirected onto itself. Alternately, the Load Manager server runs independently and need not participate in the Platform instance in any other capacity, which is useful for high-availability scenarios.

The following diagram illustrates how all incoming web requests are handled for your Apprenda application. 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 .NET application, we'll cover how the URLs used to access the user interface 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 a user interface can be triggered by any of the following events:

  • An 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 web application
  • During a sweep to enforce Scaling settings, Apprenda finds that an instance count is below what is required by an existing setting

The following steps must occur to deploy the application onto the instance:

  1. Apprenda chooses a web server
  2. Apprenda bootstraps the user interface
  3. IIS is configured
  4. The Load Manager is configured

The remainder of this section covers each of these steps in more detail.

How Apprenda Chooses a Web Server

Please see here for more details.

How Apprenda Bootstraps the User Interface

Once a server has been selected to host the user interface, Apprenda will:

  1. Create a new folder on the server to store the UI binaries, usually located by default at C:\ApprendaPlatform\SiteData\$applicationAlias\$versionAlias\root. 
  2. Copy the binaries (previously uploaded or patched) to the new folder that was just created.
  3. Copy bootstrap assemblies from the Apprenda Repository into the bin folder of the site, so that the necessary dependencies for your application to run on Apprenda are available.
  4. Modify Web.config and other configuration files to:
    • Re-configure all WCF clients to address their services via Apprenda's router (for those that are hosted on Apprenda).
    • Configure Apprenda’s ASP.NET authentication gateway and configurable login screen at the front of the HTTP pipeline (unless authentication is not required for your application).
    • Apply token replacements and conditional configuration directives as required.
  5. Record and catalog information regarding the user interface as required for tracking and management by the Platform.

How IIS is Configured

Now that the user interface's binaries are present on the machine chosen to host the UI, Apprenda's User Interface Manager will dynamically configure IIS on the machine. 

A new web site is created in IIS, either at the root level or beneath the built-in apps.$ApprendaRootUri site depending on the URL format specified for the given application.

If the application uses a subdomain, a binding is added so that it can respond to incoming traffic at the site's URL. Path-based applications need no binding, and Apprenda will set the name of the application appropriately so the site is resolveable to incoming traffic.

Note that all traffic comes inbound to the site on Port 8080 by default. The Load Manager will listen to traffic on Port 80 and 443 and redirect traffic to the appropriate site. This permits a server to host both the Load Manager and UIs. Load Manager configuration is discussed below.

The new user interface is linked to a new application pool. This isolates the activity of one user interface from other UIs on the server instance. This provides a safeguard, since if the user interface experiences a crash, it will not affect other UIs while IIS deploys a new worker process. Additionally, Apprenda will throttle the memory usage and/or processor usage of the user interface if it was deployed using a specific Resource Policy.

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 web 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 user interfaces 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 web 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 primary web 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.

UIs 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 user interfaces (and assist with performance under high load), Apprenda natively supports the replication of UI on multiple servers. If the deployment request is to replicate the UI, 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 UI in a future action.

Apprenda's Authentication Gateway

Note: This section applies only to applications requiring authentication.

Once a user interface 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.

Multiple User Interfaces

All sections in the User Interface Tier topic to this point assume that your Apprenda application contains exactly one user interface. In Apprenda, this user interface is known as the root UI. Notice that this same name is used in the application archive structure and as part of the folder path when partitions are created. 

It is possible, however, to have multiple user interfaces inside of a single Apprenda application, and Apprenda will manage and deploy them all for you. The key difference, however, is that a virtual directory will be created beneath the physical website. The name of the virtual directory will be the same as the name of the folder indicated in the application archive or patch, as illustrated in the following example.

Application Archive Folder Name Sample Web Address
~\interfaces\root http://northwind.contososoftware.com
~\interfaces\goods http://northwind.contososoftware.com\goods
~\interfaces\services http://northwind.contososoftware.com\services

Web Farms

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

  1. Apprenda will deploy a new copy of the UI to a web 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 User Interface Tier with a Web Farm

The following steps represent the path taken by the request across the web 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 User Interface with Multi-tenancy

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

User Interface Multi-tenancy

Like .NET services, Java Web Applications, and databases, user interfaces should be designed as though one and only one Tenant is using the UI at any particular time (as though it were deployed on-the-premises). Apprenda will deploy your UIs in a multi-tenant fashion at deployment time as specified by one of the available sharing models:

  1. Commingled: One user interface serves the web requests of multiple Tenants. Many Tenants share the same memory and process.
  2. Isolated: There is one user interface per Tenant, providing memory isolation (many Tenants still share the same process, however).

Recall the notion of partitions and shards, which are necessary constructs for the Platform to scale guest applications to multiple servers. For the purposes of user interfaces, they take on the following meaning: 

  • Partition: Each process that hosts your user interface instance is a partition.
  • Shard: Each UI instance reserved for a specific Tenant is a shard

Regardless of the sharing model chosen, many Tenants share the same process. Therefore, each partition corresponds to the process. Only one process for the same application version will run on the same server, guaranteeing only one partition per server for that application version. 

Shards only apply to the Isolated sharing model. Web requests for each Tenant are directed to the specific user interface created on one of the partitions. In the Commingled model, web requests are directed to any available partition.

Application URLs

For Commingled UIs, this is no different than single-tenant applications; this section deals with how the URLs used to access the user interface of your application are constructed for Isolated UI deployment.

Apprenda bases your application's URL on your application's alias. This alias, coupled with the application version alias, tenant alias and Apprenda Root URI, is used to direct all incoming requests to your Apprenda application.  Apprenda supports two patterns for accessing your app:

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

The pattern must be selected prior to deployment of the application by the Development Team that publishes the application. 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 set to be 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 a Tenant whose alias is fabrikam 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:

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

Friendly URLs

For convenience, it is not necessary to specify the Tenant alias. This yields more convenient URL names. For example, a Development Team can circulate the same URL to all Tenants. For example, Fabrikam or any other Tenant can access the application using the following URLs:

When the Tenant visits the friendly URL, Apprenda uses session information for the logged-in User to transfer the request to the correct website. 

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 user interfaces so that they resolve the URL. No other intervention is needed, although the Network Administrator must point this URL to your Apprenda instance.

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

For Commingled user interfaces, this is no different than single-tenant applications.  For Isolated UIs, whenever a new Tenant subscribes to the application, the following workflow is followed:

  1. Apprenda chooses a web server
  2. Apprenda creates the partition if necessary
  3. Apprenda creates the shard for the newly subscribed Tenant
  4. The Load Manager is configured

How Apprenda Chooses a Frontend Server

Again, please see here for more details.

How Apprenda Creates the Partition

Note: This step only occurs if no partition exists yet on the web server that was just selected. 

Once a server has been selected to host the user interface, Apprenda will:

  1. Create a new folder on the server to store the user interface binaries of the application, located by default at C:\ApprendaPlatform\SiteData\$applicationAlias\$versionAlias\root.
  2. Copy the binaries (previously uploaded or patched) to the new folder that was just created.
  3. Copy bootstrap assemblies from the Apprenda Repository into the bin folder of the UI, so that the necessary dependencies for your application to run on Apprenda are available.
  4. Modify Web.config and other configuration files to:
    • Re-configure all WCF clients to address their services via Apprenda's router (for those that are hosted on Apprenda).
    • Invoke Apprenda’s ASP.NET authentication gateway and configurable login screen at the front of the HTTP pipeline.
    • Apply token replacements and conditional configuration directives as required.
  5. Record and catalog information regarding the partition as required for tracking and management by the Platform.
  6. Create the application pool for the partition.

How Apprenda Creates the Shard

Whether a new partition was created or not, the binaries for the user interface and the necessary application pool already exist at this point. Now, Apprenda's User Interface Manager will dynamically configure IIS on the machine. 

A new web application is created in IIS, either at the root level or beneath the built-in apps.$ApprendaRootUri web application depending on the URL format specified for the given application.

If the application uses a subdomain, a binding is added so that it can respond to incoming traffic at the site's URL. Path-based applications need no binding, and Apprenda will set the name of the application to the appropriate name so the site is resolveable to incoming traffic.

Note that all traffic comes inbound to the site on Port 8080 by default. The load manager will listen to traffic on Port 80 and 443 and redirect traffic to the appropriate site. This permits a server to host both the load manager and actual UIs. Load Manager configuration is discussed below.

The new user interface is linked to the application pool for the partition.

How Apprenda Configures the Load Manager

This is no different than single-tenant applications.

How Apprenda Handles Web Farms

This is no different than single-tenant applications.