Installatron Server API and Setup Guide

API Specification, version 1.7 (2012-02-20)

2. Self-hosting Installatron Server
2.1. Prerequisites
2.2. Download and Install
2.3. Create a web server virtual host
2.4. Complete

3. Interfacing with Installatron Server
3.1. Request Header
3.2. List available applications and application information
3.3. Installing an application
3.4. Import an existing installed application
3.5. List installed applications
3.6. List installed application backups
3.7. View/sync an installed application
3.8. Edit an installed application
3.9. Backup an installed application
3.10. Upgrade an installed application
3.11. Restore an installed application backup
3.12. Uninstall an installed application
3.13. List currently executing and recently completed tasks
3.14. Transferring a user into the Installatron Server GUI
3.14.3. Logging in as the GUI administrative user
3.14.4. Database management within the GUI
3.14.5. Hiding database inputs within the GUI

1. Introduction

Please refrence the "What is Installatron Server?" page for an overview of what Installatron Server is: What is Installatron Server?

As outlined, there are two hosting options for Installatron Server:

Self-hosted
Hosted as a service

And three integration interfaces for Installatron Server:

HTTP API
Command-line API
Installatron Server GUI

In this document each Installatron Server integration interface will be explained in detail. The interfaces do not differ between self-hosted and hosted as a service instances.

2. Self-hosting Installatron Server

Follow these instructions to install an instance of Installatron Server on a local server.

2.1. Prerequisites

At least one server with a permanent internet connection is required for licensing and updating purposes.

This can be the same server an existing web hosting control panel is installed on, or this can be a dedicated server just for Installatron Server.

2.2. Download and Install

For servers that support the RPM packaging standard, execute this command from the SSH root command prompt:

rpm -Uvh http://data1.installatron.com/installatron-server-2.1.2-1.noarch.rpm

For FreeBSD and other UNIX servers that don't support RPM, execute these commands from the SSH root command prompt:

mkdir -p /var/installatron/custompanel
wget http://data1.installatron.com/installatron/installatron_setup.sh
chmod +x installatron_setup.sh
./installatron_setup.sh -f

For Windows, simply execute the installatron_setup.exe executable as an administrative user.

Core files and programs will be installed here:

/usr/local/installatron/

And the data files will be installed here:

/var/installatron/

For Windows these paths translate roughly to \Program Files\Installatron and \Program Files\Installatron\Data, respectively.

Note: These paths can be moved to different locations using a more advanced installation method. Please contact Installatron Support for more information.

2.3. Create a web server virtual host

A web server virtual host is only required if the GUI or HTTP API will be used. Skip this step if only the Command-line API will be used.

When creating the virtual host, link any URL to the specified directory.

http://myhost.com/installatron/ -> /usr/local/installatron/frontend/

Note that it's possible to use a different URL mapping. If this is done, the /usr/local/installatron/etc/http.php file must be updated to reflect the URL mapping used.

2.4. Complete

That's it! Continue to the section 3 Interfacing with Installatron Server below.

3. Interfacing with Installatron Server

Three different interfaces are provided for interfacing existing infrastructure with Installatron Server.

HTTP API
Command-line API
Installatron Server GUI

Input to both API interfaces can be formatted in JSON or simple URL encoded values.

3.1. Request Header

The request header informs Installatron Server about a user. Every request to Installatron Server must include a header, including requests to transfer a user into the Installatron Server GUI.

3.1.1. List of header arguments

name value
key The API authentication key. This is provided by Installatron when hosted as a service. Check the "key" value in /usr/local/installatron/etc/settings.ini for self-hosted instances.
websites List of websites for the current session. Each website can only have one home directory. Websites spread across multiple home directories are supported but will need separate entries.

3.1.1.1. List of header website arguments

name value
id A value that will uniquely identify this website containing only alphanumeric characters. This value will be used to index data for this website and cannot change.
email The user's email address (used for email notifications, if enabled)
vhosts An array containing a list of each domain hosted by this account and its corresponding directory on the filesystem relative to path (see example below)
path The server's path to the home directory of this account, without a trailing directory separator. This value can be formatted as a FTP URI if Installatron Server is hosted on a centralized server and files are to be transferred over the FTP layer.
For example: /home/user or ftp://user:pass@remotehost
path_backups
(optional)
A path relative to path where installed application backups will be saved, without a trailing directory separator. The default location is "{path}/installatron_backups/".
uid
(optional)
the POSIX UID for this website that should be used to CHOWN files and execute binaries like mysqldump. Only define this when path_remote is NOT defined.
gid
(optional)
the POSIX GID for this website that should be used to CHOWN files and execute binaries like mysqldump. Only define this when path_remote is NOT defined.
mysql_host
(optional)
The default mysql server for this website (defaults to the Mysql Host Global Administrative Setting or "localhost"). Usually omitted.

