Application Packaging Standard - Package Format Specification

<sa:name>phpbb</sa:name>

Free-formed string specifies user-visible name of web application in a package. Package name is a package identifier - it MUST NOT be changed in consequent versions of packages, otherwise package upgrade and patch from older versions will be not feasible.

<sa:packager-uri>uuid:15d041e8-34c6-409a-b165-3290d2c9d599</sa:packager-uri>

Arbitrary URI unique for each packager (it is RECOMMENDED to use uuid: URI scheme to minimize the possibility of clash). This URI is needed to distinguish packages with the same name but created by different packagers. Note that consequent versions of the same package MUST have the same URI, as otherwise package Controllers MAY refuse to update package from one version to another.

Controllers SHOULD allow to upgrade and patch package from the version which does not specify packager-uri to the one which specifies to support smooth upgrade path for the packages which did not use packager-uri from the beginning.

<sa:version>2.0.22</sa:version>
<sa:release>6</sa:release>

Package version consists of two parts: application version and package release, the former corresponds to the version of application packaged, and the later to the release of the package containing the same version of application (packages may be released many times, e.g., for fixing bugs in packaging or adding localizations).

Version format and the algorithm for determining the chronological relationship between different Package versions are specified by the Debian Policy: Version Format in Debian Policy.

Unlike the Debian's version-release approach, application version and package release are separated to ease parsing.

<sa:homepage>http://phpbb.com/</sa:homepage>

URL of the web application official site.

<sa:package-homepage>http://swsoft.com/</sa:package-homepage>

URL of the application packager official site.

<sa:default-prefix>/forum/</sa:default-prefix>

Relative URL with the default path where the application is supposed to be installed on domain.

<sa:summary>High powered, fully scalable, and highly customizable Open Source bulletin board package.</sa:summary>
<sa:summary xml:lang="es-ES">...</sa:summary>

Single-sentence summary of the package for end users.

<sa:description>
  phpBB is a high powered, fully scalable, and highly customizable
  Open Source bulletin board package. phpBB has a user-friendly
  interface, simple and straightforward administration panel, and
  helpful FAQ. phpBB is the ideal free community solution for all web
  sites.
</sa:description>
<sa:description xml:lang="it-IT">...</sa:description>

One-paragraph description of the package for end users.

<sa:icon path="images/phpbb.png" />

Icon may be provided to be displayed in GUI for the application. The path attribute MUST contain full path in archive to the 64x64 pixels image file. Icon MUST be in JPEG, PNG or TIFF formats.

<sa:screenshot path="images/admin.png">
  <sa:description>Administrative interface</sa:description>
  <sa:description xml:lang="he-IL">...</sa:description>
</sa:screenshot>
<sa:screenshot path="images/main.png">
  <sa:description>Main page</sa:description>
  <sa:description xml:lang="ja-JA">...</sa:description>
</sa:screenshot>

Several screenshots with descriptions may be provided. The path attribute MUST contain full path in archive to the image. Images MUST be in JPEG, PNG or TIFF formats.

<sa:license must-accept="true">
  <sa:text>
    <sa:name>GPLv2</sa:name>
    <sa:file>licenses/gplv2.txt</sa:file>
  </sa:text>
  <sa:text xml:lang="de-DE">
    <sa:name>GPLv2</sa:name>
    <sa:file>licenses/gplv2-de_DE.txt</sa:file>
  </sa:text>
<sa:license>
        

or

<sa:license>
  <sa:text>
    <sa:name>Revised BSD</sa:name>
    <sa:url>http://opensource.org/licenses/bsd-license</sa:url>
  </sa:text>
</sa:license>
        

Name of the license, whether the license must be accepted by a user, and either a full path to the license file in the package or a URL to the full text of the license. The file element MUST be a full path in the archive to the existing file.

<sa:configuration-script-language>php</sa:configuration-script-language>

Interpreter to be used to run configuration script. Valid interpreters are described in the specification aspects.

