2. Self-hosting Installatron Server

2.1. Prerequisites

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

For small-to-medimum production deployments we recommend starting with these system specifications:

4GB or more system memory

60GB or more disk space

4 or more CPU cores

Next, we recommend provisioning the server with a minimal install of CentOS 7, RHEL 7, Debian 8 or Amazon Linux.

Note: Instead of using a dedicated server just for Installatron Server, it's possible to install Installatron Server on the same server that an existing web hosting control panel is installed on. Please contact Installatron Support to learn more about this installation procedure.

2.2. Generate a License Key

Generate an Installatron Server License Key through your Installatron.com account portal. If you haven't already, you'll need to create an Installatron.com account. The provided License Key can be used on any number of servers. Generate License Key

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.

List of header arguments

NAME

VALUE

key

required

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.

user

optional but recommended

An alphanumeric value that the list of websites provided for the current session can be associated with. This argument will be used to index data and cannot change.

websites

required

List of websites with each containing the below arguments. Note: Websites can only have one home directory so websites spread across multiple home directories will need separate website entries. See examples below.

NAME

VALUE

id

required

An alphanumeric value that will uniquely identify this website. This argument will be used to index data for this website and cannot change.

label

optional

A value that will uniquely identify this website that can contain any characters. This argument can change.

email

required