3.1.2. Sample header 1 formatted in JSON

"key": "8327b11a311aad5a8092d26d209c9e13",
"websites":
[{
	"id":"ws124",
	"path":"/var/www/vhosts/company.com",
	"vhosts":{
		"http://company.com":"httpdocs",
		"http://www.company.com":"httpdocs"
	},
	"email":"user@mail.com",
	"uid":153,
	"gid":153
}],

3.1.3. Sample header 2 formatted in JSON

"key": "8327b11a311aad5a8092d26d209c9e13",
"websites":
[{
	"id":"ws124",
	"path":"ftp://user:pass@server120.host.com/domains/company.com",
	"vhosts":{
		"http://company.com":"public_html",
		"http://www.company.com":"public_html",
		"http://forum.company.com":"public_html/forum"
	},
	"email":"user@mail.com"
}],

3.2. List available applications and application information

3.2.1. List of arguments

name value
cmd browser

Optional arguments:

name value
application The ID of the application to list available versions of. By default the latest version of each application is listed.
language The language application information should be returned in. For example, "en" for English or "zh_tw" for Chinese Traditional. If omitted, the defined website's default language or English is assumed. See: Available Installatron Translations.

3.2.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Table of application information.

3.2.3. Sample return value

{
"result":true,
"message":"",
"data":[
{
	"id":"wordpress_3.3.1",
	"version":"3.3.1",
	"branch":"current",
	"name":"WordPress",
	"category":"Content Management",
	"type":"blog",
	"date":"2012-01-03",
	"license":"open source",
	"description":"Wordpress is an open source blog system, and is the most-used self hosted blog script on the Internet. Wordpress forked from the b2/cafelog project in 2003, and WordPress Mu multi-website functionality has been integrated since 2010.",
	"authordescription":"WordPress is a state-of-the-art personal publishing platform/blogger with a focus on aesthetics, web standards, and usability.",
	"link_site":"http://wordpress.org",
	"link_docs":"http://codex.wordpress.org",
	"link_faq":"http://codex.wordpress.org/FAQ",
	"link_support":"http://wordpress.org/support",
	"link_admin":"wp-admin",
	"link_installersupport":"https://secure.installatron.com/tickets",
	"requirement_diskspace":"18",
	"requirement_database":true,
	"requirement_db_type":"mysql",
	"requirement_db_prefix_support":true,
	"requirement_db_prefix_underscore":true,
	"requirement_php_version_minimum":"5.2.4",
	"requirement_mysql_version_minimum":"5",
	"languages":["ar","de","en","es","fi","fr","he","hu","it","ko","nl","no","pl","pt","pt_br","ru","sv","zh","zh_tw"],
	"fields":{
		"language":{
			"label":"Language",
			"text":"select a language",
			"type":"select"
		},
		"login":{
			"label":"Administrator Username",
			"text":"enter a username for the administrator user",
			"type":"text",
			"default":"admin"
		},
		"passwd":{
			"label":"Administrator Password",
			"text":"enter a password for the administrator user",
			"type":"password"
		},
		"email":{
			"label":"Administrator Email",
			"text":"enter your email address",
			"type":"text"
		},
		"sitetitle":{
			"label":"Website Title",
			"text":"enter title for the website",
			"type":"text"
		}
	},
	"images":["button_wordpress.gif","icon_wordpress.gif","icon64_wordpress.gif","logo_wordpress.gif","ss1_wordpress.jpg","ss2_wordpress.gif","ss3_wordpress.gif","ss4_wordpress.gif"]
},
(additional entries for apps proceed here)
]}

3.3. Installing an application

3.3.1. List of arguments

name value
cmd install
application The ID of the application to be installed. For example, "wordpress" or "magento". See: List of applications.
db_host The database server.
db_name The pre-created database.
db_user The pre-created database username.
db_pass The pre-created database password.

Optional arguments:

name value
version The version of the application to be installed. If omitted, the latest, compatible version is assumed.
db_prefix If a database prefix other than the default prefix should be used, specify the value here.
url The URL to where the application should be installed. If omitted, the application is installed in the root directory of the first available domain.
url_ip If the DNS will not resolve the provided "url" to the correct IP, use this argument to provide the correct IP. This argument is typically omitted.
background When defined, the request will exit immediately and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