Two update modes are supported:

Package may document which versions it can update by either specifying minimal updatable version, or enumerating all the supported updatable versions.

<sa:upgradable-from version="1.0" release="1"/>
<sa:patchable-from version="2.0" release="1"/>

Minimal version of the package from which the current package can update. Such specification means that:

<sa:upgrades version="1.0" release="1"/>
<sa:upgrades version="2.0" release="0"/>
<sa:patches version="2.0" release="1"/>
<sa:patches version="2.0" release="2"/>

Exact versions of package which may be updated by package. Multiple specification allowed.

<sa:upgradable-from version="1.0" release="1"/>
<sa:patches version="2.0" release="1"/>
<sa:patches version="2.0" release="2"/>

Combinations of minimal and exact updatable versions specifications for different update modes are allowed.

If updating specification is absent, it is supposed that updates are not supported by the package at all.

<sa:changelog>
  <sa:version version="2.1.22" release="1">
    <sa:entry>New upstream version</sa:entry>
    <sa:entry xml:lang="ru-RU">...</sa:entry>
  </sa:version>
  <sa:version version="2.1.21" release="5">
    ...
  </sa:version>
  ...
</sa:changelog>

Changelog contains the human-readable list of changes between consecutive package versions. Order of entries in changelog is not specified, Controller should sort them.

<sa:entry-points>
  <sa:entry>
    <sa:path>/admin</sa:path>
    <sa:label>Administrative interface</sa:label>
  </sa:entry>
  <sa:entry>
    <sa:path>/guest</sa:path>
    <sa:label>Guest view</sa:label>
    <sa:label xml:lang="ru-RU">Вид сбоку</sa:label>
    <sa:description>View the gallery as user not logged in</sa:description>
  </sa:entry>
</sa:entry-points>

If a web application contains entry points except the main one (base URL of web application), the packager may declare it using the entry points extension.

When a Controller installs a application with entry points to a site, it MAY provide user with the choice what entry points to show in control panel interface and where. Installed entry points MUST point to the base URL of application + path of entry point.

A Controller SHOULD use provided label and description. A Controller should use the icon of application, if it needs an icon to show entry point in user interface.

<sa:categories>
  <sa:category>blog</sa:category>
  <sa:category>cms</sa:category>
</sa:categories>

Package may include a set of categories. Category is just a Unicode string without attached semantics. The first category should be ''primary category'' in the sense the first category should be adequate for sorting packages in the user interface.

Several categories are defined in this specification and recommended to use. However, this list of categories is not normative, and any other categories may be used.

<sa:languages>
  <sa:language>en</sa:language>
  <sa:language>de</sa:language>
  <sa:language>ru</sa:language>
</sa:languages>

Package may declare a set of languages for the presentation purposes. The first language is the ''default language'' of the application. Languages are identifiers from ISO 639.

<sa:installed-size>5242880</sa:installed-size>

Package may include a declaration of approximate size of a single application instance, to help Controllers estimate the disk space resources needed to create instance. The declared size is in bytes.

Applications often need additional parameters for successful installation and configuration. While most of the questions asked during conventional web application installation are related to various resources and answers may be provided by a Controller without user intervention, some settings need to be entered by user.

Settings are declared in the settings element in basic metadata. Settings may be grouped by the group element. Each group has a name declared by the name element and a list of settings. Groups may not nest.

Each setting element represents the single setting to be asked from user.

Settings may be regular/installation-only, and local/global (hence, four types of settings: regular local, regular global, installation-only local and installation-only global).

Regular settings are settings which need to be set up during installation and may be reconfigured later. This usually includes settings which are stored in configuration files. This type is by default.

Installation-only settings need to be set up during installation, but should not be reconfigured later. This includes all settings which may be configured from the application, as any reconfiguration in the control panel will effectively reset user customizations done in application. Such settings are marked with the installation-only="true" attribute.

Local settings are set during application instantiation. This type is by default.

