Instruction

To create and test an application package in compliance with APS, perform the following steps:

Note: it is intended that you already have a working application.

1. Define type of an environment where the application is to be provisioned.

Application may dictate type of environment the Controller should provision it to in clear. On the other hand, the Controller may select an environment basing on application services hardware and software requirements. One may single out the following types of hosting environment:

• Shared environment - hosting environment is shared by instances of an application (multi-instance application);
• Dedicated environment - application states that only one instance can be ran in a hosting environment (single-instance application);
• External environment - hosting environment that is not managed by Controller, and application provisioning, in this case, is delegated to configuration script.

2. Define a model of service provisioning.

Selecting the provisioning model application vendor should consider the level of application management by Controller and application services hierarchy. Namely, one should correctly map application services on application. One may single out the following models of service provisioning:

• Multi-tenant - this model implies that a single instance of the application runs on hosting vendor servers, serving multiple client organizations (tenants). Tenants data and application configuration are stored separately. When a tenant logs in, an application instance respective configuration (customization) is applied and each tenant sees and manages only his data as if he is an application single user. So, in this model, application context is already exists in hosting environment and customers' data is stored within it separately.
• Single-tenant - this model implies that an application instance run on hosting vendor servers, serving only one tenant. In other words, a separate application instance is provisioned for each customer. Application files are simply copied to location dedicated to customer and data of all customer applications is stored within customer.

Note: both models can be implemented for shared environment and for dedicated one as well.

3. Define application structure.

An application may comprise main module and additional ones. The main module represents core functions, whereas additional modules provide extra services. For example, a content management application may come as a main module, and the skins or localizations may be offered as add-ons.

If your application has such additional modules, consider packaging them individually like a general package with dependency to their main module. In other words, metadata of packaged add-ons must reference to their master package, so the Controller could check whether the package is really an additional module to an application installed in hosting environment and its version meets condition (if any) in add-on's metadata file.

For details on packaging add-ons, refer to the 5.1.5. Master package reference section of the Specification.

4. Define application services hierarchy.

In general, an application purpose is to provide services to end-users. Application services hierarchy should reflect order of application services provisioning and level of application services management by Controller.

For example, let's consider multi-tenant application. The top-level application service represents a tenant. Under top-level service an application context is declared (second-level service) that is provisioned inside of the tenant. Then one may declare a number of application features (third-level services). Another way is to declare users and specify features for a user.

5. Define an application licensing procedure.

APS supports licensing applications by means of license keys. Each application instance or service may require license keys. To get keys, a well-formed license request should be send to respective authority. After the license is issued it is installed to the application.

If your application requires license to be installed, you should specify this in its metadata file. A special script should perform all involved operations, like querying application, installing and removing license.

For details on license requirement declaration, refer to the APS Licensing Aspect document.

6. Define technologies used by your application.

Your application may utilize various scripting languages, specific server modules, databases, mailboxes, DNS records in application domain and the like. Application technologies form the list of requirements to be satisfied to provision application. In general, requirements usually request some resource to be allocated or specific configuration to be performed.

A Controller can handle these requirements as qualified technologies – software, resources (e.g. databases, mailboxes or DNS records) or executable code described in the aspect included in the Specification. For details on aspects that describe qualified technologies, refer to the 8. Common aspects section of the Specification.

Note: If the application uses non-qualified technologies, write an aspect for each such technology and make it public. You may then submit a request to extend the Specification (recommended scenario), or otherwise include the information into the package release notes. This will help control panel developers to configure Controllers to provision the package properly. For details on what data should be included in an aspect, refer to the 7. Points of Extensibility section of the Specification.

Tip: For common understanding, please, use the terms given in the Specification.

7. Define presentation details and settings for application and its services.

Your package metadata may include details and settings of the application interface. If an application is multi-tenant, for example, it should meet requirements of a number of tenants that use this application for absolutely different purposes. In other words, the more settings you declare for an application, the more flexible it becomes. This way you may set up automated generation of setting values ensuring their uniqueness within the required scope. Some settings may be prefilled automatically with a Customer's login, password, email or domain of the application without requesting the data from end-user. For details, refer to the 5.1 Common Application Properties, 5.2 Services and 5.2.5 Service Settings sections of the Specification.

Tip: For common understanding, please, use the terms given in the Specification.

8. Define application content delivery method.

Content delivery method defines the way application files are deployed to hosting environment. For now APS allows using the following methods:

• Inside package - the method implies that package content does not require any special processing prior to its deployment. The Controller simply copying the very application files and directories from the package to a hosting environment specific location, according to URL mapping rules (if any specified).
• Inside PVC template - the method implies that application files are packed in PVC template that regulates application files deployment. For details on PVC templates, refer to the Parallels Virtuozzo Containers: Templates Management guide.
• Delivery is not required - the method implies that hosting environment already contains all necessary content and do not require any configuration. This method suits for provisioning external service.

9. Create a draft of metadata file.

