Application Fundamentals

This page describes the structural expectations of applications on the Platform and how the Platform will deploy these applications. Before continuing, you should have an understanding of the key concepts of the Platform.

Application Structure

A Platform application will typically follow some form of a service-oriented design pattern consisting of user interfaces, business logic services, and persistence mechanisms architected in a well-defined manner. The compiled application artifacts (user interfaces, web services, database schema declarations, or any combination of those pieces) are bundled into a specially structured ZIP (.zip) file called an Apprenda Archive.  

An Apprenda Archive contains the binaries, SQL scripts, configuration, static content, and other resources that make up the application, all ordered in a structure of directories that can be parsed by the Platform. This archive file is uploaded to the Platform in the Developer Portal and provisioned by the Platform across one or more physical servers as a single application instance to handle the aggregate load of the application’s users. All the code in a single archive (.zip) file is considered to be a single application.  The pieces of the application are inspected and determined by the Platform as one of the following based on their content and location in the archive:

  • A .NET user interface - ASP.NET, ASP.NET MVC, static HTML + Javascript, etc. contained in the archive.  The Platform knows how to install a user interface as a website or web application in IIS
  • A .NET web service - Self-hosted Windows Communication Foundation services. These binaries are class libraries that contain the service contracts and implementations for web services that typically contain application business logic.  The Platform knows how to configure these services, and distribute instances of them across physical servers to accommodate aggregate processing needs of the application and user base demands
  • A Windows service - As needed, Windows services can be deployed as part of a guest application and consumed via the API. See more about including Windows Services in your application
  • A Java web application - Any application that can be packaged as a WAR will automatically be deployed as a Java web application. The Platform can  install, configure, and run WARs on top of Application Servers such as Tomcat. See more about supported Application Servers
  • A database schema script for application provisioning - A .sql script file that contains the SQL code necessary to create the application’s database in SQL Server or Oracle Server. At deploy time, the Platform executes this schema script to create a database that will store the application’s data.  Additionally, the Platform transforms the schema so that it will facilitate multiple customers, whether they be “commingled” into the same physical database (but kept separate at runtime, of course) (Currently only available for SQL Server), or “isolated” from each other in separate physical databases or schemas.  The decision of “commingled” vs. “isolated” is a deploy-time decision made in the Developer Portal or the usage of the Deployment Manifest. The database schema for application provisioning need only represent a single instance of the database
  • A database schema script for customer provisioning - A .sql file that contains the SQL code that will be executed on behalf of every customer that “onboards” to the application. At customer “onboarding,” the Platform executes this script on behalf of the customer, to pre-populate their “slice” of the multi-tenant database structure with standard or default data. For instance, this customer provisioning script might contain the default values for application settings that should start the same for every customer
  • A Linux Service - A generic Linux executable, can be any application that is launched through an executable file (e.g. shell scripts, C-compiled native code, Ruby, python, etc.). You are able to configure your Platform to deploy Linux Services in Docker containers. See more about Linux Services and configuring Docker.
  • A Kubernetes pod - a Pod definition. The Platform is capable of connecting to an existing Kubernetes cluster and can configure Pod definitions to deploy your applications onto the cluster. See more about adding a cluster and deploying pods.

The application’s architecture and archive structure will vary depending on the functional requirements of the application. It’s possible that the application will contain a user interface and database schema, but no business logic encapsulated in WCF services. Alternatively, the application may contain only WCF web services for use by remote clients, but no user interfaces or database schema.

To create your application’s archive (.zip file), use the Apprenda Archive Builder that is installed with the SDK or see our page on creating application archives.

Application Lifecycle

With an understanding of application structure, let’s look at how the components of the application are provisioned on the infrastructure of your Platform instance. Applications can be uploaded to the Platform through the Developer Portal interface, the Apprenda Cloud Shell command line interface, or the Developer Portal API. Using one of those three interfaces, you can create, configure, and provision your application on the Platform as well as define other important information about the application.

