Site Applications Package Format Specification

A package is a ZIP file [ZIP] file with the .app.zip extension.

Package MUST contain only regular files and directories.

There MUST NOT be two files or directories in one directory whose filenames differ only in case.

Names of the files included in a package SHOULD contain only printable ASCII characters (except for the TAB, NL, and CR characters (ASCII codes 32-127)). To ensure web application compatibility with Microsoft Windows, names of the files included in a package SHOULD NOT contain the following characters: <, >, :, ", /, \, |, *, ?.

Special Windows device names (con, con.*, nul, nul.*, lpt etc) MUST NOT be used in packages. It is recommended to check for such files during package unpacking on Windows.

Each package MUST contain a well-formed XML file named APP-META.xml in the Package's root directory. This file contains whole metadata of the package. Aspects declare additional XML elements to be added after basic metadata.

The basic metadata uses the XML namespace http://swsoft.com/schemas/siteapps/1. Future incompatible versions of metadata will use a different namespace.

RELAX NG schema of basic metadata

The following items are described in the basic metadata:

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

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

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

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

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

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

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

<sa:icon><sa:file>images/phpbb.png</sa:file></sa:icon>

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

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

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

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

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

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

<sa:after-installation-url>/tutorial/</sa:after-installation-url>

Package may include the web application configuration script. This script will be invoked during adding application to a site, updating application, changing settings of application and removing application from the site.

Configuration script must be named configure and reside in the scripts directory of the Package root directory.

The script file and script language declaration in metadata must be either both included in the package or both omitted from the package.

Configuration script may be written in any programming language specified in Basic metadata section.

Any aspect may declare language to be available for executing configuration script. Such aspect must declare name of language to be used to identify language in basic metadata (as there is no established registry of programming language names, it is recommended to use lowercased name from Wikipedia list of programming languages [Langs]) and rules of executing configuration script.

Configuration script must be run on the host application is being installed to, with the permissions of user which ows this application instance, so only unprivileged actions may be performed in the configuration script.

During execution, the working directory of the configuration script must be set to the actual location of the script. All contents of scripts directory must also reside in the script's current working directory.

If package does not contain configuration script, Controller should skip all configuration script invocations.

If any script invocation fails (script returns non-zero exit code), it must be treated as fatal error and Controller must refuse to continue operation. Stdout and stderr of the script should be captured to log error in this case.

It is recommended to capture and log stdout and stderr of all configuration scripts runs for papertrail purposes.

add

upgrade [old version] [old release]

configure

remove

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

RELAX NG schema of PHP aspect metadata

<p:min-version>4.0</p:min-version>

If web application works only on PHP since particular version, min-version element with desired minimal PHP version must be specified in metadata.

<p:reqired-extension>fcntl</p:reqired-extension>

If web application needs some PHP extensions to operate, names of each such extension must be specified in required-extension element in metadata. Name of extension is specified in zend_module_entry structure of extension code and may be obtained by the get_loaded_extensions PHP function.

<p:file-uploads>true</p:file-uploads>

If web application needs one of allow_url_fopen, file_uploads, safe_mode, short_open_tag, register_globals, magic_quotes_gpc settings to be true or false, apropriate element with must be added to metadata. If web application does not care about value of setting, corresponding element must not be included in metadata.

<p:memory-limit>16m</p:memory-limit>

If web application needs particular value of max_execution_time, memory_limit or post_max_size settings, apropriate elements with minimal acceptable values of settings must be added to metadata. If web application does not care about those settings, corresponding elements must not be included in metadata. Values are in format understood by PHP (integer or integer with k/m/b suffix for kilobytes, megabytes and gigabytes).

<p:required-function>system</p:required-function>

If web application needs specific PHP functions known to be frequently disabled (such as system function), each such function name must be declared in required-function element in metadata.

<p:code-dir>lib/php-ws-federation</p:code-dir>

If web application needs additional PHP code to be available in include_path, but not in document root, directory of such code should be placed somewhere in the Package, and code-dir element must contain full path path to the directory with code inside archive. There may be many such directories.

When Controller adds site application with PHP aspect to the site, Controller must ensure the number of things mentioned below, and refuse to install package if some of the requirements can't be fulfilled.

PHP must be enabled on site application installs to.

If min-version element exists in metadata, PHP version on site must be same or greater than min-version.

For each required-extension element, corresponding PHP extension must be available on the site.

For each allow-url-fopen, file-uploads, safe-mode, short-open-tag element present in metadata, corresponding PHP setting must have matching value on the site. For each execution-time-limit, memory-limit and post-size-limit element in metadata, corresponding PHP setting (max_execution_time, memory_limit, post_max_size) must have same or bigger value on the site. For each required-function element in metadata, corresponding function must be not in disabled_functions setting.

For each code-dir element in metadata, code from the mentioned directory must be made available to the application in include_path. This code is potentially shareable between application instances.

The PHP_VERSION environment variable must be passed on to the configuration script with the version of PHP (as a string value) installed on the Web site where the Package is to be installed.

This extension defines php language for use by configuration scripts. When configuration script uses php language, it should be run by standalone PHP interpreter. All the requirements described in the site application metadata in PHP section apply to the interpreter running configuration scripts.

