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

Creating Apprenda Application Archives

Once you've developed an application in a local development environment and are ready to deploy the application to a Platform, you will need to package your code as an Apprenda Archive (with the exception of WAR files or Kubernetes spec files). This page explains about application archives and the requirements for packaging an application to upload to the Platform.

Note that you can package .NET app archives by using Archive Builder or Apprenda Cloud Shell included in the Apprenda SDK, instead of doing it manually. The Archive Builder and Apprenda Cloud Shell cannot be used to package Java Web Application (WAR) or Linux Service components of an application. You must package archives that require Java or Linux Services (including Kubernetes Pods) manually, or in the case of a WAR file or Pod spec, can be used without packaging.

Apprenda Archives

Apprenda Archives are compressed ZIP (.zip) files that contain you application files organized in a pre-determined way. The Platform uses this known structure to traverse the archive and extract information it uses to deploy your application.

During the process of deployment, the Platform first validates the contents of your archive against a set of rules that are designed to guarantee that your application will run properly on the Platform in a secure and reliable fashion. The Platform then extracts and catalogs your application's files and resources and uses them as a foundation for serving your application to requesting Users.

Archive Size

By default the size limit on Apprenda Archives is 400 MB, but your Platform Operator may make configuration changes that allow for larger archives.

Building an Archive

To build an archive, you must organize the components of your application so that the Platform can understand it. In addition to the components of your application, there are some configuration and certificate files that you can include in archives depending on your Application needs.

Application components in an archive

The following is a list of application components you can package into an archive:

An archive only needs to contain one of these components for the Platform to accepted it as a valid archive, although most applications will consist of more than one component. A typical .NET applications will contain at a minimum one .NET service, user interface, and persistence script (and may contain a Windows Service) and most Java applications will contain at minimum one Java Web App and one persistence script.

The archive structure provides a lot flexibility in the types of applications that the Platform can run, and allows you to include only the components required by your application. For example, an application archive may contain .NET web services, Java Web Apps, and Windows Services in the same archive in addition to a persistence component.

Note that an application archive cannot contain both a .NET user interface component and a Java Web App component, since both attempt to define a presentation aspect for the app.

Application configuration files in an archive

The following is a list of configuration files and certificates you can include in an archive to help you define your application and provide the Platform with information about your application:

Archive Structure

This diagram illustrates how these components and configuration files should be organized into an Apprenda Application archive:

WCF Services

Place each individual .NET service in a separately named folder inside the services folder. The root of each individual .NET service folder should include the output from Visual Studio build process for that service (i.e. built DLLs instead of projects).

Windows Services

Include each individual Windows Service in a separately-named folder inside the WinServices folder. The root of each individual Windows Service folder should include the output from the Visual Studio build process for that service (i.e. a built executable file). 

If you are building an application with a Windows Service, you must include a Deployment Manifest. In the manifest, the service name specified for the Windows Service, must match the name of its individual Windows Service folder within the WinServices folder. The name of the executable must also match the one specified in the Deployment Manifest.

.NET User Interfaces

Place all .NET user interfaces and their required files in an interfaces folder. You must name the primary user interface root. Name any other user interfaces with a unique folder name inside the interfaces folder.

If your application persists data, put that information in the persistence folder as described in the Databases section.

Java Web Applications

If your application includes a Java Web Application archive (WAR), place it in a folder that is named exactly the same as the WAR. Include that folder within a directory called wars at the root of the archive. For example, if the WAR is named Calculator.war, place it in a folder named Calculator.war inside the wars directory.  

An archive can only contain a single Java Web Application (WAR).

Include the following files as needed to configure Java Web Application components.

  • context.xml: Use this file to provide a custom Tomcat configuration. Include it in the same folder as the WAR file (inside the folder named for the WAR file)
  • tomcat-users.xml: Included this file in the same folder as the WAR file (inside the folder named for the WAR file).. If included, the Platform will copy it to Tomcat's $instanceDir/conf/tomcat-users.xml (and will overwrite any existing file)
  • Place any additional configuration files in a folder named merge that is included in the same folder as the WAR file. These files can be of any type, and will be copied into the workload at deployment (and will overwrite any existing file). The placement of the files within directories will be preserved on Platform, so to place a file in the workload's /WEB-INF/classes, place it in /merge/WEB-INF/classes