Further optional arguments that may be ignored by some applications:

name value
language The language of the application to be installed. For example, "en" for English or "zh_tw" for Chinese Traditional. If omitted, the website's default language or English is assumed. See: Installatron Language Identifiers.
login The username for the installed application's administrative account. If omitted, typically "admin" is assumed.
passwd The password for the installed application's administrative account. If omitted, a randomized password is assumed.
sitetitle The site title value for the installed application. If omitted, "My {type}" is assumed, where {type} is the type of application. For example, "My Forum".
content Should the application be installed with demo content? Valid values: "yes" or "no". If omitted, "no" is typically assumed.

3.3.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Table of installed application information.
task Table of task information if executed as a background process.

3.3.3. Examples

Command-line inteface JSON input

echo '{
	"key": "8327b11a311aad5a8092d26d209c9e13",
	"websites":
	[{
		"id":"ws124",
		"path":"/var/www/vhosts/company.com",
		"vhosts":{
			"http://company.com":"httpdocs",
			"http://www.company.com":"httpdocs"
		},
		"email":"user@mail.com",
		"uid":153,
		"gid":153
	}],
	"cmd":"install",
	"application":"wordpress",
	"url":"http://company.com/blog",
	"db_name":"db123",
	"db_user":"db123",
	"db_pass":"sdfsdf1",
	"db_host":"localhost"
}' | /usr/local/installatron/installatron

HTTP interface URL-encoded input

curl https://secure.installatron.com/server/v1 \
	-d "key=8327b11a311aad5a8092d26d209c9e13" \
	-d "websites[0][id]=ws124" \
	-d "websites[0][email]=user@mail.com" \
	-d "websites[0][path]=ftp://website124:password@12.24.36.22" \
	-d "websites[0][vhosts][http://company.com]=httpdocs" \
	-d "websites[0][vhosts][http://www.company.com]=httpdocs" \
	-d "cmd=install" \
	-d "application=wordpress" \
	-d "url=http://company.com/blog" \
	-d "db_name=db123" \
	-d "db_user=db123" \
	-d "db_pass=sdfsdf1" \
	-d "db_host=localhost"

HTTP interface JSON input


<?php
$query = array(
    /* these values define the request header: */
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "websites" => array(
        array(
            "id" => "ws124",
            "path" => "ftp://".urlencode("website124").":".urlencode("password")."@12.24.36.22",
            "vhosts" => array(
                "http://company.com" => "httpdocs",
                "http://www.company.com" => "httpdocs",
                "https://company.com" => "httpsdocs",
                "https://www.company.com" => "httpsdocs",
            ),
            "email" => "user@mail.com",
        )
    ),
    /* these values define the request body: */
    "cmd" => "install",
    "application" => "wordpress",
    "url" => "http://company.com/blog",
    "db_name" => "db123",
    "db_user" => "db123",
    "db_pass" => "sdfsdf1",
    "db_host" => "localhost",
);

$ch = curl_init("https://secure.installatron.com/server/v1");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));

$reply = curl_exec($ch);

if ( $reply === false )
{
    echo "An error occurred: ".curl_error($ch);
    return;
}

$reply = json_decode($reply,true);

if ( $reply["result"] === false )
{
    echo "An error occurred: ".$reply["message"];
    return;
}

echo "Success! ".$reply["message"];

3.4. Import an existing installed application

3.4.1. List of arguments

name value
cmd import
application The ID of the application to be installed. For example, "wordpress" or "magento". See: List of applications.

Optional arguments:

name value
version The version of the application to be imported. If omitted, the latest, compatible version is assumed.
url The URL to where the application is installed.
url_ip If the DNS will not resolve the provided "url" to the correct IP, use this argument to provide the correct IP. This argument is typically omitted.

Further optional arguments that may be ignored by some applications:

name value
db_host The server that hosts the installed application's database. If omitted, Installatron will try to autodetect.
db_name The name of the installed application's database. If omitted, Installatron will try to autodetect.
db_user The database username used to connect to the installed application's database. If omitted, Installatron will try to autodetect.
db_pass The database username password. If omitted, Installatron will try to autodetect.
db_prefix The prefix each database table begins with, including trailing underscore (if any). If omitted, Installatron will try to autodetect.

3.4.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Table of installed application information.

3.5. List installed applications

3.5.1. List of arguments

name value
cmd installs
filter-version-available When set equal to "yes", only installed applications that have new version upgrades available will be listed.

3.5.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Detailed list of matched installed applications.

3.6. List installed application backups

3.6.1. List of arguments

name value
cmd backups

