Application Packaging Standard: Development and Implementation

Application Packaging Standard: Development and Implementation
Student Guide
Version 1.0.3
Copyright 1999-2012 Parallels Holdings, Ltd. and its affiliates. All rights reserved.
ISBN: N/A Parallels 500 SW 39th Street Suite 200 Renton, WA 98057 USA Tel: +1 (703) 815 5670 Fax: +1 (703) 815 5675 1999-2012 Parallels. All rights reserved. Distribution of this work or derivative of this work in any form is prohibited unless prior written permission is obtained from the copyright holder
Contents
Preface ....................................................................................................................... 7
Documentation Conventions............................................................................................ 7
Typographical Conventions ......................................................................................................7 Shell Prompts in Command Examples......................................................................................8 General Conventions ................................................................................................................8
Introduction ............................................................................................................... 9
APS Overview ............................................................................................................... 10 SaaS Business Model ................................................................................................... 11 APS Application Life Cycle............................................................................................. 12 Provisioning Types ........................................................................................................ 13 Check Your Progress .................................................................................................... 15
Package Structure ................................................................................................... 17

Structure of APS Package ............................................................................................. 18 APS Metadata............................................................................................................... 19
Common Package Information .............................................................................................. 21 Services ................................................................................................................................ 21 Requirements ........................................................................................................................ 22 Configuration Settings ........................................................................................................... 23 Resources ............................................................................................................................. 25 Entry Points ........................................................................................................................... 25 Provisioning Logic ................................................................................................................. 26 Integration with Service Users ............................................................................................... 27 Integration with Domains ....................................................................................................... 28 Integration with Mailboxes ..................................................................................................... 29
Provisioning Logic ......................................................................................................... 30

Environment Variables ........................................................................................................... 30 Configuration Scripts ............................................................................................................. 31 Application Updates .............................................................................................................. 32
Contents
Check Your Progress .................................................................................................... 33
APS Package Creation ............................................................................................ 35

Planning APS Package .................................................................................................. 36 Developing APS Package .............................................................................................. 37 Development Tools ....................................................................................................... 38
Eclipse IDE ............................................................................................................................ 38 APS Plug-in ........................................................................................................................... 38
Packaging Application for Shared Web Environment ...................................................... 39

Demo: Creating WordPress APS Package ............................................................................ 40
Packaging Application for Dedicated Environment.......................................................... 58 Packaging Application for External Environment ............................................................. 60
Demo: Creating SpamExperts APS Package......................................................................... 61
Package Certification .................................................................................................... 71 Check Your Progress .................................................................................................... 73
Deployment in Parallels Automation....................................................................... 75

Importing APS Package ................................................................................................ 76 Configuration of Provisioning Environment ..................................................................... 77 Resource Configuration ................................................................................................. 78
Resource Types .................................................................................................................... 79 Activation Parameters............................................................................................................ 81
Service Template .......................................................................................................... 83 Service Plan .................................................................................................................. 85 Check Your Progress .................................................................................................... 86
Provisioning in Parallels Automation ...................................................................... 87

Application Installation, Configuration, Removal and Updating ........................................ 88 Configuration Runner .................................................................................................... 89
Example of Runner in Web Shared Environment ................................................................... 90 Example of Runner in Provisioning Gateway .......................................................................... 90
Integration with Service Users........................................................................................ 91 Integration with Domains ............................................................................................... 92 Integration with Mailboxes ............................................................................................. 93 Check Your Progress .................................................................................................... 94
Troubleshooting in Parallels Automation................................................................ 95

Troubleshooting Tools ................................................................................................... 96
APS Player ............................................................................................................................ 96
Contents
Importing APS Packages............................................................................................... 97 Debugging APS Configuration Scripts............................................................................ 98

Shared Web Provisioning Type .............................................................................................. 98 External System Provisioning Type ........................................................................................ 99
Special Cases in Customer Control Panel .................................................................... 100

Empty Value ........................................................................................................................ 100 Unforeseen Error ................................................................................................................. 100
Check Your Progress .................................................................................................. 101
Check Your Progress ............................................................................................ 103

Module 1. Introduction ................................................................................................ 104 Module 2. Package Structure ...................................................................................... 105 Module 3. APS Package Creation ................................................................................ 106 Module 4. Deployment in Parallels Automation ............................................................. 107 Module 5. Provisioning in Parallels Automation ............................................................. 108 Module 6. Troubleshooting in Parallels Automation....................................................... 109
Preface
Documentation Conventions
Before you start using this guide, please familiarize yourself with its documentation conventions.
Typographical Conventions
The following formatting conventions in the text identify special information.
Formatting convention Special Bold Type of Information Items you must select, such as menu options, command buttons, or items in a list. Titles of modules, sections, and subsections. Italics Used to emphasize the importance of a point, to introduce a term or to designate a command-line placeholder, which is to be replaced with a real name or value. The names of commands, files, and directories. On-screen computer output in your command-line sessions; source code in XML, C++, or other programming languages. Example Navigate to the QoS tab.
Read the Basic Administration module. These are the so-called shared containers. To destroy a container, type pctl delete CTID
Monospace
Use pctl start to start a container.

Saved parameters for Container 101
Preformatted
Preformatted Bold CAPITALS KEY+KEY
What you type, contrasted with on-screen # rpm V virtuozzo-release computer output. Names of keyboard keys. Key combinations - user must press and hold down one key and then press another. SHIFT, CTRL, ALT CTRL+P, ALT+F4
Preface
Shell Prompts in Command Examples

