1. Introduction

Installatron Server is an API and optional UI that enables scalable and flexible application management to be integrated seamlessly into existing web hosting infrastructure.

Please reference the What is Installatron Server? page for more information about what Installatron Server is.

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

• Self-hosted (On Premise)
• Cloud-hosted (On Installatron.com)

And three integration interfaces for Installatron Server:

• HTTP API
• Command-line API
• Installatron Server UI

These interfaces are not mutually exclusive: you can use safely use multiple interfaces on the same Installatron Server instance. And the interfaces do not differ between self-hosted and cloud-hosted.

Installatron Server is mostly managed through API calls. To use Installatron Server, you will need to be comfortable using API-driven systems.

This document will explain how to use and interface with each hosting option, and offer suggestions for which methods work best in which situations.

2. Cloud-Hosted vs. Self-Hosted

Back to top▴

2.1. Cloud-hosted (On Installatron.com)

The cloud-hosted instance of Installatron Server for your company is provisioned on Installatron.com's servers and managed by our team.

This option is recommended for a low-maintenance, hassle-free solution:

• No need to worry about infrastructure, software updates, or security patches.
• Cloud-hosted instances automatically scale as usage increases.
• Applications are managed using a standard FTP(S), SFTP, or SSH layer which connects to your web hosting platform.

Follow these steps to use Installatron Server as a cloud service:

2.1.1. Prerequisites

Your web hosting platform will need to allow connections from Installatron.com. This may require firewall rule and rate limiting adjustments.

There are no additional prerequisites because Installatron Server is hosted on Installatron.com.

2.1.2. Get Started

If you haven't done so already, you'll need to create an Installatron.com account and then log in.

Afterwards, contact us to receive access and begin the integration process.

Back to top▴

2.2. Self-Hosted

The self-hosted Installatron Server is installed on one or more servers on your network and managed by your team.

This option is recommended to maximize data security and performance optimization:

• Customer data never leaves your infrastructure, reducing third-party risks.
• Multiple Installatron Server nodes can also be clustered for High Availability and Scalability.
• Using local infrastructure ensures faster processing and lower latency.

Follow these steps to deploy Installatron Server on your network:

2.2.1. Prerequisites

Installatron Server's architecture minimizes requirements while maximizing compatibility.

At least one server with a permanent internet connection is required to run Installatron Server. Management of this server is your responsibility, and we recommend the following best practices:

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

• 4 GB or more RAM
• 100GB or more disk space
• 4 or more CPU cores
• 64-bit architecture

For larger deployments, contact us for recommendations based on anticipated usage.

Installatron Server supports the following Linux distributions:

• Debian 12
• Debian 11
• Red Hat Enterprise Linux 9
• Red Hat Enterprise Linux 8
• CentOS Stream 9
• CentOS Stream 8
• AlmaLinux 9
• AlmaLinux 8
• Rocky Linux 9
• Rocky Linux 8
• Amazon Linux 2023
• Amazon Linux 2

We always recommend selecting a "minimal" variation of the distribution. Installatron Server will provision all necessary system services for you.

When partitioning your disk, we recommend a straightforward partition structure of:

• swap — The same as the amount of RAM on the server, but not more than 16 GB.
• / — Remaining balance of available disk space.

Finally, Installatron Server uses a MySQL database to store data. There are two options available:

• By default, Installatron Server will provision and manage MySQL on the local server.
• A second option to offload the database to a dedicated database server (Recommended for large deployments).

This concludes the Self-Hosted best practices and prerequisites. Contact us with any questions.

2.2.2. Generate a License Key

If you haven't done so already, you'll need to create an Installatron.com account and then log in.

You can now generate an Installatron Server License Key through your Installatron.com account portal.

The generated License Key can be used on any number of Installatron Server instances.

2.2.3. Download and Install

Start by provisioning the server following the best practices outlined in the Prerequisites section above.

Execute these commands from the SSH root command prompt (replace YOUR_LICENSE_KEY with the Installatron Server License Key generated in step 2.2.2):

• RHEL 9, CentOS Stream 9, Rocky Linux 9, AlmaLinux 9
  RHEL 8, CentOS Stream 8, Rocky Linux 8, AlmaLinux 8
• Debian 12
  Debian 11
• Amazon Linux 2023
  Amazon Linux 2
  

curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
yum -y remove httpd
./installatron-server.sh -f --key YOUR_LICENSE_KEY

curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
yum -y remove httpd
./installatron-server.sh -f --key YOUR_LICENSE_KEY

apt-get update
apt-get -y dist-upgrade
apt-get -y install curl net-tools
curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
./installatron-server.sh -f --key YOUR_LICENSE_KEY

Note: If the MySQL database has been offloaded to a dedicated database server, or to add an additional Installatron Server node to a cluster, add these arguments to the install command:

--db-host=sql.yourhost.com --db-user=youruser --db-pass=yourpass --db-name=itron

