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 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.
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.
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.
This diagram illustrates how these components and configuration files should be organized into an Apprenda Application archive:
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).
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.
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.
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:
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 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.
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:
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.
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.
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.
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:
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.
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:
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).
Please see the Data Tier section of our deployment documentation for more information on how and when patching scripts are applied.
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.
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.