Welcome to our docs site. Docs on this site are for ACP version 9.
See these links for previous versions: Version 8, Version 7

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. However, the Archive Builder and Apprenda Cloud Shell cannot be used to package Java Web Application (WAR) or Linux Service components of an application. Archives that require such components must be packaged manually, or in the case of a WAR file, can be used without packaging.

Apprenda Archives

Apprenda Archives are compressed ZIP (.zip) files that contain 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. In some situations, 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 can be included in archives depending on your Application needs.

Application components to include in an archive

The following is a list of application components that can be placed into an archive:

An archive only needs to contain one of these components in order to be accepted by the Platform as a valid archive, however, 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 can be run on the Platform, and ultimately 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 any persistence component. One existing restriction, however, is 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 to include in an archive

Note that only the Application Provisioning Script from the above list is required for all applications.

Archive Structure

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

WCF Services

Each individual .NET service should be 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

Each individual Windows Service should be 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). 

The name of each Windows Service as specified in the name of its individual Windows Service folder within the WinServices folder must match the service name specified in a Deployment Manifest included with the archive. The name of the executable must also match that specified in the Deployment Manifest.

.NET User Interfaces

All .NET user interfaces and their required files must be located within the interfaces folder. The first (primary) user interface must be named root. Any other user interfaces (e.g. administrator or mobile interfaces) must be contained within the interfaces folder with unique folder names (‘admin’, or ‘mobile’, for example).

If your application persists data, information is arranged in the persistence folder as described in the Persistence Scripts section.

Java Web Applications

If your application includes a Java Web Application archive (WAR), it must be included in a folder that is named exactly the same as the war. This folder must then be placed within a directory called wars created at the root of the archive (i.e., if the WAR is named “Calculator.war”, it must be included in a folder named “Calculator.war” that is then placed within the wars directory).  Please note that each archive should contain no more than one Java Web Application (WAR).

As needed, the following files can be included to configure Java Web Application components:

  • context.xml: this file can be used to provide a custom Tomcat configuration. It should be included in the individually named war folder (at the same level as the WAR file)
  • tomcat-users.xml: this file should be included in the individually named war folder (at the same level as the WAR file).  If included, it will be copied to Tomcat’s $instanceDir/conf/tomcat-users.xml (and will overwrite any existing file)
  • any additional configuration files can be placed in a folder named merge that is included in the individually named war folder (at the same level as the WAR file). These files can be of any type, and will be copied into the workload upon deployment (and will overwrite any existing file). The placement of the files within directories will be preserved, so to place a file in the workload’s /WEB-INF/classes, it should be placed in /merge/WEB-INF/classes

Linux Services

If your application includes a Linux Service, your Apprenda Archive must include a linuxServices folder. The linuxServices folder should any application binaries needed, and must always include “start”and “stop” scripts. The Application Archive for a Linux Service application must include a Deployment Manifest that references the named artifact-specific sub-folder.

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

Kubernetes Components

Kubernetes pods can be included 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 definition file to create an application on the Platform without creating a full archive.

Databases

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.

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

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

For deployment on a live Apprenda Platform, you can include an optional DeploymentManifest.xml file. If you do include this file in your application archive, Apprenda will attempt to extract meta-information about your application settings, any options to be applied to your application’s schema, and any specified Features, Securables, and Entitlement Definition (if applicable).  Apprenda will use this information to automatically populate the corresponding portions of your application’s Definition in the Developer Portal. While doing this, Apprenda will not delete any existing Feature or Securable definitions, nor will it synchronize new items with existing items.  It simply adds any new items that it finds in the configuration file to your application’s Definition. This allows those persons responsible for packaging and uploading the application archive to help those responsible for defining the application get a head start on the process of building the application offering.  

** Please note: any Windows Services included in the archive must be accompanied by a DeploymentManifest.xml file that includes the required information noted here. Archives that contain Linux Services must also be accompanied by a DeploymentManifest.xml file that includes the required information noted here.

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.  This file must be structured in the same way as your initial archive upload, but should not include an application provisioning script (even if your application contains a data tier). 

Because components such as WCF services, Windows Services, .NET UIs, and Java Web Applications can easily be redeployed for new versions of an application, you can simply provide updated binaries for these components in a Patching Archive.  Because data for existing SQL Server databases and Oracle schemas must be preserved when patching, 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/9/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).

Please 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.