3.6.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Detailed list of matched installed application backups.

3.7. View/sync an installed application

3.7.1. List of arguments

name value
cmd view
id The ID of the installed application to be synced and displayed.

3.7.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Application details, similar to the "installs" API return value.

3.8. Edit an installed application

3.8.1. List of arguments

name value
cmd edit
id The ID of the installed application to be edited.

Updates the specified installed application by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the language parameter, that becomes the install's active language.

Optional arguments:

name value
url The URL to the installed application.
path The local path to the installed application.
db_host The server that hosts the installed application's database.
db_name The name of the installed application's database.
db_user The database username used to connect to the installed application's database.
db_pass The database username password.
db_prefix The prefix each database table begins with, including trailing underscore (if any).

Additional optional arguments that some applications may not support:

name value
language The language of the installed application. For example, "en" for English or "zh_tw" for Chinese Traditional. See: Installatron Language Identifiers.
login The username of the installed application's administrative account.
passwd The password of the installed application's administrative account.
email The email of the installed application's administrative account.
sitetitle The site title value of the installed application.

3.8.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Further details regarding the success or failure.

3.9. Backup an installed application

3.9.1. List of arguments

name value
cmd backup
id The ID of the installed application to be backed up.

Optional arguments:

name value
background When defined, the request will exit immediately and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

3.9.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Further details regarding the success or failure.
task Table of task information if executed as a background process.

3.10. Upgrade an installed application

Note: It's always recommended to create a backup prior to upgrading any installed application.

3.10.1. List of arguments

name value
cmd upgrade
id The ID of the installed application to be upgraded.

Optional arguments:

name value
version The version to be upgraded to. If omitted, the latest, compatible version is assumed.
background When defined, the request will exit immediately and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

3.10.2. List of return values

3.11. Restore an installed application backup

3.11.1. List of arguments

name value
cmd restore
id The ID of the installed application backup to be restored.

Optional arguments:

name value
background When defined, the request will exit immediately and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

3.11.2. List of return values

3.12. Uninstall an installed application

3.12.1. List of arguments

name value
cmd uninstall
id The ID of the installed application to be uninstalled.

Optional arguments:

name value
background When defined, the request will exit immediately and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

3.12.2. List of return values

3.13. List currently executing and recently completed tasks

3.13.1. List of arguments

name value
cmd tasks

3.13.2. List of return values

name value
result true on success, or false on failure.
message Success or failure message.
data Table of currently executing and recently completed tasks.

3.14. Transferring a user into the Installatron Server GUI

To transfer a user into the Installatron Server GUI, a session must first be created for the user. This is done by calling the "guixfer" API.

Note: When using a FTP connection, the FTP username and FTP password are optional. When omitted, the user will be prompted for these values by the Installatron Server GUI.

3.14.1. List of arguments

name value
cmd guixfer
language The language the user interface should display in. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations.

3.14.2. Examples

This example written in PHP initializes an Installatron Sever session and then redirects to the Installatron Server GUI:


<?php
$query = array(
    /* these values define the request header: */
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "websites" => array(
        array(
            "id" => "website123",
            "path" => "ftp://".urlencode("website123")."@12.24.35.11",
            "vhosts" => array(
                "http://website.com" => "httpdocs",//@note it's assumed "path" is prefixed.
                "http://www.website.com" => "httpdocs",
            ),
            "email" => "user@mail.com"
        ),
        array(
            "id" => "website124",
            "path" => "ftp://".urlencode("website124")."@12.24.36.22",
            "vhosts" => array(
                "http://company.com" => "httpdocs",
                "http://www.company.com" => "httpdocs",
                "https://company.com" => "httpsdocs",
                "https://www.company.com" => "httpsdocs",
            ),
            "email" => "user@mail.com",
            // Because we are transferring the user into a GUI, we need some mechanism to
            //  handle databases. See section 3.14.3 for more information.
            "db_mode" => "manual",
            "databases" => array(
                array(
                    "type" => "mysql",
                    "host" => "localhost",
                    "name" => "db134",
                    "user" => "db134",
                    "pass" => "0sdhfldsafh"//Note: Providing a password is optional.
                ),
                array(
                    "type" => "mysql",
                    "host" => "localhost",
                    "name" => "db135",
                    "user" => "db135"
                )
            )
        )
    ),
    /* these values define the request body: */
    "cmd" => "guixfer",
    "language" => "en"
);

$ch = curl_init("http://yourhost.com/installatron/index.php");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$reply = curl_exec($ch);