Once on the Platform, applications can move through the Platform application lifecycle that consists of four ordered stages: Definition, Sandbox, Published, and Archived. Each stage infers different characteristics about how your application is deployed, and controls which operations can be conducted against the application in the Developer Portal.

An important concept to understand before talking about the application lifecycle is application visioning. Applications on the Platform can have multiple versions. The first version is created by default when a new application is made and uploaded to the Platform. You are then able to make subsequent versions of the same application that can be moved through the application lifecycle on the Platform. Versions can be used to test new features and make updates to your application without affected the version that your users are using. You can create a new version by patching an on Platform application


This is the first stage of a product version. If you create the product, Version 1 will be created automatically at this stage. Future versions of your application created by patching an existing version will start at this stage as well.

In the Definition stage, the application’s binaries and resources are considered volatile and the Developer may change them and overwrite them until they are ready to be “promoted” to the next Lifecycle stage, which in this case is the Sandbox stage.

During this stage, application configuration and metadata such as Features, Editions, and Securables may be specified. 

The Platform does not provision any application components to the infrastructure while the application version is in this stage.


When the application archive has been uploaded or a patch to the application’s components has been applied, the Developer may “promote” the product version to the Sandbox stage.

At promotion, the Platform analyzes, validates, and provisions your application’s components as needed. Each user interface and the database is provisioned to IIS, Tomcat, SQL Server or Oracle Server respectively if defined in the archive. It also prepares any discovered WCF web services for deployment as standalone self-hosted WCF services.

Changes cannot be made to the application’s components in this stage. If more changes are needed to the application’s components, the version can be “demoted” back to the Definition stage. Note that the Platform provisions test versions in a volatile way, meaning that once the stage is changed the provisioned application components used for Sandbox are destroyed, including all data and Sandbox subscriptions. 

This stage permits Developers to test their application as if they were Tenants.  If the application has been deployed as a multi-tenant app, the Platform also automatically onboards the Developer as a subscriber to their own application. The person who conducted the promotion operation is automatically assigned a subscription to the application and can use the Account Portal to launch the application, manage security, assign subscriptions, and obtain additional subscriptions to experience the application from the Tenant point of view.


After the application has been tested and is ready for live use, the Developer may promote the product to the Published stage. 

At promotion, the Platform removes the components provisioned during the Sandbox stage and provisions all of the components in a way that is consumable by the Developer’s subscribers, honoring any SLA options and deployment settings (such as tenant isolation policy). 

Applications in the Published stage are generally “locked” in this stage, although entitlement information may be changed. To make changes to the application at this stage, it is necessary to patch the application, which is discussed in the next section.

If the application has been deployed as a multi-tenant app, at this point Tenants can be granted subscriptions to the application and manage them, along with associated subscription information and security settings, using the Account Portal. Developers may monitor and adjust their application’s provisioning characteristics in the Cloud Control area of the Developer Portal.


When a patched version of an application enters the Published stage, the previous Published version is automatically “promoted” to the Archived stage. The Archived version’s components, metadata, and entitlement information is preserved for reference at this stage.

Patching an Application

Due to the necessity of a bug fix or the introduction of additional functionality, you will likely need to update most applications after their initial version has been placed in Published. The Platform offers built-in patching capability to implement such changes.

When creating the new version of the application, all of the application components and metadata from the parent version in the Published stage are copied. These items can then be modified or deleted. New application components (e.g. new WCF services) that did not previously exist can be added as well. Database schema changes and changes to the underlying data can be done as well but must be done by specifying patch scripts.

The new version of the application can be promoted to the Sandbox stage, even though its parent version is in Published. The Published version will behave the same way until the new version is promoted to Published. 

For multi-tenant apps, all entitlement information from the previous version is copied as well, and modification restrictions are placed on those Entitlement Definitions to ensure that all subscriptions from the parent version can be migrated to the new version of the product when it is promoted to the Sandbox stage.

Note: Application entitlements can be changed at any time; updating them does not require a patch to an application.