The email address for the website (used as the default value for any application's email input)

path

optional*

The path or URI to the home directory of this account (without a trailing directory separator).

Important notes for URI values:

The entire URI is AES encrypted in Installatron Server's database.

To ensure correct URI syntax the username and password values should be URL-encoded.

The host portion of the URI is used to distinguish between web servers. It's considered a best practice to use a web server-referencing hostname (eg., server123.host.net) or an IP address for the host portion of the URI. If this is not possible, make sure to include the server argument as documented below.

Supported protocols:

The local filesystem (including NFS shares)

SSH**

FTP

FTPS

SFTP**

Note: Both password and private key authentication is supported for the SSH and SFTP filesystem protocols; to authenticate by private key, substitute the private key for the password.

Examples:

/home/user

ftp://user:pass@server123.host.net

ssh://user:pass@server123.host.net

ftp://user:pass@12.23.34.45/httpdocs

*This value is required unless the instructions outlined in section 3.18.1 are followed to define paths on demand.**Both password and private key authentication is supported. To authenticate by private key, simply use the private key in place of the password within the URI.

vhosts

required

A set of key/value pairs that define each domain hosted by this website and its corresponding document root relative to path. The sample header sections below illustrate the correct formatting.

Example:

http://installatron.com =&gt public_html

http://dev1.installatron.com =&gt public_html/dev1

vhost_ip

optional, default is the IP address resolved via DNS

The IP address each domain listed in vhosts should resolve to, enabling Installatron Server to install to vhosts that might not resolve through DNS.

path_backups

optional, default is /application_backups/

A path relative to path where installed application backups will be saved, without a trailing directory separator.

server

optional, default is host portion of the path URI

The host portion of the path URI is used to distinguish between web servers by default. If for whatever reason this doesn't correctly distinguish web servers then a unique value for each web server should be set here.

uid

required if path is a local filesystem

The filesystem POSIX UID that files should be created as for this website. This value should only be included if path is a local filesystem path.

gid

required if path is a local filesystem

The filesystem POSIX GID that files should be created as for this website. This value should only be included if path is a local filesystem path.

mysql_host

optional, default is localhost

The default mysql server for this website. This value will be overridden if a different database host value is defined for an installed application.

language

optional, default is the systemwide default language or English

This website's default language. This is the language text strings and error messages will display in for requests involving this website. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations.

The ID of the application to list available versions of. This can be a single application or an array of multiple applications. By default the latest version of each application is listed. Listed versions are ordered correctly.

version

optional

If application is set to one application, set this to only list the specific version.

from-version

optional

If application is set to one application, set this to list all versions from specified version to the latest version. Each listed version includes a "upgrade_from" member which reveals whether an install at the specified version can upgraded to the listed version (values of "none" or "manual" mean it cannot). Listed versions are ordered correctly.

versions-available-from

optional

If application is set to one application, instead of the usual output this will return two lists, "versions-available" and "versions-available-minor", each listing the versions upgradable to from the specified value.

language

optional

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.

If the DNS will not resolve the provided url to the correct IP, use this argument to provide the correct IP.

db_host

required if the application requires a database, can be omitted if database automation is implemented

The database server.

db_name

required if the application requires a database, can be omitted if database automation is implemented

The pre-created database.

db_user

required if the application requires a database, can be omitted if database automation is implemented

The pre-created database username.

db_pass

required if the application requires a database, can be omitted if database automation is implemented

The pre-created database password.

db_prefix

optional, defaults to the prefix behavior configured at Installatron Admin > Features

The prefix applied to database tables.

db_host_ip

optional, typically omitted

If a different MySQL host value must be temporarily used to connect to the database, use this argument to provide the temporary address. Installed application files will be written with the "db_host" value, but Installatron will use "db_host_ip" while installing.

notification

optional

List of email notifications to send for the installed application (each separated with a comma). Omit this argument entirely to send all notifications, or define an empty string to send no notifications.

Available notifications:

install

install_error

clone

clone_error

backup

backup_error

restore

restore_error

update_available

update

update_error

plugin_update_available

plugin_update

plugin_update_error

A sample value could look like "update_available,update,update_error"

background

optional

When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.

Set this to the URI to a backup location (which will be associated with the defined "user" for the session).

Supported filesystem protocols:

FTP

FTPS

SFTP

SSH

WebDAV (HTTP)

WebDAVS (HTTPS)

Examples:

ftp://user:pass@server

sftp://user:pass@server/backups

ftp://user:pass@server/backups

webdav://user:pass@server/backups

Further optional arguments that depend on the application (get a full list of fields available for a specific application/version using the browser API):

NAME

VALUE

language

optional, default is the website's default language or English

The language of the application to be installed. For example, "en" for English or "zh_tw" for Chinese Traditional. Use the browser API to get a list of available languages for the installed application.

login

optional, default is randomly generated value

The username for the installed application's administrative account.

passwd

optional, default is randomly generated value

The password for the installed application's administrative account. If omitted, a randomized password is assumed.

sitetitle

optional, default is "My blog" or similar

The site title value for the installed application.

content

optional, default is "yes"

Set to "yes" for the sample/demo template.Set to "no" for the blank install template.Set to the ID of the template for a different template.

The ID of the application to be imported or migrated. For example, "wordpress" or "magento". See: List of applications.

version

optional, defaults to the automatically-detected version

The version of the application to be imported. If omitted, the version is automatically detected.

url

required

For a local Import this is the URL to where the application is current located. For a remote Import (a Migration) this is the destination URL where the copy of the source application will be constructed.

url_ip

optional, default is the IP address resolved via DNS

If DNS cannot resolve the provided url to the correct IP, use this argument to provide the correct IP.

source_url

required if migrating an installed application from a remote server

If migrating an installed application from a remote server, include this argument to provide the source installed application URL.

For example, "http://website.com/wordpress".

source_ftu

required if migrating an installed application from a remote server

If migrating an installed application from a remote server, include this argument to provide the source installed application account information.

Supported filesystem protocols:

FTP

FTPS

SFTP

SSH

Examples:

ftp://user:pass@website.com

sftp://user:pass@website.com/public_html

ftp://user:pass@website.com/public_html/wordpress

source_url_ip

optional, default is the IP address resolved via DNS

If migrating an installed application from a remote server, include this argument to provide Installatron the IP address that Installatron should use for the source server. Providing this value means that Installatron will not need to perform DNS lookup on the source domain.

3.8. Edit an installed application

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.

List of email notifications to send for the installed application (each separated with a comma). Omit this argument entirely to send all notifications, or define an empty string to send no notifications.

Available notifications:

install

install_error

clone

clone_error

backup

backup_error

restore

restore_error

update_available

update

update_error

plugin_update_available

plugin_update

plugin_update_error

A sample value could look like "update_available,update,update_error"

db_host

optional, defaults to the existing value

The server that hosts the installed application's database.

db_name

optional, defaults to the existing value

The name of the installed application's database.

db_user

optional, defaults to the existing value

The database username used to connect to the installed application's database.

The version to be updated to. Use the browser API to get a list of available versions.

Note: A value of 'current' can be used to skip updating (if only plugins and themes).

revert

optional, default is "no"

If set to 'yes', a backup will be created prior to attempting the upgrade, and the backup will automatically be restored if the upgrade fails.

plugin

optional

If set to '*' or a comma-separated list of plugin ID's, all plugins or the listed plugins will be updated to their current version (WordPress only). Use the view API to get a list of installed plugins.

theme

optional

If set to '*' or a comma-separated list of theme ID's, all themes or the listed themes will be updated to their current version (WordPress only). Use the view API to get a list of installed themes.

background

optional

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

Possible values include:

Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc..

A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.

The language the user interface should display in. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations. If omitted, the default language or English is assumed.

email

optional, default is the per website email value (if defined) or an empty string

An email address to display within the GUI. This value can also be defined per website.

package

optional

Specify a value that enables sets of users to be assigned different applications. For example, this might be set to "no_mysql" or "wordpress_only". The applications assigned are configured within the Installatron Server Admin GUI.

reseller

optional, default is the main administrator

Assign ownership to a reseller instead of the main administrator.

Examples

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

3.17.2. Accessing the GUI as an administrative user or a reseller

Using a similar guixfer request, sessions for administrator and reseller users can also be created. To create a GUI session for an administrator, define the user member to match the "admin=" value in /usr/local/installatron/etc/settings.ini as shown below (the value is usually "admin"). To create a GUI session for a reseller (or sub-reseller), define the user member to the name of the reseller.

3.17.3. 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 /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:

<?phpclass 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" for the selected website it will be available in this array. // All custom variable names must begin with an underscore (_).$prefix = itron::$session["_some_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);