That will take a couple minutes to install the system services and dependencies for Installatron Server. Contact us if you observe any issues during the process.

Core files and programs are installed here:

/usr/local/installatron/

And Installatron's data files are installed here:

/var/installatron/

2.2.4. Complete

Installatron Server is now ready!

Continue to 3 Interfacing with Installatron Server below to see how to use your new instance of Installatron Server.

3. Interfacing with Installatron Server

Installatron Server can be accessed via UI or through API calls: the APIs can be called from both CLI and over HTTP.

Back to top▴

3.1. Interfaces

There are two ways to interface with Installatron Server, and it's worth noting that these interfaces are not mutually exclusive: they can both be used on the same server at any time.

Back to top▴

3.1.1. Accessing Installatron Server through UI

See the "guixfer" API for examples of using the Installatron Server UI.

Back to top▴

3.1.2. Accessing Installatron Server through APIs

See Installatron Server API Specification 1.0 for a complete list of all API calls and examples of how to use them.

3.17.1 Accessing the UI as a website owner TODO: move this

A session must be created before a user can be redirected to the Installatron Server UI. This is accomplished by issuing a "guixfer" request.

List of arguments

NAME	VALUE
cmd	guixfer
key	required part of the Request Header that must be included with all API requests
websites	required part of the Request Header that must be included with all API requests
user	required part of the Request Header that must be included with all API requests
reseller	optional part of the Request Header that must be included with all API requests
language	optional, default is the systemwide default language or English 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 UI. 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 UI.
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 UI:

<?php
$query = array(
    /* these values define the request header: */
    // Note: "key" is the "key=" from /usr/local/installatron/etc/settings.ini
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "websites" => array(
        array(
            "id" => "website123",
            "label" => "website.com",
            "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",
            "label" => "company.com",
            "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 UI, we need some mechanism to
            // handle databases. See section 3.17.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://installatron.yourhost.com/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://installatron.yourhost.com/index.php?s=".$reply["session_id"]);

3.17.2 Accessing the UI as an administrative user or a reseller TODO: move this

TODO: check that this has been moved to /apis/is/guixfer

Using a similar guixfer request, sessions for administrator and reseller users can also be created. To create a UI 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 UI session for a reseller (or sub-reseller), define the user member to the name of the reseller.

Note: Administrators and resellers can access the Installatron Server directly from the login screen if an account is pre-configured. By default the main administrator account is pre-configured. To pre-configure additional accounts reference 3.17.3. Create/edit user data within the Installatron Server database.

List of arguments

NAME	VALUE
cmd	guixfer
key	required part of the Request Header that must be included with all API requests
type	reseller
user	An alphanumeric value that will represent the reseller. This argument will be used to index data and cannot change.
reseller	optional, default is the main administrator Assign ownership to a reseller instead of the main administrator.

Example:

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

4. Maintaining Installatron Server

This additional information can help you understand your Installatron Server.

Back to top▴

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 user to let them know that an update is available.

Installatron Server utilizes a task queue to prevent the system from overloading from too many simultaneous 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 application update policy.

Back to top▴

4.2. Settings.ini values

Installatron Server's "/usr/local/installatron/etc/settings.ini" configuration file is provisioned automatically during installation and generally doesn't require manual editing. But here are some typical lines found in the settings.ini file:

NAME	VALUE
key	required The product key.
noperl	optional, default is "no" Installatron Server uses Perl .cgi files on the destination web server to speed up tasks. If Perl is not supported, this setting should be set to "yes" to avoid every task having to test Perl.
update	required, default is "release" The update channel. Valid values include "edge", "release", "stable", or "never" to switch off automatic updates.
debug	optional, default is "no" Set to "yes" to enable the debug log at /var/installatron/logs/debug_log which contains very verbose output which can be useful tracking down a multitude of issues.
db_type	required, default is "mysql" The type of database server. Mysql and sqlite supported. This setting is configured automatically during installation to use MySQL.
db_host	required for mysql, default is configured automatically The database server.
db_name	required for mysql, default is configured automatically The database.
db_user	required for mysql, default is configured automatically The database username.
db_pass	required for mysql, default is configured automatically The database password.
num_cpu	optional, default is the number of CPU threads multiplied by two The number of tasks allowed to execute concurrently systemwide.
num_cpu_perserver	optional, default is 5 The number of tasks allowed to execute concurrently per web server.
db_schema_update	optional, default is yes Whether database schema updates should be automatically managed by Installatron (recommended: yes).

Back to top▴

4.3. Useful command-line tools

Here are some useful CLI commands:

Forcibly update/repair the entire system:

/usr/local/installatron/repair -f --quick

Create a single-use access token for the administrative UI:

/usr/local/installatron/installatron --createsession

Reset administrative login:

/usr/local/installatron/installatron --repair --reset-admin

Forcibly check for customer app updates for user named barry:

/usr/local/installatron/installatron --taskscheduler --full --user barry