Command-line examples throughout this guide presume that you are using the Bourne-again shell (bash). Whenever a command can be run as a regular user, we will display it with a dollar sign prompt. When a command is meant to be run as root, we will display it with a hash mark prompt:
Bourne-again shell prompt Bourne-again shell root prompt
$ #
General Conventions
Be aware of the following conventions used in this book. The content of this guide is divided into modules which, in turn, are subdivided into sub modules. When following steps or using examples, be sure to type double-quotes ("), left singlequotes (`), and right single-quotes (') exactly as shown. The key referred to as RETURN is labeled ENTER on some keyboards. Commands in directories included in a PATH variable are used without absolute path names. Steps that use commands in other, less common, directories show the absolute paths in the examples.
# $PRODUCT_ROOT_D/bin/<utility name> [parameters] [options]
# /usr/local/psa/admin/bin/<utility name> [parameters] [options]
MODULE 1
Introduction
In This Module
APS Overview ........................................................................................................ 10 SaaS Business Model............................................................................................. 11 APS Application Life Cycle ...................................................................................... 12 Provisioning Types ................................................................................................. 13 Check Your Progress ............................................................................................. 15
Introduction
APS Overview
APS (Application Packaging Standard) is a unified open standard that defines the package structure and rules of processing packages. A package is a file that contains application files and metadata required to provision and manage instances of an application. APS increases business opportunities for the entire hosting ecosystem, bringing together application vendors and hosting service providers. By implementing APS, application vendors get access to the vast sales and marketing channel of APS-enabled hosting providers. In turn, hosting service providers, by implementing APS, gain access to a great variety of APS applications. Application vendors implement APS by creating application packages in full compliance with the rules defined by the standard. Currently, there are more than 700,000 instances of APS packages. For providers, there are publicly available catalogs of APS packages, for example, http://apscatalog.com and http://www.apsstandard.org/app.
10
Introduction
SaaS Business Model

SaaS (Software as a Service) is a business model where software applications are sold as services and can be easily accessed by end users with a web browser or another standard tool. In the SaaS model, software is hosted by service providers, and can be obtained by their customers on demand. Customers subscribe to the target application instead of purchasing and maintaining it. Customers are typically charged on a per-month basis for flexible, low-cost access to software applications. As a result, they can focus on their business rather than spend time and resources applying patches/updates on their software. APS can be used to deliver a SaaS service.
The SaaS model includes three object types: SaaS Application is a software application packaged by an ISV (independent service vendor) using the APS technology. SaaS Service is an application service that is defined in an APS package and provisioned for a customer on demand. To process APS packages, the provider environment must have an APS controller compatible with the APS requirements. SaaS Client is a company or an individual who can subscribe to an application and get access to its services.
11
Introduction
APS Application Life Cycle

APS application life cycle includes the following stages: 1 Packaging In this stage, the target application package is created, tested and certificated to be published in APS catalog afterwards. 2 Deployment The application package is imported into POA and all associated Resource Types are created and configured by means of activation parameters. 3 Provisioning Once deployed, the APS controller provisions the application services for a customer. The full application life cycle allows you to perform the following operations: Install and configure application instances within the hosting environment on demand. Update application instances within the hosting environment and apply application patches and security fixes without user interaction. Install and remove the application license. Perform operations such as backup or restore using the backup script, which is included in the APS package. Let customers manage application objects, such as users, mailboxes, domains, etc. Customize applications by installing additional plug-ins, for example, language packs or themes. Uninstall application instances.
12
Introduction
Provisioning Types
Depending on the way an application is going to be provisioned, the following provisioning types are singled out. Shared web environment. Files are installed in a web server and this web server is shared for multiple instances of APS application.
Dedicated environment. Files are placed in a virtual private server (VPS) based on the Parallels Virtuozzo Containers technology. The VPS is dedicated to a single instance of the application:
External application (Open-Xchange, SpamExperts, Backup Agent, etc.). The APS package does not contain any application files inside and represents a connector to an external service. Application files and user data are located outside of the customer's environment, in a multi-tenant application server or group of servers. The servers may be located either on the Internet or inside the hosted infrastructure:
13
Introduction
When deciding how to deliver an APS-enabled application, consider the overall sales model and the necessary supporting technologies. For example, a Java-based application cannot be deployed in a web space and requires a dedicated container. In this case, the application should be packed as a dedicated APS package. If the application supports multi-tenancy, the better choice is to pack it as an external APS package.
14
Introduction
Check Your Progress

Before continuing on to the next chapter, ensure whether you are able to answer the following questions. If you cannot answer a question, please reread the corresponding training materials. 1 2 3 What benefits does APS provide for application vendors? What is the difference between the SaaS business model and the standard application-purchasing model? What are the main stages of the APS life cycle?
15
MODULE 2
Package Structure
This module describes generic objects of the APS specification that can be declared in APS packages. The exact structure of a package may vary depending on the application nature and its provisioning type.
In This Module
Structure of APS Package ...................................................................................... 18 APS Metadata ........................................................................................................ 19 Provisioning Logic .................................................................................................. 30 Check Your Progress ............................................................................................. 33
17
Package Structure
Structure of APS Package

An APS package is a hierarchical structure of files and directories compressed into a single file with the app.zip extension.
Typically, an APS package includes the following components: 1 2 3 4 Application definition file APP-META.xml. A directory containing application native files or Parallels Virtuozzo Containers (PVC) templates. For the shared web provisioning type, the document root is usually htdocs. The Scripts directory with scripts implementing the provisioning logic of the application: Install, Remove, Configure and other operations. List file APP-LIST.xml containing the list of all files in the package but itself. The size in bytes and the SHA256 digest are specified for each file in the list to determine the package integrity and to protect from fake packages. As an alternative, a certification authority (for example, the APS organization) may sign a package; in such a case the package contains a certificate additionally. Optionally, the package may contain additional directories, such as Images (for storing images presenting the package itself in provisioning systems).
Note: An APS package must comply with the Application Packaging Standard (APS) Format Specification available at http://www.apsstandard.org/isv/documentation/.
18
Package Structure
APS Metadata
The APP-META.xml file contains all the declarations required to provision and manage an application. A part of declarations describes package information and others services that the application brings (the <service> tag). Services can form a hierarchy with up to three levels. There is alway a root service at the top level that can have sub-services, i.e. services of the second level, etc. Each service has its own additional declarations included, such as presentation information, configuration parameters, requirements, and references to the provision logic scripts. The typical structure of the APP-META.xml file is as follows:
19
Package Structure
20
Package Structure
Common Package Information

The following parameters defined via XML tags are mandatory for any application package: <id> is the application identifier, usually a URI, that is used as a reference when patching or upgrading an application instance to a newer version. It must not be changed in any versions of the package. <name> is the user-visible name of the application in a package. This can be changed in an upgrade. <version> is the application version that is going to be packed, and the package release. <release> is the APS package release number. The package version consists of the application version and the package release number.
The package can be described in details with a number of other presentation parameters, for example, changelog history, screenshots, etc., under the <presentation> tag. One of them, namely a category into which the APS package is included, is a mandatory one.
Services
Each application service is represented by a service meta-data object. An application might include several services.
21
Package Structure
Each service must be declared as a particular element in APP-META.xml and might have its own parameters, resources, requirements, and provisioning scripts. A sub-service can be one of the following classes defined by the class attribute. service defines a discrete function of the application. account allows assigning a user account to the parent service, i.e. always exists as a subservice. ecommerce defines an e-commerce service.
APS services are structured in a hierarchy that reflects the logical structure of the application: The top-level (root) service. Sub-services (second level) that are presented as application objects for customers. In addition, applications can declare a number of object features (third-level services). Such services are available for users only if they are nested inside a second-level service of the account class.
The root service is mandatory in an application package. Example of nested services:

<service id="email"> ... <service id="mailbox" class=account> ... <service id="mobile access"> ... </service> </service> <service id="addressbook"> ... </service> </service>
Requirements
An application service may contain a list of requirements to be satisfied during the package provisioning. The <requirements> tag is used to contain all the requirements. For instance, the following code requires PHP of version not less than 4.0 to be presented in the provisioning environment:
<requirements xmlns:php="http://apstandard.com/ns/1/php"> <php:version min="5.0"/> </requirements>
At a provisioning system, the requirements must be processed by the APS controller. For example: If PHP is required, the PHP of the proper version must be installed in the provisioning environment. If a database is required, the APS controller must install a database with a name assigned by a certain rule and create a database owner with a random password.
22
Package Structure
Configuration Settings
Configuration settings are settings needed to create a service. While most of the settings are provided to the APS controller without user interaction, some settings need to be entered by a user to pass them to configuration and update scripts. Such parameters are defined using the <settings> tag. A setting has a number of attributes. Some of them are explained here. 1 2 id is used to make reference to the setting from other tags by means of the value-ofsetting attribute. Class is needed for APS controllers to assign a certain processing for the setting, e.g.: login will be processed as a login name. locale defines a language supported by the application. Settings without the class attribute are not processed by APS controllers. 3 4 Type defines defines a data type: string, number, enum, etc. Its value usually must be selected depending on the setting class. In case a setting is supposed to be configurable during the service provisioning only, it should be marked with the installation-only attribute. If settings are optional, then they should be marked with the optional attribute, otherwise they are considered to be mandatory by the APS controller and cannot be left empty. The Protected attribute informs the APS controller that a user is not allowed to change such a parameter. If a setting needs to be hidden from the application subscriber, the visibility attribute should be set as hidden. The value of a setting can be required to be unique within a scope. The uniq attribute must be specified for that. For instance, uniq="global" means that the value of such a setting must be unique within the global scope, that is, among all the resource types that are created for the same application. If a setting value must be generated automatically, use the generate attribute with one of the values: sequence, uuid, random, or password. A child service can request a setting value from its hierarchical parents (from bottom to top) by using the value-of-setting attribute.
7 8
A setting may have a number of parameters specified as tags: name, description, default-value, and error-message. A service can also contain settings in groups with certain group classes as follows: authn relates to user authentication parameters, i.e. login name and password. presentation caries presentation and user interface information, e.g. locale. web defines a web site title an its description. vcard is needed to gather personal data in the hCard format.
<settings> <group class="authn"> <name>Administrator's preferences</name>
23
Package Structure
<setting id="admin_name" type="string" default-value="admin" class="login" min-length="1" max-length="32" regex="^[a-zA-Z][0-9a-zA-Z_]*"> <name>Administrator's login</name> <error-message>Please make sure the text you entered starts with a letter and continues with either numbers, letters, underscores or hyphens. </error-message> </setting> <setting id="admin_password" type="password" class="password" min-length="1" > <name>Password</name> </setting> </group> <group class="vcard"> <name>Main configuration</name> <group class="email"> <setting id="admin_email" type="email" class="value"> <name>Administrator's email</name> </setting> </group> <group class="fn n"> <setting id="title" type="string" default-value="My CMS" min-length="1" class="organization-name"> <name>Site name</name> </setting> </group> </group> <group class="web"> <setting id="locale" class="locale" type="enum" default-value="en-US"> <name>Interface language</name> <choice id="nl-NL" > <name>Dutch</name> </choice> <choice id="de-DE" > <name>German</name> </choice> <choice id="en-US" > <name>English</name> </choice> </setting> </group> </settings>
NOTE: Get more details on settings attributes at http://www.apsstandard.org/r/doc/package-formatspecification-1.2/index.html#s.metadata.service.settings.
24
Package Structure
Resources
Generally, resource objects are declared inside the particular service definition and prescribe what usage values should be reported by the application. The APS controller can use them for monitoring applications and accounting resources. The <resource> tag is used to define each new usage object, for instance:
<resources> <resource id="filestore_diskusage" class="mb" limitingsetting="filestore_quota"> <name>Disk space used by Open-Xchange context infostore files. </name> </resource> </resources>
A resource is identified by the id attribute. The class attribute defines the units of measurement for a given resource (item, b, kb, mb, gb). The resource limit may be specified through the limiting-setting attribute. Resource usage reporting is implemented inside a resource script.
Entry Points
Entry points are application access links presented in a customer control panel. Each new entry point is defined using the <entry> tag. Additionally, variables can be defined within each entry point to pass values inside the request when an entry point is clicked, for example:
... <entry-points> <entry dst="/wp-login.php" method="POST"> <label>Administrative interface</label> <variable name="log" value-of-setting="admin_name" class="login"/> <variable name="pwd" value-of-setting="admin_password class="password"/> </entry> </entry-points> ...
The class attribute of the variables may be used, to inform the APS controller about a requested variable meaning: login - a requested variable contains a login password - a requested variable contains a password locale - a requested variable carries localization information
25
Package Structure
Provisioning Logic
In APS, two programming approaches are implemented. Declarative programming is used to require from the APS controller to create some objects required in the package. This works towards object often required by various applications. For example, the APS controller is able to setup PHP in a shared web environment, or create a database with an owner of the database, and other. Imperative programming allows the packagers to be flexible in processing APS packages in order to meet application specific requirements, e.g. set certain specific variables in certain installation files. This is possible due to different types of custom scripts that are considered in this topic.
The <provision> section specifies two provisioning mechanisms for installing an application instance in a web site: passive configuration by URL mapping and active configuration by means of configuration scripts. Normally, both of them are used. URL mapping mechanism processes the package in the following way. 1 2 It copies the hierarchy of files from the Files directory to a web site directory defined at the provisioning stage. It configures the virtual web host in accordance with URL mapping rules containing the following XML elements. Default prefix specifies the directory of the application instance document root. Mapping URL sets the mapping between a site directory and a URL suffix by means of aliases in a web server. It also requires files with a certain extension to be processed by a certain script engine, e.g. PHP, Perl, or Python. Additionally, it can set the write permission to configured directories. There are a few types of scripts that can be specified in the metadata: Configuration script - <configuration-script> tag. It implements install, configure, upgrade, and remove operations over an application instance requested from a control panel. Resource script - the <resource-script> tag. It reports the application's current resource usage to the APS controller.
Note: For details on resource scripts, refer to the APS Standard Specification 5.3.4 Resource Script. http://www.apsstandard.org/r/doc/package-format-specification-1.2/
Verification script - the <verify-script> tag. This script verifies the service settings for consistency, but it should never change the application state or its instances. License script - the <l:license-script xmlns:l="http://apstandard.com/ns/1/licensing"> tag. It is invoked when a new license is issued for the application, or the old license is updated or removed. The script should be able to get the instance-related license information, install the issued license and remove it on demand.
26
Package Structure Backup script - the <backup-script> tag. It serves to preserve and restore user data. The APS controller invokes it when the application instance backup or restore is requested. The script should be able to back up all sensitive application data and all involved resources to a specified file, and restore backed up data to a specified location.
This is an example of the URL mapping rules.

<provision> <configuration-script name="configure"> <script-language>php</script-language> </configuration-script> <url-mapping> <default-prefix>wordpress</default-prefix> <installed-size>6696960</installed-size> <mapping url="/" path="htdocs" xmlns:php="http://apstandard.com/ns/1/php"> <php:permissions writable="true"/> <php:handler> <php:extension>php</php:extension> </php:handler> <mapping url="wp-config.php"><php:permissions writable="true"/> </mapping> <mapping url="blogs/media"><php:permissions writable="true"/> </mapping> <mapping url="wp-content"><php:permissions writable="true"/> </mapping> <mapping url="tmp"><php:permissions writable="true"/> </mapping> </mapping> </url-mapping> </provision>
Integration with Service Users

If a customer who buys an application has multiple end users, their auto-registration for the application can be performed. Therefore, the second-level service of the account class should be declared. The APS controller will use the existing end user parameters declared in the ressource groups to register the end users in the application. In the following example, login, password, given name, and surname of existing end users will be used for registering them in the system:
<service id="account" class="account"> ... <settings> <group class="authn"> <setting id="user_login" class="login"> </setting> <setting id="user_password" class="password"> </setting> </group> <group class="fn n"> <setting id="user_given_name" class="given-name"> </setting> <setting id="user_surname" class="family-name"> </setting> </group> </settings> ... </service>
27
Package Structure
Integration with Domains

APS allows applications to use and modify domain zones. Therefore, two related elements must be declared. 1 A setting of the domain-name class and list type is needed to create a list of domains in the provisioning environment: DNS record types that will be subjected to changes must be specified. Often it concerns MX records and thus it can be presented as follows.
<setting id="domains" class="domain-name" type="list" element-type="string"> </setting>
<group> <name>Virtual MX record</name> <setting id="mx1" class="title" type="string" default-value="" min-length="1"> <name>Primary MX</name> <description> This is the MX record used to deliver to the spamcluster, preferably a Round Robin DNS entry containing all servers. </description> </setting> </group>
To modify used domains, the DNS aspect (xmlns:dns="http://apstandard.com/ns/1/dns") must be specified with the dns:record in the <requirements> section of a service. The most typical modification is the MX record substitute to redirect mail:
<dns:record> <dns:id>MX1</dns:id> <dns:mx> <dns:src> <dns:external value-of-setting="domains"/> </dns:src> <dns:dst> <dns:external value-of-setting="mx1"></dns:external> </dns:dst> <dns:substitute/> </dns:mx> </dns:record>
28
Package Structure
Integration with Mailboxes

APS allows applications to gain access to customer mailboxes or SMTP servers based on Linux mail hosting services (qmail). Therefore, add the mail aspect (xmlns:mail="http://apstandard.com/ns/1/mail") inside the second-level service of the account class with the following requirements. Mailbox requirement: Incoming mail server requirement:
<mail:mailbox> </mail:mailbox>
<mail:access> <mail:imap/> </mail:access>
Outgoing mail server requirement:
<mail:outgoing> <mail:smtp/> </mail:outgoing>
This is an example:
<requirements xmlns:mail="http://apstandard.com/ns/1/mail" xmlns:php="http://apstandard.com/ns/1/php"> <php:version min="5.2" /> <php:extension>openssl</php:extension> <php:extension>curl</php:extension> <mail:mailbox> <mail:id>account</mail:id> <mail:access> <mail:imap/> </mail:access> <mail:outgoing> <mail:smtp/> </mail:outgoing> </mail:mailbox> </requirements>
29
Package Structure
Provisioning Logic
In a provisioning environment, some operations over application instances are processed by the APS controller that implements the declarative logic contained in the APS package. The following operations are performed by APS controllers. 1 2 3 4 Copying files in accordance with the URL mapping. Creating HTTP links, e.g. entry points. Creating requested objects, such as databases and database owners. Running the configuration script that must process settings and other parameters passed through environment variables.
Application specific configuration is to be processed by configuration scripts implementing the imperative logic. In the following sections, you will find description of environment variables and configuration scripts.
Environment Variables
1 URL mapping variables are needed when the shared web provisioning type is used. They are presented in the following list: BASE_URL_SCHEMA can be either http or https. BASE_URL_HOST is the host domain name. BASE_URL_PORT is the TCP port, e.g. 80 or 443. BASE_URL_PATH is the URL path including the trailing slash. WEB_<ID>_DIR is the full path to a directory on the provisioning host. For the document root, the <ID> is replaced with one ;more '_'. In addition to the document root, multiple variables of the same type can define other directories with own <ID>. 2 3 4 Every declared global setting or service setting must be passed as the SETTING_<ID> variable, where <ID> is the ID of the declared setting. For each setting with the track-old-value attribute, the corresponding OLDSETTING_<ID> variable must be passed to configuration scripts. APS aspects, if used, specify own environment variables that must be passed to configuration scripts.
30
Package Structure
Configuration Scripts
As a best practice approach, for APS packages of the web shared provisioning type you may use script files copied from existing APS packages. The following script files are often used. 1 configure or configure.php file contains the main script started by the runner.sh script from inside the web site directory. In some parts, it is application specific. It performs the following operations. It defines some application specific parameters and creates a hash from each set of parameters, e.g.: Array of configuration files Database schema files It defines the required command (install, configure, upgrade, or remove) and calls the function (respectively configure, configure, upgrade_app, or remove_app) for processing the command. It passes the needed hashed parameters to the function. 2 app-util.php file contains definitions of common high-level functions. Function configure uses database schema files to create or modify database tables by calling the import_sql_scripts_to_databases function. It also creates or modifies the application configuration file (e.g. wp-config.php for WordPress) from the configuration template (e.g. wp-config.php.in for WordPress). Therefore, it calls the write_config_files function. Function import_sql_scripts_to_databases. Function write_config_files. Function set_write_permissions sets the read, write, and execute permissions for a file. Function set_write_permissions_list sets the read, write, and execute permissions for a list of files. 3 upgrade-app.php contains the definition of the application specific high-level function upgrade_app needed for upgrading application instances. The upgrade may substantially depend on the application release and package version. db-util.php file contains definitions of common low-level functions for working with SQL databases. file-util.php file contains definitions of common low-level functions for working with files and directories. env-parser.php file contains definitions of common low-level functions for working with environment variables. The functions are needed for the following operations. Fetching environment variables Defining values for placeholders used in the configuration template Creating a hash for a set of parameters that are used in the configure script
4 5 6
31
Package Structure
Application Updates
There are two types of updates. 1 Upgrade implies major changes in application instances including updates of files, database, settings, and requirements. It implies that in the provisioning system, some operations are performed by the APS controller, and after that the configuration script with the update command is started. The following operations are performed by the APS controller: Update and removal of files
NOTE: Files in the Scripts directory are updated after the application files are updated (usually in the htdocs directory).
Reconfiguration of PHP if needed, e.g. update from version 4 to version 5 Restart of the web server 2 Patch implies minor changes in application instances, such as update of files. This operation is processed by the APS controller in a provisioning system. In some cases, the configuration utility can also be started, e.g. the APS controller in POA works this way.
32
Package Structure
Check Your Progress

Before continuing on to the next chapter, ensure whether you are able to answer the following questions. If you cannot answer a question, please reread the corresponding training materials. 1 1 2 3 What types of components can be included in the APPMETA.xml file? Can you miss out service declaration in the metadata file? Which class must be assigned to a service used for integrating application instances with users? What operations can be performed by the configuration script?
33
MODULE 3
APS Package Creation

This module describes specifics of APS package creation for different types of application provisioning.
In This Module
Planning APS Package ........................................................................................... 36 Developing APS Package ....................................................................................... 37 Development Tools................................................................................................. 38 Packaging Application for Shared Web Environment ............................................... 39 Packaging Application for Dedicated Environment ................................................... 58 Packaging Application for External Environment ...................................................... 60 Package Certification.............................................................................................. 71 Check Your Progress ............................................................................................. 73
35
Planning APS Package

Before you begin to develop an APS package for your application, follow these preliminary steps that help you avoid mistakes and not miss some needed actions. 1 2 Define the sales model. This will help you to figure out requirements to the provisioning environment as well as a list of services and resources to be declared in the APS package. Define the environment and associated provisioning type. Shared environment - an application instance will be installed in a web server. Dedicated environment - an application instance will be installed in a Parallels Virtuozzo Container. External environment - the application must be pre-installed in an external system. The APS package will use a gateway to install an application connector. 3 Determine the hierarchy of application services. The logical structure of the application includes a top-level service, sub-services and available features as third-level services. Expose only those components that are either sold or must be managed by end-users. 4 5 Define the licensing procedure, if the license key delivery is required. Define used technologies and application requirements. Write a specification containing all application requirements, for example, scripting languages, databases, DNS zones and server modules. 6 7 Define the application global settings and service settings. Determine the application content delivery method. Inside a package - the controller simply copies the files from the package to a hosting environment according to the URL mapping rules. Inside the PVC template - application files are defined in the PVC templates. Delivery is not required - this method is used with an external environment.
36
Developing APS Package

Generally, the following steps are needed to develop an APS package: 1 2 Create or update the hierarchy of the application package folders and copy the application content to the appropriate place. Create and edit the APP-META.xml metadata file that includes all application properties, for example, name, version, description, list of services with their settings, required resources, and reference to configuration scripts. Create the provisioning scripts. Archive the APS package files. Validate the APS package. Verify that the package is accepted by an APS-compliant controllers, for example, the one inside Parallels Automation. Test the application deployment and provisioning.
3 4 5 6 7
37
Development Tools
To create an APS package in the most developer-friendly way, the APS team issued the APS plug-in for the Eclipse IDE (Integrated Development Environment) to create, validate, deploy, and publish APS packages from a single place, reducing a number of operations that might require the application developer involvement.
Eclipse IDE
Eclipse IDE is an open source software development environment written in Java, and it is an OS-independent IDE. Eclipse can be used for different classes of development projects by using corresponding plug-in modules. To install Eclipse IDE: 1 2 3 Make sure Sun Java SE JRE is setup on your system. Navigate to http://www.eclipse.org/downloads/ and download the Eclipse Classic archive. Unpack the archive into a disk directory. No actual installation is required.
APS Plug-in
APS plug-in is intended to extend Eclipse IDE to easily create APS-compatible packages and automate their subsequent deployment and publishing. To install the APS plug-in: 1 2 3 4 5 6 7 8 Run the Eclipse executable. Navigate to Help > Install New Software. Type http://www.apsstandard.org/r/doc/sdk/eclipse-plugin in the Work with combobox and then press Enter. Select the Application Packaging Standard checkbox and click Next. Eclipse will check dependencies of the selected software. Click Next, read and accept license agreement. Click Finish and wait until installation is complete. Restart Eclipse. Close the Welcome page and switch to the APS perspective by navigating to Window > Open Perspective > Other.
38
Packaging Application for Shared Web Environment

The APS package creation for shared web environment has the following peculiarity: URL mapping must be specified, for instance:
<url-mapping> <default-prefix>wordpress</default-prefix> <installed-size>6696960</installed-size> <mapping url="/" path="htdocs" xmlns:php="http://apstandard.com/ns/1/php"> <php:permissions writable="true"/> <php:handler> <php:extension>php</php:extension> </php:handler> <mapping url="wp-config.php"><php:permissions writable="true"/> </mapping> <mapping url="blogs/media"><php:permissions writable="true"/> </mapping> <mapping url="wp-content"><php:permissions writable="true"/> </mapping> <mapping url="tmp"><php:permissions writable="true"/> </mapping> </mapping> </url-mapping>
39
Demo: Creating WordPress APS Package

Planning WordPress APS Package
WordPress will be sold as standalone objects that can be installed one or multiple times per customer. 1 Sales models: Web site with applications Application in a separate web site 2 3 4 5 Type of environment. The application vendor states that WordPress can be installed on shared hosting so, the application is to be delivered within a shared environment. Service hierarchy. WordPress provides only the root service web blog. Licensing procedure. WordPress is a free, open source application implemented under a GPLv2 license. Technologies used. According to http://wordpress.org/about/requirements/, PHP version 5.2.4 or greater and MySQL version 5.0 or greater must be setup on the machine before installing WordPress 3.2.1. Application settings. WordPress requires the following settings on installation: admin credentials and e-mail address, web blog title, and language choice. Content delivery method. WordPress is a simple web application requiring deployment of files, and is accessible from Internet over HTTP/HTTPS. Provisioning operations must be implemented by URL mapping rules and provisioning scripts.
6 7
40
Developing WordPress APS Package

Download the archive of the WordPress application by navigating to http://wordpress.org/download/. Then create a new APS project in Eclipse IDE: 1 2 3 Run Eclipse. Navigate to File -> New -> Project, select APS Project and then click Next. Specify the project name and location, and select an APS version:
41
APS Package Creation 4 Click Finish.
The structure of the project is shown in the Project Explorer View and looks as follows:
42
APS Package Creation Files folder. All the application files should be placed here. Unpack the downloaded WordPress archive into the htdocs sub folder (should be created manually) of the APS project directory (/home/APS/projects/APS_WordPress). Images folder. All the image files are stored here. Scripts folder. All the scripts implementing the provisioning logic should be placed here. APS Package folder. All the package versions are stored here. Due to the APS plug-in, the project files are automatically compressed to become an APS package. Each time the application version or package release is changed, a new separate package version will be created upon saving. APP-LIST.xml. The file contains the list of all files in the package except itself. Size in bytes and SHA256 digest value are specified for each file in the list. APP-META.xml. The file contains application definitions and is automatically opened in the Editor.
The Editor simplifies the procedure of defining the application metadata by means of GUI fields, although the XML code is still available to edit it manually. Let us define the metadata file adhering to the GUI, sequentially switching between the corresponding tabs. The very last tab contains the XML code itself and might be useful to trace the new elements that will appear in the APP-META.xml file, as new values are specified through the GUI fields. Overview tab GUI interaction steps: Specify the following mandatory values. Application ID: http://wordpress.org/. A unique value that impacts successful updating from previous versions to the current one. Name: APS_WordPress. Version: 3.2.1. This is a WorrdPress version. Release: 1. This is the APS package release. Application version and package release are united for the package version: 3.2.1-1. To avoid conflicts between APS packages that have the same name, we recommend specifying a unique packager URI value as well.
43
XML code: GUI actions executed generate the following code that could be typed manually:
<id>http://wordpress.org/</id> <name>APS_WordPress</name> <version>3.2.1</version> <release>1</release>
Presentation tab The tab area contains top sub-tabs. Two of them, Changelog and Other include mandatory definitions: GUI interaction steps Switch to the Changelog sub-tab, click the Add button, and then specify Version: 3.2.1, Release: 1, Entry: WordPress release notes: http://codex.wordpress.org/Version_3.2.1.
44
APS Package Creation Switch to the Other sub-tab, click the Add button, in the Category box choose a category for the APS package. Let us pick Web/Blog to be the category for the WordPress APS package although a greater number of categories may be assigned to the same APS package. APS package supports multi-language localization. That means the content of some XML elements can be presented in different languages. To expand the APS package localization, click the Add button from the Languages section, and in the Language box choose a language that will be available. Let us assume that the WordPress APS package will support English (en) by default and, additionally, French (fr).
45
XML code:
<presentation> <changelog> <version version="3.2.1" release="1"> <entry>WordPress release notes: http://codex.wordpress.org/Version_3.2.1 </entry> </version> </changelog> <categories> <category>Web/Blog</category> </categories> <languages> <language>en</language> <language>fr</language> </languages> </presentation>
Global Settings tab There are no global settings in WordPress that can be applied to all instances.
Services tab GUI interaction steps The only service provided by WordPress is web blog management. To specify this service, click the Add button. The service added should be properly configured for successful provisioning: In the General sub-tab, specify the service unique identifier, ID: WordPressBlog. Click to the License sub-tab. As stated previously, WordPress is a free, open source application. Click the License type box and choose Free. A user should read and accept GPLv2 before using WordPress. Therefore, select the Must be accepted by a user check box, click the Add button, type the license name, and then browse for a file that contains the GPLv2 description. Because the APS package will be bilingual, two license agreements, one for each language and each containing the GPLv2 file, should be specified. For the APS controller to distinguish between these license agreements, the Language field should be set to an appropriate value.
46
47
XML code:
<license must-accept="true"> <free /> <text xml:lang="en-US"> <name>GPLv2_en</name> <file>htdocs/license_en.txt</file> </text> <text xml:lang="fr-FR"> <name>GPLv2_fr</name> <file>htdocs/license_fr.txt</file> </text> </license>
GUI interaction steps Proceed with the service configuration on the Settings sub-tab. WordPress requires that the following settings are to be specified on installation: Administrator credentials. Generally, the related settings should be visually rendered as a single group. Click the Add button, then the Setting group item, and type the group name: Administrator's preferences. It is recommended to inform the APS controller about the type of settings the group button, then the Class item, and in the Class contains by specifying its class. Click the box that appears choose authn. The Administrator's preferences group holds the login and password. Select the Administrator's preferences group, click the Add button then the String setting item, and in the ID box select admin_name. In the same way, add the Password setting item and select admin_password as a value. Both of those fields should be labeled for a user to distinguish, so add the Name detail field to each of the settings, and then type in an appropriate word as a value; for example, Admin's login and Password. This detail field has the mark meaning that an XML element corresponding to it can be localized into the
additional language (French) that was specified previously. Click next to the Name field of the login setting,and in the window that appears add a row for the fr-FR localization and type in, for instance, Le login administrateur as a value. For the password setting, specify Le mot de passe as a translation.
NOTE: Each locales that can be used here is specified as a <presentation><languages><language> element at the global application level.
An APS controller may automatically fill in some settings to reduce the number of input operations that require user involvement by specifying the class. Add the Class item for each of the settings inside the Administrator's preferences group, and assign login and password as corresponding values. Web blog title and administrator e-mail. These settings could be included in the same group; for example, named Main configuration. Vcard works well as a value of the group class; both settings relate to the general representation.
Note: Vcard class is organized according to the Vcard standard that is the basis of the HCard specification. Please, visit http://microformats.org/wiki/hcard for details.
48
APS Package Creation The Vcard standard prescribes that sub-classes fn and n are mandatory to use; therefore, let us add a sub-group named Title, for example, and specify fn n as its class value. Then a setting with ID: title, Type: string should be created inside the group. Let us assume that the title setting should be automatically filled in with a company name value. In accordance with PA-specific APS Classes, the company name can be obtained from the organization-name class; therefore, specify that class as a value of the title setting class.
Note: All other PA-specific APS classes can be found at http://www.parallels.com/r/docs/poa/Integrating_Application_with_Parall els_Automation_by_APS/58169.htm
As for the e-mail setting (ID: admin_email, Type: email), a separate sub-group of the email class named Email, for instance, should be created for it inside the Main configuration setting group. To comply with the Vcard standard, the value should be specified as the email setting class. Interface language. This setting relates to the WordPress appearance and also could be included in a separate group named Language, for example. The most applicable group class in such a case is web. The setting itself should have ID: locale, Type: enum and Class: locale. The enum type means that a choice between a number of pre-defined values (languages) must be made at the installation stage. To pre-define those values, select the setting, click the Add button and then Choice, and specify the language ID and Name. For instance, ID: en-US, Name: English.
49
XML code:
<settings> <group class="authn"> <name>Administrator's preferences</name> <setting id="admin_name" type="string" class="login"> <name>Administrator's login</name> <error-message>Please make sure the text you entered starts with a letter and continues with either numbers, letters, underscores or hyphens. </error-message> </setting> <setting id="admin_password" type="password" class="password" min-length="1" > <name>Password</name> </setting> </group> <group class="vcard"> <name>Main configuration</name> <group class="fn n"> <setting id="title" type="string" class="organization-name"> <name>Site name</name> </setting> </group> <group class="email"> <setting id="admin_email" type="email" class="value"> <name>Administrator's email</name> </setting> </group> <group class="web"> <setting id="locale" class="locale" type="enum" default-value="en-US"> <name>Interface language</name> <choice id="nl-NL" > <name>Dutch</name> </choice> <choice id="de-DE" > <name>German</name> </choice> <choice id="en-US" > <name>English</name> </choice> <choice id="fr-FR" > <name>French</name> </choice> <choice id="it-IT" > <name>Italian</name> </choice> </setting> </group> </settings>
GUI interaction steps Click the Requirements sub-tab. As defined previously, WordPress requires PHP version 5.2.4 or greater and MySQL version 5.0 or greater to be setup prior to its installation; that is why those requirements must be declared inside the APS package for successful provisioning. Click the Add button then PHP, and type 5.2.4 as a value of the min-version field. Because WordPress utilizes MySQL database to store all the settings, you must add the extension item as a PHP requirement detail, and set its value: mysql. Now let us add the Database requirement and specify details on it as follows ID: main, server-type: mysql, server-min-version: 5.0
50
51
XML code:
<requirements xmlns:php="http://apstandard.com/ns/1/php" xmlns:db="http://apstandard.com/ns/1/db" xmlns:mysql="http://apstandard.com/ns/1/db/mysql"> <php:version min="5.2.4"/> <php:extension>mysql</php:extension> <db:db> <db:id>main</db:id> <db:default-name>wordpress</db:default-name> <db:can-use-tables-prefix>true</db:can-use-tables-prefix> <db:server-type>mysql</db:server-type> <db:server-min-version>5.0</db:server-min-version> </db:db> </requirements>
GUI interaction steps Click the Entry Points sub-tab. All the specific access links to the WordPress application should be listed here. It is enough to add just a couple of links: administrator interface and web blog. Click the Add button, type Administrator interface in the Label field and /wplogin.php in the Destination field. A few additional details on this entry point must be stated. Two variables, for instance, log and pwd, are required to pass the login (the admin_name value) and password (the admin_password value) for auto-filling by the APS controller. The request method should be specified. Both login and password are sensitive data, and that is why the Post request method must be chosen. Add the Blog entry point specifying / as a destination value.
XML code:
<entry-points> <entry dst="/wp-login.php" method="POST"> <label>Administrative interface</label> <variable name="log" value-of-setting="admin_name"/> <variable name="pwd" value-of-setting="admin_password"/> </entry> <entry dst="/"> <label>Blog</label> </entry> </entry-points>
GUI interaction steps Switch to the Provision sub-tab. Make sure the configure script file that contains provisioning logic is implemented in full and exists in the Scripts folder. The general view of such a file looks similar to the following:
<?php # Collecting settings $admin_name = getenv('SETTINGS_admin_name'); $admin_password = getenv('SETTINGS_admin_password'); # etc. # Collecting DB info $db_id = 'main'; $db_type = getenv("DB_${db_id}_TYPE"); /*
52

DB_${db_id}_NAME DB_${db_id}_LOGIN DB_${db_id}_PASSWORD #optional DB_${db_id}_PREFIX DB_${db_id}_PORT */ # Collecting file system and url info $base_url_host = getenv("BASE_URL_HOST"); # mydomain.com $base_url_path = getenv("BASE_URL_PATH"); # /wordpress. If application is installed # in document root directory, BASE_URL_PATH = '/' /* #http or https BASE_URL_SCHEME #80 or 443 BASE_URL_PORT */ # /var/www/vhosts/mydomain.com/httpdocs/wordpress (Plesk) # /usr/local/pem/vhosts/1233445/webspace/siteapps/123/htdocs (POA) $root_dir = getenv("WEB___DIR");$blob_dir = getenv("WEB_blogs_media_DIR"); $command = $argv[1]; if($command == "upgrade") { upgrade_app($argv[2],$argv[3]); exit(0); } if($command == "install") { install(); exit(0); } if($command == "remove") { remove(); exit(0); } if($command == "configure") { configure(); exit(0); } print "Error: unknown command $command.\n"; exit(1); function upgrade_app($old_version, $old_release) { # calling native upgrade script } function install() { # creating database schema (tables) # populating database # writing config file }
53
function remove() { # removing DB tables - it is important for application that supports DB PREFIX } function configure() { # updating settings, url paths and other parameters # E.g.: updating DB record after admin login / password have been changed } ?>
A reference to that script file should be specified in the package. Click the Add button, and then Configuration script, browse for the script and choose a the script language, e.g. PHP. It is important to map URLs to directory or file paths. Add the URL mappings setting that serves as a site root, select that setting and click Add, to include the Mapping sub setting. Specify ID: /, browse for Path: htdocs (it is a sub-directory of Folder, where the application files are located). If you want the PHP interpreter to handle file extensions other than php, add the PHP handler sub setting and enumerate them using the extension detail field. Add other mappings that should be nested inside the root: wp-config.php, blogs/media, wp-content, tmp. All directories and files inside a mapping should be available for writing by the PHP interpreter, thus add the PHP permissions sub setting to each of the mappings.
54
XML code:
<provision> <configuration-script name="configure"> <script-language>php</script-language> </configuration-script> <url-mapping> <default-prefix>wordpress</default-prefix> <installed-size>6696960</installed-size> <mapping url="/" path="htdocs" xmlns:php="http://apstandard.com/ns/1/php"> <php:permissions writable="true"/> <php:handler> <php:extension>php</php:extension> </php:handler> <mapping url="wp-config.php"> <php:permissions writable="true"/> </mapping> <mapping url="blogs/media"> <php:permissions writable="true"/> </mapping> <mapping url="wp-content"> <php:permissions writable="true"/> </mapping> <mapping url="tmp"> <php:permissions writable="true"/> </mapping> </mapping> </url-mapping> </provision>
Updates tab GUI interaction steps The settings specified here define which earlier package versions can be upgraded to this one by means of upgrades or patches. Let us specify an upgrade condition that means significant changes will be brought into the contents of an earlier package. Click the Add button and fill in the Match field as follows: /application/version > '2.0' or /application/version = '2.0' and /application/release >= '1' In this case, the APS package starting from version 2.0-1 can be upgraded to the current version.
55
XML code:
<upgrade match="/application/version > '2.0' or /application/version = '2.0' and /application/release >= '1'"/>
Content tab Since WordPress is a simple shared application, it has nothing to do with PVC and no DLL registration is required. Since the Eclipse IDE has been used, there is no need to archive files; the package is automatically created inside the APS Package sub-folder of the APS project directory.
Validation, due to the Eclipse IDE with APS plug-in installed, is done automatically as well.
Finally, the test deployment of the WordPress package can be performed right from Eclipse. Make sure that you have access credentials to the Provider Control Panel of your internal POA and that Public API service is enabled. Navigate to Eclipse > Preferences; in the window that appears go to APS -> Compliant Panels. Click the Add button and select Parallels Automation Operation as a type. Specify a URL address of the host with POA installed and that of the Public API host, and enter valid credentials to log in to the corresponding Provider Control Panel and Public API access point. Click OK.
56
Next, navigate to Run -> Deploy APS Package, and in the window that appears select the POA site specified earlier as a host. Click Deploy.
As a result of successful deployment, a link to an instance of the application appears in the last line of the Console.
Note: If this is the first time the test deployment is performed, a request to specify POA Application ID and Resource Type ID appears.
57
Packaging Application for Dedicated Environment

The APS package creation for dedicated environment has the following peculiarities: The operating system requirement must be specified, for instance:
<requirements xmlns:env="http://apstandard.com/ns/1/environment"> <env:environment xmlns:env="http://apstandard.com/ns/1/environment"> <env:linux>redhat-as4</env:linux> </env:environment> </requirements>
PVC template as a delivery method must be specified, for instance:
<content xmlns:pvc="http://apstandard.com/ns/1/pvc"> <pvc:templates class="lin"> <pvc:archive-root path="/var/www/html/SugarCE-Full"/> <pvc:template path="templates/vzpem-sugarcrm-as4-template-20100410-1.0-1.i386.rpm"/> <pvc:template filename="vzpem-php5-cgi-as4"/> <pvc:template filename="vzpem-php-as4"/> <pvc:template filename="vzpem-mysql-client-as4"/> <pvc:template filename="vzpem-pgsql-client-as4"/> </pvc:templates> </content>
58
APS Package Creation The path attribute can be used to state that the template should be built-in inside the APS package.
Note: For details, refer to the PVC Aspect Specification, http://www.apsstandard.org/r/doc/aspect-pvc-1.2/index.html
59
Packaging Application for External Environment

The APS package creation for external environment has the following peculiarity: The access credentials and API parameters of the external service must be defined as globalsettings, for instance:
... <global-settings> <setting id="ox_host" class="title" type="string" default-value="" min-length="1"> <name>Open-Xchange installation host</name> <description> This is DNS name or IP address of Open-Xchange installation, used for provisioning access. </description> ... <setting id="ox_master_admin" class="title" type="string"> <name>Master Administrator Login</name> <error-message>Please make sure the text you entered starts with a letter and continues with either numbers, letters, underscores or hyphens.</error-message> </setting> <setting id="ox_master_password" class="title" type="password"> <name>Master Administrator Password</name> </setting> <setting id="ox_module_access" type="string" visibility="hidden" default-value="groupware"> <name>Open-Xchange administrator access level</name> <description> This is access level of Open-Xchange context administrator account. Valid values are 'webmail_plus', 'pim_plus', 'groupware', or any other defined in ModuleAccessDefinitions.properties file. </description> </setting> </global-settings> ...
60
Demo: Creating SpamExperts APS Package

SpamExerts is an external cloud service protecting mail boxes from spam messages. That is why it can be available through a provisioning gateway by creating APS connectors.
Planning SpamExperts APS Package

1 2 Sales model: Additional application for mail hosting Type of environment: SpamExperts is a cloud application accessible via its API. Therefore, we need an APS package of the external provisioning type. 3 Services hierarchy. SpamExperts provides two services: root service to declare domain integration sub-service to describe e-mail integration 4 Licensing procedure: The SpamExperts service is licensed per provider. The license itself is the login and password pair to access an API host and is issued by the SpamExperts company manually. There is no licensing workflow inside an APS package. 5 Technologies used: PHP 5.2 or higher qmail hosting 6 7 Application settings. SpamExperts requires the following settings on installation: List of domains where spam detection should be performed. Content delivery method: Since SpamExperts is an external application, package scripts must deliver the service.
61
Developing SpamExperts APS Package

Create a new APS project in Eclipse, specify its name, location and an APS version to be used in the metadata file. Overview tab GUI interaction steps: Specify the following mandatory values: Application ID: http://www.spamexperts.com/, Name: APS_SpamExperts, Version: 1.5, Release: 1. XML code:
<id>http://wordpress.org/</id> <name>APS_SpamExperts</name> <version>1.5</version> <release>1</release>
Presentation tab GUI interaction steps Changelog sub-tab: Version: 1.5, Release: 1, Entry: SpamExperts release notes: built at <current date and time> Other sub-tab: Category: Collaboration/Email XML code:
<presentation> <summary></summary> <changelog> <version version="1.5" release="1"> <entry>SpamExperts release notes: built at 12-12-2011 09:39 </entry> </version> </changelog> <categories> <category>Collaboration/Email</category> </categories> </presentation>
Global Settings tab GUI interaction steps Because SpamExperts is an application of external provisioning, the following applicationspecific global settings must be declared: 62 SpamPanel URL (a URL leading to the web host where SpamPanel, used to manage antispam settings, is installed):
APS Package Creation ID: spampanel_url, Type: string, Class: access_point API access host (DNS or IP address of the master host where the SpamExpert API product is installed): ID: apihost, Type: string, Class: title API access login: ID: apilogin, Type: string, Class: title API access password: ID: apipass, Type: password, Class: title SSL (Enable/Disable SSL to communicate with APIs): ID: ssl_enabled, Type: boolean, Default value: True MX record (MX record that substitutes ones in user domains, and is required to redirect incoming e-mails for spam detection): ID: mx_primary, Type: string, Class: title
63
XML code:
<global-settings> <group class="authn"> <name>SpamPanel Settings</name> <setting id="spampanel_url" class="access_point" type="string"> <name>SpamPanel URL</name> </setting> </group> <group> <name>API Settings</name> <setting id="apihost" class="title" type="string"> <name>API hostname</name> </setting> <setting id="apilogin" class="title" type="string"> <name>API login</name> </setting> <setting id="apipass" class="title" type="password"> <name>API password</name> </setting> <setting id="ssl_enabled" class="title" type="boolean" default-value="true"> <name>SSL</name> </setting> </group> <group> <name>MX record</name> <setting id="mx_primary" class="title" type="string"> <name>Primary MX</name> </setting> </group> </global-settings>
Services tab SpamExperts is a multi-tenant application, therefore, a hierarchy of services should be declared: Domain integration root service and E-mail integration sub-service.
64
GUI interaction steps Root Service: General sub-tab: ID: SpamExpertsDomain, Class: service XML code:
<service id="SpamExpertsDomain" class="service">
Settings sub-tab: Domains to replace MX records in (that is, domain integration): ID: domains, Type: list, Element type: string, Class: domain-name, Visibility: hidden, Protected: true Domains to login for: ID: login_domains, Type: string, Class:value, Visibility: hidden, Protected: true Password to Login into SpamPanel: ID: domain_password, Type: password, Class: password, Visibility: hidden, Protected: true Email to send protection reports to: ID: email, Type: email, Class value, Visibility: hidden, Optional: true Number of domains: ID: num_domains, Type: string, Visibility: hidden Number of service users: ID: num_serviceusers, Type: string, Visibility: hidden
65
XML code:
<settings> <setting id="domains" class="domain-name" visibility="hidden" protected="true" type="list" element-type="string"> <name>List of domains</name> </setting> <group class="authn"> <setting id="login_domains" class="value" type="string" visibility="hidden" protected="true"> <name>List of domains</name> </setting> <setting id="domain_password" class="password" type="password" visibility="hidden" protected="true"> <name>Password</name> </setting> </group> <group class="vcard"> <group class="email"> <setting id="email" class="value" visibility="hidden" type="email" optional="true"> <name>Your e-mail address</name> </setting> </group> </group> <setting id="num_domains" type="string" visibility="hidden"> <name>Amount of domains allowed</name> </setting> <setting id="num_serviceusers" type="string" visibility="hidden"> <name>Amount of service users allowed</name> </setting> </settings>
Resources sub-tab. The following settings can be limited as resource objects and the application will report the value of their consumption: Number of domains:ID: num_domains_res, Class: item, Limiting setting: num_domains Number of service users: ID: num_serviceusers_res, Class: item, Limiting setting: num_serviceusers
XML code:
<resources> <resource id="num_domains" class="item" limiting-setting="num_domains"> <name>Number of domains</name> </resource> <resource id="num_serviceusers" class="item" limiting-setting="num_serviceusers"> <name>Number of service users</name> </resource> </resources>
Requirements sub-tab: PHP interpreter with two extensions must be installed on a provisioning gateway for the service configuration script to be executed: min version: 5.2, extension: openssl, extension: curl MX record is obligatory to present in domains: ID: MX_req, Record type: mx. Some MX specific attributes should be defined: Source: external, Value of setting: domains (List of domains to replace MX records in), Destination: external, Value of setting: mx_primary (MX record that substitutes ones in user domains).
XML code: 66

<requirements xmlns:php="http://apstandard.com/ns/1/php" xmlns:dns="http://apstandard.com/ns/1/dns"> <php:version min="5.2" /> <php:extension>openssl</php:extension> <php:extension>curl</php:extension> <dns:record> <dns:id>MX_req</dns:id> <dns:mx> <dns:src> <dns:external value-of-setting="domains"/> </dns:src> <dns:dst> <dns:external value-of-setting="mx_primary"/> </dns:dst> <dns:substitute/> </dns:mx> </dns:record> </requirements>
Entry Points sub-tab: Access point to login into SpamPanel of user domains: Label: SpamExperts ControlPanel, Destination: {spampanel_url}/bridgelogin.php, Request method: POST, Variable: spampanel_url_var, Value of setting: spampanel_url, Variable: domains_var, Value of setting: login_domains, Variable: password_var, Value of setting: domain_password
XML code:
<entry-points> <entry dst="{spampanel_url}/bridgelogin.php" method="POST"> <label>Antispam Controlpanel</label> <variable name="spampanel_url_var" value-of-setting="spampanel_url" /> <variable name="domains_var" value-of-setting="login_domains" /> <variable name="password_var" value-of-setting="domain_password" /> </entry> </entry-points>
Provision sub-tab: Verify that, configuration and resources scripts are placed into Scripts folder and add a reference to them.
XML code:
<provision> <configuration-script name="configure.php"> <script-language>php</script-language> </configuration-script> <resource-script name="report-resources.php"> <script-language>php</script-language> </resource-script> </provision>
Sub-service: General sub-tab: ID: SpamExpertsEmail Class: account XML code:
<service id="SpamExpertsEmail" class="account">
67
APS Package Creation Settings sub-tab: ID: user_login, Type: email, Class: login, Protected: true, Unique: global ID: user_password, Type: password, Class: password, Protected: true
68
XML code:
<settings> <group class="authn"> <setting id="user_login" class="email" protected="true" type="login" uniq="global"> <name>Primary email address</name> </setting> <setting id="user_password" class="password" protected="true" type="password"> <name>Password</name> </setting> </group> </settings>
Requirements sub-tab: PHP interpreter with the same two extensions Mailbox: ID: mail, imap: true, smtp: true
XML code:
<requirements xmlns:mail="http://apstandard.com/ns/1/mail" xmlns:php="http://apstandard.com/ns/1/php"> <php:version min="5.2" /> <php:extension>openssl</php:extension> <php:extension>curl</php:extension> <mail:mailbox> <mail:id>account</mail:id> <mail:access> <mail:imap/> </mail:access> <mail:outgoing> <mail:smtp/> </mail:outgoing> </mail:mailbox> </requirements>
Entry Points sub-tab: Access point to log in to the dashboard of SpamPanel dedicated to a service user: Label: SpamExperts UserDashboard, Destination: {spampanel_url}/index.php, Request method: POST, Variable: spampanel_url_var, Value of setting: spampanel_url, Variable: username_var, Value of setting: user_login, Variable: userpassword_var, Value of setting: user_password
XML code:
<entry-points> <entry dst="{spampanel_url}/index.php" method="POST"> <label>SpamExperts UserDashboard</label> <variable name="spampanel_url_var" value-of-setting="spampanel_url" /> <variable name="username_var" value-of-setting="userlogin" /> <variable name="userpassword_var" value-of-setting="userpassword" /> </entry> </entry-points>
Provision sub-tab: Make sure, that the configuration script is placed into the Scripts folder and add a reference to it.
XML code: 69

<provision> <configuration-script name="configure-mail.php"> <script-language>php</script-language> </configuration-script> </provision>
After development is complete, perform the test deployment the same way as described for WordPress.
70
Package Certification
Once the APS package is ready, contact the APS support team (http://www.apsstandard.org/support/) for credentials to get an access to the APS Certification System, and then: Login to the APS Certification System (https://apscatalog.com/packager/admin/) using the given credentials. Upload the APS package to the APS Catalog by clicking the Upload new package button.
71
APS Package Creation When the process is complete, details on each test are displayed. Depending upon the results, the application receives a certification level according to the APS Application Certification Criteria.
Resolve APS package issues, if any, and request the application publication (http://www.apsstandard.org/certification/app/).
Note: For more information, refer to the APS Package Certification Guide available at http://www.apsstandard.org/r/doc/APS_Package_Certification_Guide/index.h tm
72
Check Your Progress

Before continuing on to the next chapter, ensure that you are able to answer the following questions. If you cannot answer a question, please re-read the corresponding materials. 1 2 3 Which provisioning method does an APS package with the External System provisioning type use? What conveniences do the Eclipse IDE and APS plug-in bring? Assume that you have already packaged and tested the APS application. What else do you need to do to publish the application within the APS catalog?
73
MODULE 4
Deployment in Parallels Automation

APS deployment in POA involves the following stages: Importing the APS package Configuring the hosting platform Creating resource types Creating a service template Creating a service plan
In This Module
Importing APS Package .......................................................................................... 76 Configuration of Provisioning Environment ............................................................... 77 Resource Configuration........................................................................................... 78 Service Template .................................................................................................... 83 Service Plan............................................................................................................ 85 Check Your Progress .............................................................................................. 86
75
Importing APS Package

In the POA provider control panel, generally there are different ways to import an APS package into POA. 1 Certified APS packages can be downloaded from the APS catalog. Make sure the proper URL is specified at Operations Director > Application Manager > APS Catalog, on the Catalog settings tab. Navigate to Service Director > Application Manager > APS Catalog, select the applications you want to be available in POA, and then click the Import Packages button. 2 Any APS package regardless of its certification status can be imported. Navigate to Operations Director > Application Manager > Applications. Click Import Package. Select one of sources, URL or local file. Each application can have a number of versions available. An application version is ready to be used only if it is selected as Enabled (available for subscriptions).
76
Configuration of Provisioning Environment

One or several hosts (or provisioning gateways) with software installed, which meets all the APS package requirements, must be prepared for application provisioning. A common procedure starts with registering a hardware node in POA and then, depending on the application, different software should be installed on it such as: Web hosting: Apache or IIS with APS.NET PHP or Perl
Database: MySQL, PostgreSQL or Microsoft SQL Server
Note: For more information, refer to the POA Application Hosting, POA Linux Shared Hosting and POA Windows Shared Hosting Deployment Guides.
Mailbox: The qmail service
Note: For more information, refer to the POA Linux Mail Hosting Deployment Guide.
77
Resource Configuration
In POA, services are provisioned to customers through Resource Types. The main Resource Type must be configured to provide the root service of the application. Additionally, it is possible to create Resource Types for sub-services and application resources.
78
Resource Types
There are two ways to create an APS-related Resource Type: On the basis of Site Applications Resource Class. Only APS packages of the web shared provisioning type can use this Resource Class. A number of such applications can be installed in the same web site. On the basis of the Application resource class, often called a SaaS Application. Any type of APS package can be used to provision the service.
Besides the main application resource, there might be two other Resource Types related to SaaS: Application Service Resource Type allows specifying of additional parameters or setting limits for services other than the root service, as defined inside the application APS package; for example
... <service id="context" class="service"> ... <service id="account" class="account"> <setting id="user_module_access" type="string" visibility="hidden" default-value="groupware"> <name>Open-Xchange module access level for End-user</name> <description> This is access level of Open-Xchange account. </description> </setting> <setting id="upload_message_limit" type="string" visibility="hidden" default-value="100"> <name>Maximum size of all attachments in one message (in bytes) </name> </setting> <setting id="upload_attachment_limit" type="string" visibility="hidden" default-value="10"> <name>Maximum size of one attachment, maximum size of one InfoStore item (in bytes) </name> </setting> ... </service> ... </service> ...
The definition above looks in POA as follows:
79
Application Resource Resource Type that allows accounting for resources, as defined inside the APS package; for example,
... <service id="context" class="service"> ... <resources> <resource id="filestore_diskusage" class="mb" limiting-setting="filestore_quota"> <name>Disk space used by Open-Xchange context infostore files. </name> </resource> </resources> ... </service> ...
In the code extract above, the application reports disk quota usage to the APS controller.
Note: For details, refer to the POA Application Hosting Deployment Guide.
80
Activation Parameters
While creating the Application Resource Type, the activation parameters should be specified. There are two types of activation parameters natively related to the application APS package: Global settings. Changes impact all existing instances of the application, which are provisioned on the basis of this Resource Type. Global settings are defined inside the metadata file of the application APS package, for example,
... <global-settings> <setting id="ox_host" class="title" type="string" default-value="" min-length="1"> <name>Open-Xchange installation host</name> <description>This is DNS name or IP address of Open-Xchange installation, used for provisioning access. </description> </setting> </global-settings> ...
Such a definition looks as follows in POA:
81
Deployment in Parallels Automation Default settings. These are initial settings for a newly created instance of the application root service. Such settings are defined inside the metadata file of the application APS package, for example,
... <service id="context" class="service"> ... <setting id="filestore_quota" type="string" visibility="hidden" default-value="1024"> <name>Open-Xchange context wide filestore quota (in MB)</name> </setting> <setting id="admin_tz" class="tz" type="enum" visibility="hidden" default-value=""> <name>Default time zone</name> </setting> <group class="branding"> <setting id="branding_theme" class="branding_theme" type="string" visibility="hidden" default-value=""> <name>Branding scheme name</name> </setting> </group> ... </service> ...
The definition above looks as follows in the POA Provider Control Panel:
82
Service Template
An APS application can be installed in a certain environment, and thus depends on other resources, such as web space, disk space, database, and other. Depending on which APS-related Resource Type is chosen, the minimal contents of the Service Template differ: If the Site Applications Resource Type is used, a physical hosting Resource Type and other required resources must be added into the same Service Template explicitly. In this case, an application is just an add-on object for a web site. For the Application Resource Type, the application uses an environment created for this application exclusively: web space, or a PVC container, or a special tenant. It is sufficient to include the Application Resource Type only, and then bind resource types existing in the system to it using the provisioning attributes as described earlier.
In case of using an APS resource based on the Application Class the other required resources must be selected by the provisioning system due to the links between the resources. It means, you need to add only the APS resource to a service template, since all other required resources will be added at the provisioning stage. Both Application Resource Type and additional resource types should have the same provisioning attribute as the hardware nodes do. Moreover, Backup Resource Type and the associated hardware node should have an additional provisioning attribute to prevent the chaotic backup done to different machines:
83
84
Service Plan
Service plan defines application components (and possibly their quantity) that can be purchased by a customer. Service plans are based on service templates combined with terms and prices. Service Plan is created by following a typical procedure in PBA (Parallels Business Automation). A customer can purchase additional application-related objects as options using resource rates. Services due to Application Service Resource Types. Resource limits due to Application Resource Resource Types. Licenses due to the APS License Class with a class identifier matching the API constant of the application-specific license as defined in Key Administrator Remote API Guide. Preliminarily, the application vendor's license service must be integrated with the Parallels Key Administrator service to make the license obtaining available. At the moment that an application instance needs a license, Parallels Automation requests it from the Parallels Key Administrator. The Parallels Key Administrator forwards this request to the vendor's licensing service. The vendor's licensing service issues the license and sends it back.
Note: For details about creating service plans, refer to the PBA Provider's Guide.
85
Check Your Progress

Before continuing on to the next chapter, ensure whether you are able to answer the following questions. If you cannot answer a question, please reread the corresponding training materials. 1 Should a Service Template with an Application Resource Type contain additional Resource Types the application depends on? What is the difference between Global and Default settings? What APS-related objects can be sold as resource rates?
2 3
86
MODULE 5
Provisioning in Parallels Automation

In This Module
Application Installation, Configuration, Removal and Updating ................................. 88 Configuration Runner.............................................................................................. 89 Integration with Service Users ................................................................................. 91 Integration with Domains ........................................................................................ 92 Integration with Mailboxes ...................................................................................... 93 Check Your Progress ............................................................................................. 94
87
Application Installation, Configuration, Removal and Updating

Applications requiring some parameters need to be installed manually from the POA customer control panel (CCP). After buying a a service plan with APS resources, a customer will have a new subscription valid during a selected period. Using the subscription resources, the customer will be able to perform the following operations. 1 In the CCP, select a target application to install from the left-side navigation menu or from the Applications list depending whether the Resource Type general activation parameter "Show application in navigation menu" is enabled or disabled. Click Create (or Install New Application if the Applications item was clicked in step 1) and then specify settings in the empty fields, if any.
88
Provisioning in Parallels Automation 3 Verify that all application entry points work properly.
Applications instances in shared web spaces are placed into the following directories on a hosting machine: Linux: /usr/local/pem/vhosts/<Webspace ID>/siteapps/<Application Instance ID>/ Windows: C:\Customer data\webspace_<Webspace ID>\webapps\SiteApp<Application Instance ID>\
Dedicated application instances are placed into directories inside a PVC container as specified in the PVC application templates. Provisioning scripts for external application processing are placed into the following directories on a gateway machine: Linux: /usr/local/pem/APS/instances/<Application Instance ID>/ Windows: C:\Program Files\SWsoft\pem\APS\instances\<Application Instance ID>\
To reconfigure application setting: 1 2 3 4 In CCP, select the target application. Open the Settings tab of the application and click Edit. Change settings and then click Submit. After the application receives the Ready status, verify that the setting has been changed in the application instance.
To uninstall the application: 1 2 In CCP, select the target application. Open the Settings tab of the application then click Uninstall.
To update the application: 1 2 3 In CCP, select the target application. Open the Settings tab of the application and click Upgrade. All the instances can be upgraded from the Provider Control Panel as well.
Configuration Runner
In order to perform one of operations over an application instance (install, configure, upgrade, or remove), the APS controller must create the runner.sh file in the provisioning environment that will start a script and provide needed parameters as environment variables. The content of the runner.sh file in a Linux OS may look as in the following examples.
89
Example of Runner in Web Shared Environment

An APS application is processed by the configure script which output looks similar to the following when it upgrades an application:
env 'WEB__tmp_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/tmp' 'WEB__modules_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/modules' 'WEB__data_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/data' 'WEB__custom_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/custom' 'WEB__config.php_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/confi g.php' 'WEB__cache_DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs/cache' 'WEB___DIR=/usr/local/pem/vhosts/100004/webspace/siteapps/34/htdocs' 'SETTINGS_title=SugarCRM' 'SETTINGS_send_usage_statistics=true' 'SETTINGS_check_for_updates=manual' 'SETTINGS_admin_password=1q2w3e' 'SETTINGS_admin_name=admin' 'SERVICE_ID=instance' 'PHP_VERSION=5.2.17' 'DB_main_VERSION=5.0.83' 'DB_main_TYPE=mysql' 'DB_main_PASSWORD=qg7tZpzVUuJG8VXS' 'DB_main_NAME=db1_sa34_main' 'DB_main_LOGIN=u1_sa34' 'DB_main_HOST=10.30.2.182' 'BASE_URL_SCHEME=http' 'BASE_URL_PATH=sugarcrm/' 'BASE_URL_HOST=z.mn.arena.aps.sw.ru' 'BASE_IP_ADDRESS=10.30.2.182' /usr/bin/php-cgi -d open_basedir= -q configure 'upgrade' '5.5.1' '5.6.0'
In the example, the PHP based script configure is called after all environment variable are set. It requires upgrade from version 5.5.1 to version 5.6.0.
/usr/bin/php-cgi -d open_basedir= -q configure 'upgrade' '5.5.1' '5.6.0'
Example of Runner in Provisioning Gateway

Below is the content of the runner.sh file when a configuration for contact basic with email address basic@automatic.com is required in a provisioning gateway connected to an external application.
#!/bin/sh cd /usr/local/pem/APS/instances/11/scripts env 'OLDSETTINGS_display_name=basic' 'OLDSETTINGS_email1=basic@automatic.com' 'SERVICE_ID=contact' 'SETTINGS_admin_login=vfilatov121' 'SETTINGS_admin_password=7654321' 'SETTINGS_business_mobility_service=mobile' 'SETTINGS_cellular_telephone1=' 'SETTINGS_city_business=' 'SETTINGS_contact_id=' 'SETTINGS_country_business=' 'SETTINGS_debug=on' 'SETTINGS_department=' 'SETTINGS_display_name=basic' 'SETTINGS_email1=basic@automatic.com' 'SETTINGS_fax_business=' 'SETTINGS_first_name=basic' 'SETTINGS_horde_enable_migration=false' 'SETTINGS_horde_url=' 'SETTINGS_last_name=' 'SETTINGS_note=' 'SETTINGS_ox_antispam=false' 'SETTINGS_ox_host=10.39.94.115' 'SETTINGS_ox_master_admin=oxadminmaster' 'SETTINGS_ox_master_password=1234567' 'SETTINGS_ox_module_access=all' 'SETTINGS_ox_site=http://ox.pasupport.plesk.ru' 'SETTINGS_postal_code_business=' 'SETTINGS_public_contact_folder=' 'SETTINGS_public_contact_folder_id=' 'SETTINGS_state_business=' 'SETTINGS_street_business=' 'SETTINGS_telephone_business1=' 'SETTINGS_telephone_home1=' php -q configure-contact.php configure
The configure-contact.php script with the configure command is called after setting all needed environment variables:
php -q configure-contact.php configure
90
Integration with Service Users

Service users gain access to installed applications via the MyCP control panel. MyCP provides all application functionality for service users including entry-points. To integrate a service user with an application: 1 2 3 4 5 Access the target application via the navigation menu of the customer control panel. Open the Service Users tab and click Add. Choose the appropriate service user to add to the application. Wait until the service user is provisioned. Verify that the service user's entry point works correctly.
To create a new service user and integrate him with applications at once: 1 2 3 4 5 6 7 Open the Service Users item of the customer control panel navigation menu. Click the Add New Service User button. Specify Display name, Login and Password. Select services you would like to integrate the new user with and click Next. To confirm the new service user creation, click Finish. Wait until the new service user is provisioned. Verify that the service user's entry point works correctly.
91
Integration with Domains

To integrate an application that is going to be provisioned with a domain: 1 2 3 4 5 6 On the All Domains tab of the customer control panel, create a domain or subdomain to be used in the subscription. Access an application via the navigation menu of the customer control panel. Begin installing the application. Select the created domain to be owned by the application. Click Finish to complete installation. Make sure the domain has appeared in the Sites & Domains item of the CCP navigation menu and the A record appeared in it.
Note: If an application modifies an existing DNS record (typically MX record), make sure that it has been replaced with the one required by the application.
92
Integration with Mailboxes

To integrate an application with a mailbox of a service user: 1 2 3 4 5 Open the Service Users item in the customer control panel navigation menu. Make sure you have a service user with an assigned mailbox. Install the application. Register the service user in the application (refer to the Integration with Service Users topic in this module). Navigate to the E-mail > E-mail addresses menu to verify that the Open Web Mail link works properly for the service user.
93
Check Your Progress

Before continuing on to the next chapter, ensure whether you are able to answer the following questions. If you cannot answer a question, please reread the corresponding training materials. 1 2 What are major APS-related provisioning operations? Is the following statement true? If a customer updates an application, a newer version of the APS package will be imported into POA.
94
MODULE 6
Troubleshooting in Parallels Automation

In This Module
Troubleshooting Tools ............................................................................................ 96 Importing APS Packages ........................................................................................ 97 Debugging APS Configuration Scripts ..................................................................... 98 Special Cases in Customer Control Panel ............................................................... 100 Check Your Progress ............................................................................................. 101
95
Troubleshooting Tools
For APS, there are troubleshooting tools that can be used at different APS package life cycle stages. 1 2 3 In Eclipse, the APS player helps to debug the APS package at the package development and creation stage. It works with APS packages targeted on the external provisioning type. In POA, the task log is used for analyzing issues when a package is being imported and at the provisioning stage. The runner.sh script in the provisioning environment allows to re-execute the last provisioning task.
APS Player
APS plug-in in Eclipse IDE allows provisioning APS package of the external provisioning type in the test mode, i.e. without any APS-compliant product, by means of the following operations. Create, recreate, change and remove hierarchy of services Call configuration scripts and display their output Execute provisioning scripts on PHP Execute provisioning scripts on jscript and vbscript. Collect and show resource usage and display output of root service's resource script Satisfy requirements (define environment variables)
96
Importing APS Packages

Symptom The application shows no details in the General tab, the icon associated with the application is missing in the list of installed applications in the POA provider control panel (Service Director > Application Manager > Applications), and a message displays: Importing error or Application importing is in progress. Probable cause The error is caused either by an invalid APS package or by a bad network connection to the server. Diagnostics 1 2 In the POA provider control panel, go to Service Director > Task Manager. Use the filter to search for the task by the Application ID or by the Failed or Rescheduled status (if the task has failed due to an error in the metadata, you may search the task using a wildcard; for example, *NNNN*, where NNNN is the instance ID). Click the task link to view the error cause.
Solution 1 2 Cancel the task by clicking the Cancel Task button, if the APS package is shown as invalid in the task description. Then fix the APS package and import it again. If the error is caused by a failed network connection, click the Run Task button to rerun the task, once the connection is established or recovered.
97
Debugging APS Configuration Scripts

Shared Web Provisioning Type
To debug a task associated with an APS package of the Shared Web provisioning type, perform the following steps. 1 2 3 4 5 6 Navigate to Service Director > Applications Manager > Applications and select the required application by clicking the corresponding link. Click the Instances tab to learn which provisioning host (the Hardware Host column) and web space (the Webspace ID column) the required instance is using. Navigate to System Director > Task Manager, find the failed task associated with the application instance, and click its name. Save all of the environment variable values and the script name they are used by from the Last execution output field into the runner.sh file. Cancel the failed task associated with the application instance. Login to the provisioning host via SSH and execute cd /usr/local/pem/vhosts/<Webpsace ID>/webspace/siteapps/<Application Instance ID>/. Place runner.sh into the scripts directory. Execute runner.sh to output to script execution result. Access the scripts directory and fix the script that causes errors.
7 8 9
10 Execute runner.sh again to verify that the script execution returns no errors. 11 Modify runner.sh to verify the execution result of other scripts and functions, if needed. 12 When all the errors are resolved, import the revised APS package with an increased release number.
98
External System Provisioning Type

To debug a task associated with an APS package of the External System provisioning type, perform the following steps. 1 2 3 4 5 6 7 8 9 Navigate to Service Director > Application Manager > Applications and select the required application by clicking the associated link. Click the Instances tab to learn which provisioning gateway (the Hardware Host column) the required instance is using. Navigate to System Director > Task Manager and cancel the failed task associated with the application instance Log in to the provisioning gateway of the application instance via SSH. Execute cd /usr/local/pem/APS/instances/<Application Instance ID>. Execute runner.sh to output to script execution result. Access the scripts directory and fix the script that causes errors. Execute runner.sh again to verify that the script execution returns no errors. Modify runner.sh to verify the execution result of other scripts and functions, if needed.
10 When all the errors are resolved, import the revised APS package with an increased release number.
99
Special Cases in Customer Control Panel

Empty Value
Symptom: During update of an application instance, an error message appears with a notification similar to: '' is not a valid value for setting '' for application (id = 21). Invalid value passed for setting 'admin_email': No @ at address Please contact your provider. Probable cause: The new version of the APS package contains a new setting (mail address in the above example). The update is not interactive, thus the application owner is not able to provide a value for the requested parameter. Default value was not assigned in the setting. That is why the update is not possible. Workaround: Temporary add some default value, either in the metadata or in the resource type of the Application resource class. Notify the customer to change the default value to a proper value after update.
Unforeseen Error
Symptom: During installation of an application instance, an error message appears notifying about unforeseen error. Probable cause: This might happen if an existing version of an APS package was imported to POA, but the user session still keep old IDs of the application configuration cached. Recommended solution: Recommend the user to restart the POA session.
100
Check Your Progress

Before continuing on to the next chapter, ensure whether you are able to answer the following questions. If you cannot answer a question, please re-read the corresponding training materials. 1 The application shows no details in the General tab, and the icon associated with the application is missing in the list of installed applications in POA. What diagnostic steps would you recommend? Describe the main steps of the application script debugging process for the external provisioning type.
101
APPENDIX A
Check Your Progress

In This Appendix
Module 1. Introduction............................................................................................ 104 Module 2. Package Structure ................................................................................. 105 Module 3. APS Package Creation ........................................................................... 106 Module 4. Deployment in Parallels Automation ........................................................ 107 Module 5. Provisioning in Parallels Automation ........................................................ 108 Module 6. Troubleshooting in Parallels Automation .................................................. 109
103
Check Your Progress
Module 1. Introduction
1 2 What benefits does APS provide for application vendors? Access to the channel of APS-enabled service providers. What is the difference between the SaaS business model and the standard application purchasing model? Customers subscribe to the target application and get on-demand access versus purchasing the application. 3 What are the main stages of the APS life cycle? Packaging Deployment Provisioning
104
Check Your Progress
Module 2. Package Structure

1 What types of components can be included in the APP-META.xml file? services user configuration entry points platform requirements 2 3 Can you miss out service declaration in the metadata file? No, you cannot. The metadata file must have at least the root service declared. Which class must be assigned to a service used for integrating application instances with users? account 4 What operations can be performed by the configuration script? install configure upgrade remove
105
Check Your Progress
Module 3. APS Package Creation

1 Which provisioning method does an APS package with the External System provisioning type use? Only provisioning scripts. 2 3 What conveniences do the Eclipse IDE and APS plug-in bring? Automated validation, archiving, deployment and publishing of APS packages Assume that you have already packaged and tested the APS application. What else do you need to do to publish the application within the APS catalog? Successfully complete the certification procedure.
106
Check Your Progress
Module 4. Deployment in Parallels Automation

1 Should a Service Template with an Application Resource Type contain additional Resource Types the application depends on? No, it should not. It's quite sufficient just to use correct provisioning attributes. 2 What is the difference between Global and Default settings? Global settings: changes affect all existing instances of an application Default settings: initial settings for a newly created instance of an application service 3 What APS-related objects can be sold as resource rates? Services (components) Resources Licenses
107
Check Your Progress
Module 5. Provisioning in Parallels Automation

1 2 What are major APS-related provisioning operations? Installation, reconfiguration, removal, and upgrading Is the following statement true? If a customer updates an application, a newer version of the APS package will be imported into POA. No, it is not. Customers are allowed to update only the application instances they own.
108
Check Your Progress
Module 6. Troubleshooting in Parallels Automation

1 The application shows no details in the General tab, and the icon associated with the application is missing in the list of installed applications in POA. What diagnostic steps would you recommend? Investigate the Task log. Examine the APS package for errors. Verify the connection to the catalog server. 2 Describe the main steps of the application script debugging process for the external provisioning type. In the POA PCP, find where the application instance is installed. Log in to the provision host with SSH. Navigate to the application instance folder. Modify and execute runner.sh to debug the task.
109

Application Packaging Standard: Development and Implementation

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Application Packaging Standard: Development and Implementation

Uploaded by

Copyright:

Available Formats

Application Packaging Standard: Development and Implementation

Package Structure ................................................................................................... 17

Provisioning Logic ......................................................................................................... 30

Check Your Progress .................................................................................................... 33

APS Package Creation ............................................................................................ 35

Packaging Application for Shared Web Environment ...................................................... 39

Package Certification .................................................................................................... 71 Check Your Progress .................................................................................................... 73

Deployment in Parallels Automation....................................................................... 75

Provisioning in Parallels Automation ...................................................................... 87

Troubleshooting in Parallels Automation................................................................ 95

Importing APS Packages............................................................................................... 97 Debugging APS Configuration Scripts............................................................................ 98

Special Cases in Customer Control Panel .................................................................... 100

Check Your Progress .................................................................................................. 101

Check Your Progress ............................................................................................ 103

Use pctl start to start a container.

Preformatted Bold CAPITALS KEY+KEY

Shell Prompts in Command Examples

# $PRODUCT_ROOT_D/bin/<utility name> [parameters] [options]

# /usr/local/psa/admin/bin/<utility name> [parameters] [options]

SaaS Business Model

APS Application Life Cycle

Check Your Progress

Structure of APS Package

Common Package Information

The root service is mandatory in an application package. Example of nested services:

<settings> <group class="authn"> <name>Administrator's preferences</name>

NOTE: Get more details on settings attributes at http://www.apsstandard.org/r/doc/package-formatspecification-1.2/index.html#s.metadata.service.settings.

This is an example of the URL mapping rules.

Integration with Service Users

Integration with Domains

<setting id="domains" class="domain-name" type="list" element-type="string"> </setting>

Integration with Mailboxes

<mail:access> <mail:imap/> </mail:access>

Outgoing mail server requirement:

<mail:outgoing> <mail:smtp/> </mail:outgoing>

Check Your Progress

APS Package Creation

APS Package Creation

Planning APS Package

APS Package Creation

Developing APS Package

APS Package Creation

APS Package Creation

Packaging Application for Shared Web Environment

APS Package Creation

Demo: Creating WordPress APS Package

APS Package Creation

Developing WordPress APS Package

APS Package Creation 4 Click Finish.

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation

APS Package Creation