Global settings affect all instances of application and SHOULD be set prior to application instantiation. Such settings are marked with the global="true" attribute.

When global regular setting is changed, all instances of respective package need to be reconfigured immediately.

When application is updated, transformations of settings with the same id from 'installation-only' to 'regular' and from 'local' to 'global' classes are prohibited to protect application instance's settings values.

For patching, it is also prohibited to introduce new 'installation-only' settings without default values, as this prevents from unattended patch installation.

To make user interface more convenient, the following information is supplied for each setting:

Settings and groups are listed in the order suggested to be used in interface.

Controller MUST keep state of application settings values to pass them to the configuration/update scripts.

<sa:requirements>
  <php:version min="5.0.2"/>
  <sa:choice>
    <sa:requirements id="mysql">
      <php:extension>mysql</php:extension>
      <db:db>
        <db:id>main</db:id>
        <db:default-name>wiki</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>4.0</db:server-min-version>
      </db:db>
    </sa:requirements>
    <sa:requirements id="postgresql">
     <php:extension>postgresql</php:extension>
     <db:db>
       <db:id>main</db:id>
       <db:default-name>wiki</db:default-name>
       <db:can-use-tables-prefix>false</db:can-use-tables-prefix>
       <db:server-type>postgresql</db:server-type>
       <db:server-min-version>7.4</db:server-min-version>
     </db:db>
    </sa:requirements>
  </sa:choice>
</sa:requirements>

Requirements belong to the ''requirement types''. Requirement types are defined in aspects. Each requirement type has an associated unique XML QName (element name + namespace) and an element schema (preferably in RELAX NG). Every requirement is described as XML element valid according to the schema.

Every requirement type has associated rules (in natural language) of how to satisfy the requirement during the installation as the part of the requirement type definition in aspect.

Requirements are placed to the requirements element in the APP-META.xml file.

Individual requirements form a complex requirement which needs to be satisfied by Controller. This is performed by logical 'AND' of requirements (when they are just placed in the requirements section side-by-side), and logical 'OR' of requirements, when they are placed in the choice sub-element inside the requirements element.

Only one level of choices is allowed to simplify building the GUI.

Controller has to ensure the logical truth of a complex requirement (this means not all individual requirements need to be satisfied).

For each choice element, the CHOICE_<id> environment variable must be passed, with the value of the id attribute of the selected requirements element.

No changes in application instance resources are allowed for patches. Therefore, Controller MUST preserve all resources allocated for previous version of instance and may not even try to satisfy requirements of new version.

Every resource allocated for application instance as a result of satisfying requirements MUST be preserved during upgrade. Exact semantics of preservation is left to the requirement specification.

<sa:mapping url="/" path="htdocs"
        xmlns:sa="http://apstandard.com/ns/1"
        xmlns:php="http://apstandard.com/ns/1/php"
        xmlns:mod-python="http://apstandard.com/ns/1/mod-python">
  <php:handler>
    <php:extension>php</php:extension>
    <php:extension>pinc</php:extension>
  </php:handler>

  <sa:mapping url="upload">
    <php:handler><php:disabled/></php:handler> <!-- Disabling PHP -->
    <php:permissions writable="true"/>
  </sa:mapping>
  <sa:mapping url="stat" virtual="virtual">
    <php:handler><php:disabled/></php:handler>
    <mod-python:handler>com.example.StatHandler</mod-python:handler>
  </sa:mapping>
</sa:mapping>

The example mapping describes three contexts: URLs starting from the /, URLs starting from the /upload and URLs starting from the /stat. The two first are mapped to the file system, the third one is virtual (the mod_python aspect is not defined in this specification, so this is placed here just for illustrative purposes).

Mappings may be nested, and there MUST NOT be two mappings with such URLs that the first URL is the prefix of the second URL. In other words, the construction

<sa:mapping url="/" xmlns:sa="http://apstandard.com/ns/1">
  <sa:mapping url="foo/bar"/>
  <sa:mapping url="foo/bar/baz"/>
