Application Packaging SDK

An Installatron application package is comprised of several files and directories, placed in the Installatron's "installers" directory:

/var/installatron/installers/installerid/
init.xml // information about the installer and the application
locale_en.php // the default (english) locale file
button.png // a 88x31 button image for the app
logo.png // up to 400x150 logo image for the app
icon.png // 175x175 icon image for the app
icon64.png // 64x64 icon image for the app (resized icon.png)
ss1.png // 1024x640 screenshot of the app
ss2.png // 1024x640 screenshot of the appversion1/ // a version sub-directory
LICENSE // license agreement for this version (optional)
init.xml // information for this version
install.php // install code for this versionversion2/ // another version sub-directory (optional)
LICENSE
init.xml
install.php
upgrade.php // upgrade code for upgrading to this version (optional)

Creating an application package

The easiest way to create an Installatron application package is to use the Installer Maker/Editor tool. This tool creates a basic template and has a GUI for editing most of the commonly used features.

See the Refrence: Variables, Commands, and How-Tos section for a closer look at the things you can use in application package installer and upgrader code, the Using an Installer section for information on adding the application package to your server, or read blow for a closer look at each file and directory in an Installatron application package:

installerid/

The installer id is lowercase alphanumeric key that must be unique to the installer. Usually these are named after the application being installed, so for example the id for the phpBB installer is phpbb.

build_number is the current build number of the installer. Increment this number whenever the installer is edited.

_installer_installerid_* are references to locale entries. You can use plain text here if you don't want to use the locale file.

url_to_* are all optional, though users do like to see at least a website link for the application.

version1, version2, etc are the versions (eg. "2.1.0p1", "2.1.1", etc), with the newest version at the top. If upgrading is not supported then there will be a single version in this area.

upgrade types, in the versions section, can be: none (cannot upgrade to this version), manual (can only upgrade manually to this version), auto (auto-upgrading is supported by the installer), or skip (auto-upgrading is supported by the installer, and this version can be skipped over if upgrading to a later version).

install types, in the versions section, can be: none (cannot install this version), auto (auto-installing is supported by the installer).

installerid/ss1.jpg

installerid/ss2.jpg

installerid/ssN.jpg

installerid/version/

There is one version/ directory for each version of the application that is supported by the package. If the package installs a single version, or does not support upgrading, then there will be a single version directory. The version should have no spaces, and should only use characters that can be used in a directory name.

<information>

license_type can be any text, or a reference to the application's locale file, or the global locale keys: _apps_free or _apps_opensource

default_directory_name is an optional default install directory name. If not present, the default directory when installing the application will be the installerid.

<links>