Each package must contain a well-formed XML file (called APP-META.xml) that includes all the metadata required to manage the application. Metadata file includes application common properties like name, version, description as well as list of application services and resources required. The XML presentation of the metadata is described by the RELAX NG schema. Some schema elements are defined by aspects. It means that you must use aspects when adding the elements. For details on metadata file and its elements, refer to the 4.3. Metadata File and 5. Metadata Descriptor sections of the Specification.

10. Prepare scripts.

The Specification defines the following provisioning methods: URL mapping and configuration script. These methods are not mutually exclusive and are not interdependent. Thus, both of them can be declared for a service provisioning. URL mapping configures access to service through web, and configuration script performs service installation. The selection of method is determined by the hosting environment which is required for the Application. APS Package may contain multiple sets of requirements to meet the environment in case either set of requirements may not be satisfied. For details on provisioning methods, refer to the 5.3. Service Provision Methods section of the Specification.

You may develop a number of scripts that serve different purposes:

• Configuration script. It serves as method of service provisioning. Also, it is invoked by Controller on application instances configuration, removal, upgrade and enabling or disabling service. If an application has more then one service, separate configuration scripts may be implemented for each service. All resources required by a service must be allocated, instance files unpacked and placed to the file system before configuration script invocation. For details on configuration script invocation, its arguments and environment variables, refer to the 5.3.2. Configuration Script section of the Specification.
• Verification script. It serves to verify service settings for consistency, but it should never change state of application or its instances. Verification script has the same calling conventions as a configuration script, but does not support enable and disable arguments. Verification script is invoked twice: during installation and reconfiguration of an application. Initially, it is executed prior to prompting a user for setting values. At this stage the application settings receive auto-generated and default values. Second time it is invoked to validate the submitted settings values. If the return value is not zero, the script is invoked again. For details on verification script invocation, its arguments and environment variables, refer to the 5.3.3. Verification Script section of the Specification.
• Resource script. It serves to report application current resources usage to a Controller. The script utilizes the same calling conventions as configuration one, but its output stream should match XML scheme defined on the Specification. For details on resource script invocation, its arguments, output and environment variables, refer to the 5.3.4. Resource Script section of the Specification.
• Backup script. It serves to preserve and restore users' data. It is invoked by Controller on application instance backing up and restoration. Also, an operation of migration is performed with this script as sequential execution of backup and restore operations. For details on backup script invocation, its arguments and environment variables, refer to the 5.3.5. Backup/Restore Script section of the Specification.

  The script should be able to back up all sensitive application data to file specified and all involved resources, if required; restore backed up data to location specified.

• License script. It serves to install application license, if any. It is invoked when new license is issued for the application, existing license is updated or removed. The script should be able to get instance-specific license information, install issued license and remove installed one. For details on license script invocation, its arguments and environment variables, refer to the APS Licensing Aspect document.

Script-writing language must be a qualified technology defined in the Specification and must be declared in the metadata file. Application data is passed to scripts by means of environment variables. The variables contain all information about resources and settings of application instance you defined on the 7th step of the instruction.

Scripts execution is not always going without a hitch. Consider making script output structure matching XML schema defined in the Specification. A Controller catches such structured output, reads instructions and quickly reacts, in case some errors occur. These instructions may include identifiers of settings with erroneous values accompanied by localized error messages or problems detailed descriptions as well as warnings and errors related to the requirements. For details on forming structure of script output, refer to the 5.3.2.3 Configuration script output section of the Specification.

After necessary scripts are implemented, update metadata file with scripts declarations, according to the Specification. For details, refer to the 5.3. Service Provision Methods and 8. Common Aspects sections of the Specification.

11. Prepare package contents listing.

Each package must contain a well-formed XML file named APP-LIST.xml in the package root directory. The file must contain the list of all files in the package, but itself. Size in bytes and SHA256 digest value must be specified for each file in the list. This file may be digitally signed by a packager or certification authority.

Presence of packager signature assures package integrity and helps to prevent counterfeit. If a package is signed by certification authority, for example APS organization, the package contains a certificate as well.

For details on listing structure, refer to the 4.4 Package contents listing and 6. Package contents listing sections of the Specification

12. Create an application package structure.

Package structure must comply with the content organization requirements declared in the Specification. Check your package structure before archiving and update the application content if needed. Make sure, that APP-META.xml and APP-LIST.xml files are well-formed and contain all necessary information about an application.

For details on the requirements, refer to the 1. Introduction, 4. Basic Package Format and 6.5. Additional scripts sections of the Specification.

13. Archive the application package files.

The package should be a ZIP archive with the .app.zip extension, according to the 4.1. File format section of the Specification.

14. Validate the application package.

The package validation may comprise two steps: checking whether package structure conforms to APS and then checking whether package is properly managed by Controllers. Package structure can be validated using APSLint command-line utility. If the application package is APS-compatible, then you can check how it is managed by Controllers. To do this, examine the Controller operations that require application package data. For details, refer to the Validating Application Package chapter further in this guide.

Please send us your feedback on this help page