</sa:mapping>

is prohibited, and MUST be rewritten as

<sa:mapping url="/" xmlns:sa="http://apstandard.com/ns/1">
  <sa:mapping url="foo/bar">
    <sa:mapping url="baz"/>
  </sa:mapping>
</sa:mapping>

All urls in mappings are relative to the parent URL mapping. Absolute URLs are PROHIBITED in the url attributes, except the root mapping, where url MUST be '/'.

The path attribute of mapping is always path from the root of archive to the directory inside the archive, it must not have the / character at the start.

If mapping has an explicit path attribute, then the mapping is associated with the directory specified by this attribute. The association means that any URL which is in the scope of the given mapping (URLs in scopes of inner mappings are not in scope of outer mapping) and is not handled by the handlers declared in the mapping, needs to be served as the file from the directory specified.

If a mapping does not have an explicit path attribute nor the virtual attribute, then the directory associated with the given mapping is calculated from the directory associated with the parent mapping appending the relative URL that the given mapping has. E.g., for the following declarations

<sa:mapping url="/" path="htdocs" xmlns:sa="http://apstandard.com/ns/1">
  <sa:mapping url="foo/bar">
    <sa:mapping url="baz"/>
    <sa:mapping url="quux" path="somedir"/>
  </sa:mapping>
</sa:mapping>

mapping '/' is associated with the htdocs/ directory, mapping '/foo/bar' is associated with the htdocs/foo/bar directory, mapping '/foo/bar/baz' is associated with the htdocs/foo/bar/baz directory, and mapping 'htdocs/foo/bar/quux' is associated with the somedir directory.

If mapping has an explicit virtual attribute, then the mapping is not associated with any directory, and requests to the URLs in the scope of this mapping must return 'Not found' error, if not handled by handlers declared in the given mapping.

If an outer mapping does not have an associated directory, then the inner mappings without explicit path element do not have associated directory too.

If the whole application mapping is not virtual (there is at least one mapping without the virtual attribute), the root mapping //sa:application/sa:mapping MUST have the path attribute.

Controller MUST use mapping information for deployment and upgrade of application's instance files.

Aspects declare types of URL handlers, rules of how to process them. Rules regulating propagation of specific URL handlers to inner mappings are also declared in aspects.

The handler defined latter overrides the former. In the following example all *.php files will be processed by CGI handler.

<sa:mapping url="users">
  <php:handler>
    <php:extension>php</php:extension>
  </php:handler>
  <cgi:handler>
    <cgi:extension h:handler-type="php">php</cgi:extension>
  </cgi:handler>
</sa:mapping>

No changes in mapping structure are allowed for patches. Controller MUST leave mapping as it was for previous version of application. File overwriting semantics is determined in Upgrade.

During upgrade application files will be overwritten. Any scheme of files overwriting during upgrade is permitted, given that it satisfies the following statements:

Thus, files expected to be modified during application work need to be created manually by the configuration scripts on application installation.

For each mapping, except those which do not map to file system, the WEB_<id>_DIR environment variable must be passed with the absolute path to the directory to which the mapping maps, where id is the full URL path of the mapping, with all '/' characters converted to '_'.

Configuration script is invoked when package is installed, configured, patched, upgraded or uninstalled.

install

upgrade <old version> <old release>

configure

remove

All information about application, resources and settings is passed to configuration script through environment variables.

If environment variables in operating system contain bytes (opposed to Unicode codepoints), then UTF-8 is used as the encoding. All the IDN DNS names passed through environment MUST be passed in Unicode, not in Punycode encoding (in xn--blahblah form).

Several predefined environment variables are always passed to script, and any aspect may declare additional environment variables.

BASE_URL_SCHEME=http
BASE_URL_HOST=example.com
BASE_URL_PORT not defined
BASE_URL_PATH=phpBB/