3.18. Advanced

3.18.1. Define a website path on demand

Most commonly the path variable for each website is directly defined within the Request Header. This optional method allows the path variable to be omitted from the Request Header. This can provide a superior level of security since path authentication information can be activated or created only when needed.

The disablePathByWebsite method is called between 30 minutes and 4 hours after a session's last action.

To use this method, implement each of the below PHP methods into the /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:

<?phpclass i_custom extends i_panel{

/** * Return the path URI for the provided website. * * @param array An array of website information as defined in the Installatron Server API Request Header. * @return string The URI for the website path, as it would have been defined for the Installatron Server Request Header. */public function enablePathByWebsite($websiteInfo){ return "ssh://".urlencode("user").":".urlencode("pass")."@11.42.62.82/domains";}

3.18.2. Improve FTP file operation performance

Installatron Server uses the path defined within the Request Header to communicate with the destination web server. Due to the nature of the protocol, all FTP-based protocols (FTP, FTPS and SFTP) limit the speed at which file operations can be completed.

To improve performance when using a FTP-based protocol, a SSH connection can be activated on demand which enables Installatron Server to execute commands efficiently on the destination web server.

To use this option, implement each of the below PHP methods into the /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:

<?phpclass i_custom extends i_panel{

/** * Return the path URI for the provided website. * * @param array An array of website information as defined in the Installatron Server API Request Header. * @return string The URI for the website path, as it would have been defined for the Installatron Server Request Header. */public function enableSecondaryPathByWebsite($websiteInfo){ return "ssh://".urlencode("user").":".urlencode("pass")."@11.42.62.82/domains";}

3.18.3. Create/edit user data within the Installatron Server database

This optional method enables Installatron Server user and associated website data to be modified (or created if the user doesn't exist).

By default all users are owned by the main administrative user. Creating resellers and/or sub-resellers allows sets of users to be managed separately and assigned different branding, theming, and other settings.

List of websites for the user. Please reference 3.1. Request Header for arguments. Reseller-type users can have their own websites defined, however typically this argument is omitted for resellers.

language

optional, default is the existing value or the systemwide default language or English for new users

The language the user interface should display in. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations. If omitted, the default language or English is assumed.

email

optional, default is the existing value or the per website email value (if defined) or an empty string for new users

An email address for the user. This value can also be defined per website.

package

optional, default is the existing value or an empty string for new users

Specify a value that enables sets of users to be assigned different applications. For example, this might be set to "no_mysql" or "wordpress_only". The applications assigned are configured within the Installatron Server Admin GUI.

reseller

optional, default is the existing value or the main administrator for new users

4. Maintaining Installatron Server

4.1. How app updates work

The settings at Installatron Admin > Settings control how frequently Installatron Server checks for new app updates by configuring the crontab process at /etc/cron.d/installatron. When this crontab process executes, Installatron Server checks every installation to determine whether an update is available, and if automatic update is enabled then Installatron Server will automatically queue the update task, otherwise an email notification will be sent to inform the customer that an update is available.

Installatron Server utilizes a task queue to prevent the system from overloading due to too many tasks. No more than the number of tasks configured at Installatron Admin > Settings can execute concurrently.

As of Installatron Server 4.1.15, a new setting at Installatron Admin > Features > Force Update After enables server administrators to configure Installatron Server to forcibly update installed apps after a set number of days have elapsed since the update became available. This feature can be useful to enforce an update policy.