Linux Services

If your application includes a Linux Service, your Apprenda Archive must include a linuxServices folder. Include the Linux Service in an its own folder inside the linuxservices folder. Each individual Linux Service folder should be named the same as the name of the service. Place all your application binaries inside a the named service folder in the linuxServices folder with "start"and "stop" scripts for the service. Note that "start"and "stop" scripts are required for all Linux Services and must always be included. 

You must include a Deployment Manifest in archives that contain a Linux Service. In the manifest, the service name specified for the Linux Service, must match the name of its individual Linux Service folder within the linuxServices folder.

Note, different requirements are placed on archives for Docker applications. See the documentation on Docker from more about these requirements.

Pods

Include Kubernetes Pods in a pods folder of the archive. The pods folder should include a component subfolder that contains the pod definition file as a YAML, YML, or JSON file. Only one Pod component is allowed per archive and you can not define a component for another HTTP routed component (such as .NET interfaces or a WAR) if a Pod is present. If you include a Deployment Manifest, it should reference the same Pod name as the component subfolder in the pods folder of the archive.

There are some limitations and requirements for Pod definitions, see more about creating and deploying pods on the Platform.

Alternatively, you can upload only the YAML/YML/JSON Pod spec file to create an application on the Platform without packaging a full archive.

Databases

As of Platform version 8.2.0, there are two database strategies for defining your application’s databases, using persistence scripts of Data Tier plugins. Note that Data Tier plugins can only be used for defining SQL databases. If you are running a Platform version before 8.2.0, you must use persistence scripts to define all application data storage.

Note: An application can only use one of the two methods, and once a strategy (or method) is chosen for the first version of the application, all subsequent patched versions of the application must continue using the same method of configuring the data tier.

Persistence Scripts (for SQL Server databases or Oracle schemas)

Scripts must be placed in a folder called scripts. If you would like to install CLR stored procedures for SQL Server databases, you can place the executables in a folder called binaries and the procedures will be installed when your application is deployed. 

The following scripts can be included in the scripts folder of your archive:

  • Application Provisioning Script:  this file is required to generate the database store that your application expects. It will be used to create the data structures for the application (tables, views, foreign key relationships, and so on). This is sometimes referred to the "application onboarding script" because it is used to get your application onboarded on to the Platform
  • Tenant Provisioning Script this file is optional and can be used  to populate the database/schema with data upon initial creation.  For that reason, this script is sometimes referred to as the "tenant onboarding script." The script is executed against your database/schema every time a new Tenant subscribes to the application. It can be used to pre-populate the Tenant's application with data, keywords, etc. 

For more information on conventions and considerations applicable to these scripts, please see the Working with Guest Application Data topic.

Data Tier Plugins

Available in Platform version 8.2.0 and later, Data Tier plugins allow you to use any ORM software, like Microsoft’s Entity Framework Code First Migrations, to configure the data tier of an applications.

To use a Data Tier plugin, you must implement several callback methods and include those assemblies in a folder called custom inside the persistence folder. If your implementation requires additional binaries, also place them inside the custom folder.

DeploymentManifest.xml file

The DeploymentManifest.xml is a configuration file that allows the Platform discover and pre-configure some basic application setup required for deployment. The Platform will use this information to automatically populate the corresponding portions of your application's Definition in the Developer Portal.

See the documentation on the Deployment Manifest for more about the configuration setting you can include and how to use it.

Note: Some component types require a Deployment Manifest to be included in a archive when they are present in the archive.

Application Vanity URL Certificate file

A TLS/SSL PFX certificate archive can be uploaded in the root of the archive for applications that will have a Application Vanity URL. Only Developers that have been granted the proper securable can upload a certificate in the application archive. The file must be placed in the root of the archive and, if present, the file name and vanity URL must be specified in the Deployment Manifest.