PHP aspect declares the following requirement types: PHP version requirement type, PHP extension requirement type, PHP function requirement type, and a set of PHP settings requirement types.

<php:version min="4.1" max-not-including="5.0"/>

<php:extension>curl</php:extension>
<php:extension>Zend Optimizer</php:extension>
<php:extension>ionCube Loader</php:extension>

<php:function>system</php:function>

<php:allow-url-fopen>true</php:allow-url-fopen>

<php:memory-limit>16777216</php:memory-limit>

RELAX NG schema of PHP URL handler type

Here is an example of PHP URL handlers:

<php:handler>
  <php:extension>php</php:extension>
  <php:extension>pinc</php:extension>
</php:handler>

<php:handler><php:disabled/></php:handler>

Handlers of this type require that files with the specified extensions (if no extensions are specified, the single php extension is assumed) are handled by the PHP interpreter.

Inner mappings inherit handlers from the outer mappings, so the presence of php:disabled disables PHP in the given mapping.

RELAX NG schema of PHP permissions handler type

Here is an example of PHP permission handlers:

<php:permissions writable="true">

<php:permissions readable="false">

The situation that a directory and files in the directory to which the given mapping maps should be writable by PHP interpreter is specified by using the writable attribute with the "true" value. The "false" value is by default, so no explicit attribute for this is required.

The situation that files in the directory should be protected from reading by PHP interpreter is specified by the readable attribute with the "false" value. The "true" value is by default, so no explicit attribute for this is required.

This aspect defines the php identifier for use by configuration scripts. When a configuration script uses the php language, it MUST be run by stand-alone PHP interpreter. All the requirements described in the application metadata apply to the interpreter running configuration scripts.

This aspect declares a single requirement type: ASP.NET version requirement.

RELAX NG schema of ASP.NET version requirement type

Requirement of this type is satisfied when the application is installed in virtual directory with the specified version of ASP.NET enabled.

RELAX NG schema of ASP.NET URL handler type

Here is an example of ASP.NET URL handler:

<aspnet:handler/>

<aspnet:handler><aspnet:disabled/></aspnet:handler>

Handler of this type requires that files with the specified extensions (if no extensions are specified, the default set of ASP.NET extensions is assumed) are handled by ASP.NET.

Inner mappings inherit handlers from the outer mappings, so the presence of aspnet:disabled disables ASP.NET in the given mapping.

RELAX NG schema of ASP.NET file permissions handler type

Here is an example of ASP.NET permission handler:

<aspnet:permissions writable="true">

The situation that files in the directory to which the given mapping maps should be writable by the ASP.NET interpreter is specified by using the writable attribute with the "true" value. The "false" value is by default, so no explicit attribute for this is required.

This aspect defines jscript and vbscript identifiers for use by configuration scripts (written in JScript and VBscript correspondingly).

This aspect declares two requirement types: Apache module requirement type and Apache .htaccess requirement type. Those requirements should be used only if a web application works exclusively with Apache due to some Apache-specific features.

RELAX NG schema of CGI URL handler type

Here are examples of CGI URL handler:

<cgi:handler>
  <cgi:extension h:handler-type="perl">pl</cgi:extension>
  <cgi:extension h:handler-type="perl">cgi</cgi:extension>
</cgi:handler>

<cgi:handler>
  <cgi:all-files/>
</cgi:handler>

A handler of this type requires that files with the specified extensions (if no extensions are specified, the single cgi extension is assumed) are handled by running them as CGI scripts. If the all-files option is declared, then all files under the current mapping are to be handled as CGI scripts.

Inner mappings inherit handlers from the outer mappings, so the presence of cgi:disabled disables handling of CGI in the given mapping.

Some web servers need additional information about programs to run CGIs. This information is optionally supplied in the h:handler attribute. Possible values of this attribute consist of several predefined strings, each denoting CGI handler of particular type, namely:

Web servers which do not need an additional information about CGI handlers should ignore the h:handler attributes.