All links are optional, and all are relative to the install directory. admin adds an [admin] button to the Installed Apps page and is a link to an "administration" page. config is the same except it is for a [config] button. edit-1, edit-2, etc are files that can be edited inside Installatron (for templates or config files that can't be edited through the application itself).

<requirements>

requirements are all optional. Leave empty if the application doesn't have a specific requirement.

<archives>

archives are used to register archives for this version of the application. The "main" archive is required and "xtra1", "xtra2", etc are optional. The archive_type can be either: zip or tar.gz

md5_value is an optional md5 value for the archives, which is used by Installatron to check that the archive downloaded correctly. Editor automatically adds an md5 value when saving from the Version Info tab, if no md5 value is already present.

<skeleton>

skeleton contains a list of directories, files, and database tables included with the application. Database tables should be listed without a table prefix. Boolean flags are available, including isconfig, which informs Installatron which files contain the application's MySQL and other configuration values (needed when importing installed applications). This list also informs Installatron what should be removed when an application is uninstalled.

<fields>

fields gather information and interface directly with the installed application. Fields can be uni-directional or bi-directional.

These common fields are built-in:

version: This field should return the installed version of the application. Always unidirectional (no setter).

language: This fields gets and sets the installed application's default user-interface language. The <languages> section (see below) provides a way to relate the application's language identifiers with Installatron's language identifiers.

In <get>, <set>, and <verify>, the PHP variable $this->input["field_fieldname"] always represents the input value of the field. As a special case for the language field, the PHP variable $this->input["field_language_value"] represents the application's language identifier for the selected language, as defined in the <languages> section (see below).

Custom fields can also be defined. Here's an example that uses many available options.

installerid/version/upgrade.php

The upgrade.php file upgrades an install to this version of the application from the previous version.

The upgrade file uses the same format as install.php (see above), with any number of steps and each step has an _init (for setting up the page for that step) and _process (for doing stuff). Unlike install.php, step 1 is not reserved for settings, and it's more common to have just one or two steps.

(Option 1) Use Installatron's addon-installer system.

An addon-installer is comprised of two files: the first is a tar.gz archive containing the application package (this is created by the editor). The second file is a controller file which looks like this:

installerid is the unique id of the installer.build_number is the current build number of the installer. Increment this number whenever the installer is edited.url_to_installer is a URL to the application package archive. The archive must be a gzip-compressed tar archive, and must be created using our Application Package Editor tool.

Example

Let's create an example application package with the id joomla.

When we're ready to test it we go to the Publisher tab and click the Publish button.

That will create an archive named joomla.tar.gz, which we download to our PC and then upload to a public web location somewhere. Let's upload it to http://my_domain/my_installers/joomla.tar.gz for this example.

Then we create this catalog file (or edit the one provided by Publisher) named joomla.xml:

That will add the joomla application package to Installatron. Installatron will check the joomla.xml file each time an update/repair is run to see if the build number has changed. If it has changed, it will download the installer again.

More information is provided on the Publisher page in the editor.

(Option 2) Use WGET to download the application package directly from the editor to your server.

The wget shell command can be used to transfer application packages directly to the /var/installatron/installers directory. Details are provided on the Publisher tab in the editor.

This option is only available for PHP5 because PHP4 uses a different application package format, which must be created using the Publisher tool in the editor.

This approach is also good for quick development, but should only be used during development. Once an application package is finished, you should use method 1 above.

(Option 3) Manually add the application package to your server.

It's also possible to manually upload/make the files and directories directly in the /var/installatron/installers directory.

This option is only available for PHP5 because PHP4 uses a different installer format, which must be created using the Publisher tool in the editor.

If you are good with vim then this might be a quick way to edit and test your application package.

Refrence: Variables, Commands, and How-Tos

This section lists the variables and commands that can be used in application package installer and upgrader code, and some how-to explanations. See the Overview section for a closer look at the packaging format.

SQL Query

Execute a MySQL statement. This requires that the "database" requirement is enabled.

If an array of binded_variables are included, each will replace a corresponding question mark placeholder in the SQL statement. If select_this is included, this method will return the corresponding result value.

Var Export

Language Identifier Refrence

This table lists Installatron's Language Identifier for most languages that are in use today (used for the XML <languages> tag). If support is required for a language that is not listed, please contact us.

Troubleshooting

If your application package isn't displaying or installing, the first place to check is the Installatron logs. These can be viewed from Administration, or if you need to see more than just the last few lines you can find them here:

/var/installatron/logs

The filesystem_log is usually the most useful as it logs the result of every $this-> command. The fetch_log logs the result of every call to a URL, so that includes all control panel API calls, all downloads, and all $this->fetch() commands.

Browse below for some of the more common application package problems and their fixes.

archive 'main' not found

CAUSE

Installatron failed to download the 'main' archive.

The causes are usually either a) the archive is not at a publically accessible location, or b) the MD5 checksum is wrong.

DOWNLOAD LOCATION SOLUTION

Make sure that the URL to the archive can be downloaded with a wget command from the server. If wget can get the file then Installatron can too.

INCORRECT MD5 CHECKSUM SOLUTION

The MD5 checksum, used to verify that the archive has downloaded correctly, is not shown in the Editor GUI at this time so to fix it you need to:

Go to the Source Editor tab and scroll down to the version info textarea (it contains the archive info).

Delete the md5= value. If you know the correct md5 value you can add it here. Then save.

If you didn't know the correct md5 value, go to the Version Info tab and then save. This will download the archive and find the md5 value.

my application package isn't listed

CAUSE

If the application package is listed in Administration > Access Groups > Edit but is not showing in the Application Browser then the cause is usually requirement filtering.

SOLUTION

Check the requirements you have configured for the script (Editor > Version Info > Requirements) and compare them with the Administration > Applications > Dependencies configuration in Installatron.