if ( $reply === false )
{
    echo "An error occurred: ".curl_error($ch);
    return;
}
else if ( strpos($reply,"Error:") === 0 )
{
    echo "An error occurred: ".$reply;
    return;
}

$reply = json_decode($reply,true);

if ( $reply["result"] === false )
{
    echo "An error occurred: ".$reply["message"];
    return;
}

header("Location: http://yourhost.com/installatron/index.php?s=".$reply["session_id"]);

3.14.3. Logging in as the GUI administrative user

To enter into the GUI as a predefined user, such as the administrative user, define $query with a user member:


<?php
$query = array(
    /* these values define the request header: */
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "user" => "admin",
    /* these values define the request body: */
    "cmd" => "guixfer",
    "language" => "en"
);

3.14.4. Database management within the GUI

When using the Installatron Server API databases are always created prior to invoking the API. However, this model degrades when applied to the GUI, as it's often desired to limit each database to one installed application. The Installatron Server GUI can solve this problem in two different ways:

The preferred solution is to implement a PHP class that Installatron Server then uses to list, create, and delete databases. Under the default configuration, this solution creates a separate database for each installed application.
A second, more simple solution is keep the API's model of pre-creating databases. Database information can be set per website in the "guixfer" API request. However, a warning: there are some applications (SugarCRM, Tiki Wiki) that don't support table prefixes, so attempting to install these applications will cause database table collisions. We recommend disabling these applications when this solution is used. See the above example (in section 3.14.2) to reference how to implement this solution.

To use the preferred solution, implement each of the below PHP methods into the /var/installatron/custompanel/backend.php PHP file. Here's the recommend code to start with:


<?php
class i_custom extends i_panel
{

/**
 * This method enables you to format the database name Installatron Server will expect to be created.
 *
 * @param   string  Database type (typically "mysql", can also be "mssql")
 * @return  array   (Database name, database user, database password, database host, database table prefix)
 */
public function generateDB($type)
{
    //@note
    // itron::$session is a PHP array referencing the selected website. If you define 
    // "_some_prefix" when calling "guixfer", it will be available in this array, however
    // the custom variable name must begin with an underscore (_).
    $prefix = itron::$session["_some_prefix"]."_";

    // Maximum database name length, including prefix.
    $len_max = 16;
    $len_less_prefix = $len_max-strlen($prefix);

    //@note
    // This must generate a UNIQUE database name that can be passed to createDB to be created.
    // PHP's uniqid function uses the system microtime, and this is often good enough
    $db_name = $prefix.substr(uniqid(), 0, $len_less_prefix);

    $db_host = "localhost";
    $db_user = $db_name;//same as the db name
    
    $db_pass = null;//let Installatron create a randomized value.
    $db_table_prefix = null;//let Installatron manage table prefixes

    return array($db_name, $db_user, $db_pass, $db_host, $db_table_prefix);
}

/**
 * Create a database
 *
 * @param   string  New database name. This is typically set by generateDB.
 * @param   string  New database username. This is typically set by generateDB.
 * @param   string  New database username's password. This is typically set by generateDB.
 * @param   string  Database type (typically "mysql", can also be "mssql")
 * @param   string  New database's server. This is typically set by generateDB.
 * @return  bool    true if sucessful; false otherwise
 */
public function createDB($name, $user, $pass, $type, $host)
{
    switch($type)
    {
    case "mysql":

        //@todo
        // create the database here

        return true;
    }
    return false;
}

/**
 * Remove a database.
 *
 * If database usernames are tied to database names,
 * the database username can also be removed.
 *
 * @param   string  Name of database to be removed
 * @param   string  Database type
 * @return  bool    true if sucessful; false otherwise
 */
public function removeDB($name, $type)
{
    switch($type)
    {
    case "mysql":
   
           //@todo
        // delete the database here
        // this might be a call to your control panel's API,
        // or could be something like this:
        $db = mysql_connect("localhost", "root", "rootspass");
        mysql_query("DROP DATABASE ".mysql_real_escape_string($name, $db), $db);
        mysql_close($db);

        return true;
    }
    return false;
}

}

Don't hesitate to contact Installatron Support with any questions.

3.14.5. Hiding database inputs within the GUI

If offering users the ability to manually enter database information is not desired, it's possible to simplify the install workflow by hiding the GUI's "Database" section. To do this, execute this command as SSH root:

echo -n 'a:1:{s:22:"general_db_wizard_mode";s:4:"auto";}' > /var/installatron/data/admin/.settings

Note: If "admin" isn't the name of the admin user set in /usr/local/installatron/etc/settings.ini, replace "admin" in that file path with the correct value.