RELAX NG schema of DB aspect metadata

<d:db
  <d:id>main</d:id>
  <d:default-name>phpbb</d:default-name>
  <d:db-server min-version="4.0" tables-prefix="true">mysql</d:db-server>
  <d:db-server min-version="7.4">postgresql</d:db-server>
</d:db>

If web application requires database(s) to work, for each database single db element must be added to metadata with the following content:

default-name element declares proposed name of database to be provided to the application. It is not guaranteed that actual database will be of the proposed name.

One or more db-server elements declare acceptable types of database servers. Each such element declares name of DB server and (optionally) minimal version of DB server web application can work with. Database servers should be sorted from the most preferable one on the top of list to the least preferable on the bottom of list. tables-prefix attribute declares that application instance can share database by using prefixed tables.

id element declares identifier of database. This identifier will be used in environment variables passed to configuration scripts.

When Controller adds site application with DB aspect to the site, Controller must ensure the following things and refuse to install package if some of the requirements can't be fulfilled.

For each db element database one of the types mentioned in db-server must be allocated to the user installing application. Minimal version of DB server in min-version attribute restriction must be taken into account. If tables-prefix attribute is present, Controller may chose to reuse existing database by giving unique prefix to the application. In this case Controller must ensure that tables of different applications do not overlap.

Controllers may use any policy to allocate database, from automatic provisioning to providing connection manually by the user.

For each database, the following environment variables must be passed on to configuration script:

Environment variables DB_<identifier>_HOST and DB_<identifier>_PORT must not be specified if application is to use the local transport (UNIX sockets or named pipes) to connect to the database.

This variable is defined only if application shares database with another ones. In this case application must create tables with provided prefix, and must not touch tables without this prefix. Applications which declared support of shared database in metadata must correctly handle situation when whole database is issued to the instance.

db-server element describes name of database server. Currently defined names are:

Another names should be taken from the JDBC drivers registry [JDBCDRIVERS]. Official database server driver should be used if more than one driver available. JDBC driver name (and subname if name specifies company, as with 'microsoft:sqlserver') is used.

RELAX NG schema of Apache aspect metadata

This aspect should be used only if web application works exclusively with Apache due to some Apache-specific features.

For each Apache module required for application, required-module element with name of module must be declared in metadata.

When Controller adds site application with Apache aspect to the site, Controller must ensure the following:

RELAX NG schema of Web content metadata

[TODO: this aspect need to be extended to cover more generic URL-mapping]

This aspect should be used if web application has files in document root (e.g. it is not purely mod_python based application whith keeps all the configuration in database).

Web applications typically keep different kinds of data on disk: static media, uploaded files, PHP code, CGIs etc. Those kinds differ in the possibility of sharing data between applications: uploaded files are per-instance, while PHP code may be used by the several instances of the application.

Each identified kind of data should be placed in the separate directory in package, and separate content element must be added to metadata, describing:

When Controller adds site application with Web content aspect to the site, Controller must ensure the following:

<s:web xmlns:s="http://swsoft.com/schemas/siteapps/1">
  <s:content shared="true" rel-url="/images" web-server-writable="false">
    <s:dir>code/images</s:dir>
  </s:content>
  <s:content shared="true" rel-url="/" web-server-writable="false">
    <s:dir>code/src</s:dir>
  </s:content>
  <s:content shared="false" rel-url="/upload" web-server-writable="true">
    <s:dir>code/upload</s:dir>
  </s:content>
</s:web>
</code>

Package contents:

META-APP.xml
 code/
   images/
     arrow.png
   src/
     about.php
   upload/
      

If application is installed to the http://example.com/myapp/, then arrow.png will be available at http://example.com/myapp/images/arrow.png and about.php will be available at http://example.com/myapp/about.php.

Controller may use single instance of arrow.png and about.php for the several instances of application, but upload directory must never be shared.

WEB_MODE environment variable must be passed to the configuration script with one of two possible string values: shared or instance, reflecting mode of application installation.

For each content part WEB_<id>_DIR must be passed with the absolute path to the directory where content is installed.

For each content part WEB_<id>_MODE must be passed with the one of two possible string values: shared or instance, reflecting the mode of the content part installation. Obviously, when application is installed in non-shared mode, all such variables will contain instance value.

id of each content part is the text content of dir element.

XML element described in the following schema must be added to metadata to declare use of Entry Points aspect.

RELAX NG schema of entry points aspect metadata

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

For each such entry point, entry element should be added with the following content:

When Controller adds to the site site application with Entry Points aspect, 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 site application + URL of entry point.

Controller should provide base URL of installed application as main entry point.

Controller should use provided label and description. Controller should use icon of site application, if it needs icon to show entry point in interface.

<entry-points xmlns="http://swsoft.com/schemas/siteapps/1">
  <entry>
    <url>/admin</url>
    <label>Administrative interface</label>
  </entry>
  <entry>
    <url>/guest</url>
    <label>Guest view</label>
    <label xml:lang="ru-RU">Вид сбоку</label>
    <description>View the gallery as user not logged in</description>
    <description xml:lang="ru-RU">Галерея, как видна случаному посетителю</description>
  </entry>
</entry-points>