Noted that depending on how your Platform Operator has configured the Platform, certificates may be required, optional, or disabled for applications with vanity URLs assigned. You should consult your Platform Operator for more information on the requirements around certificates. Additionally, certificates with passwords cannot be uploaded in an application archive. If your application requires a certificate with a password for its vanity URL, you can upload the certificate through the Developer Portal after the application has been created on the Platform.

Automatic Archive Generation (for .NET apps only)

Apprenda .NET applications are traditional web applications backed by WCF web services. If you created your applications using the solution and project templates supplied with the Apprenda SDK, Visual Studio can automatically create an archive directory at the root of your solution when you build your applications using the Release build target. You'll still need to manually:

  • Copy your database schema scripts into the archive directory created at the root of your solution.
  • Zip the directory contents into a single ZIP file.

Application Samples

Archive samples can be found on the Downloads page or via the Download & Dissect More Samples link located on the Dashboard of the Developer Portal. 

Creating a Patching Archive

When creating a patched version of an application, you can implement the majority of changes to your application’s runtime binaries by uploading a Patching Archive in the form of a ZIP file. The Patching Archive must be structured in the same way as your initial archive upload, but should not include an application provisioning script if you used it as your initial database provisioning strategy

WCF services, Windows Services, .NET UIs, and Java Web Applications components can easily be redeployed for new versions of an application so you can provide updated binaries for these components right in a Patching Archive. Data for existing SQL Server databases and Oracle schemas, however, must be preserved when patching.

If you used Data Tier Plugins, see more on how patching works.

If you used provisioning scripts as your database provisioning strategy, changes to your application provisioning script must be made through patching scripts. This can be accomplished through a patching archive as follows:

  • Schema and data patching scripts must be included in the Scripts folder within the Persistence folder in an application archive.  
  • In order to take effect, they must be listed in the Deployment Manifest with the proper path and script type information as per the example below.
  • They should also be listed in the order in which they should be applied.

Sample DeploymentManifest.xml for DB Patching

<?xml version="1.0" encoding="utf-8"?>
<appManifest xmlns="http://schemas.apprenda.com/DeploymentManifest"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://schemas.apprenda.com/DeploymentManifest http://apprenda.com/schemas/platform/8.0/DeploymentManifest.xsd" >

<!--Valid values for persistencPatch type: "SchemaScript", "DataScript", "SharedSchemaScript" (mssql only), "SharedDataScript" (mssql only), "Binary" -->
  <persistencePatches>
    <persistencePatch path="\Persistence\Scripts\Schema\SchemaPatch.sql" type="SchemaScript"/>
    <persistencePatch path="\Persistence\Scripts\Data\DataPatch.sql" type="DataScript"/>
  </persistencePatches>
	
  <entitlementDefinitions>
    <entitlementDefinition name="Standard" isPublished="true" />
  </entitlementDefinitions>	
  
</appManifest>

An updated Tenant provisioning script can be included in your patching archive. Please note that changes made to Tenant provisioning scripts will automatically affect only new Tenants.  You can make changes to existing Tenant data through a data patching script.   Other than patch scripts for the application provisioning script and an updated Tenant provisioning script, you must omit any database scripts from your patching archive (other items, such as updated stored procedures, may be included).

See the Data Tier section of our deployment documentation for more information on how and when patching scripts are applied.

Patching Archives for Applications that use Oracle 12c 

Additional requirements for patching archives for applications that use Oracle 12c can be found on the Working with Guest Application Data section of our documentation.

Using a Java Web Application File in Place of an Application Archive

As an alternative to uploading an archive to create a new application on the Platform, a Java Web Application (in the form of a WAR file) with no external dependencies can be used instead.  This allows Developers to create simple Java applications on the Platform without going through the process of packaging their WAR in an archive. 

To use this feature, simply target your WAR file for upload when creating an application through the Developer Portal or the Apprenda Cloud Shell (ACS).  Note: WAR files cannot be used for patching.