Ratals CMS includes a built-in installation process that can be automated by hosting providers to offer Ratals as a one-click installation option. Rather than recreating the Ratals installer, a hosting platform can deploy the current Ratals CMS files, create an empty database and database user, and submit the installation values directly to the existing installer using a server-side cURL request.
The installer handles the remaining setup, including creating the database structure, configuring the site, creating the initial administrator account, applying the custom administration path, and preparing Ratals for use.
This guide provides a working PHP cURL example, documents the values that can be submitted, and explains the basic workflow needed to integrate Ratals CMS into a hosting platform or application installer.
Table of Contents:
The Ratals one-click installation process uses the same installer as a normal manual installation. The difference is that the hosting platform supplies the installation values automatically instead of requiring the customer to complete the installation form.
The basic installation flow is:
The hosting provider does not need to duplicate the internal Ratals installation process. The one-click integration only needs to prepare the environment and submit the required values.
A clean copy of Ratals CMS must be deployed before the automated installation request is submitted.
The current Ratals CMS source and releases are available from the Ratals CMS GitHub repository.
Hosting providers implementing Ratals as an application installer should maintain a current Ratals CMS installation package that can be copied or extracted into each new customer's hosting environment. The files should be deployed in their original uninstalled state before the one-click installation script is executed.
The example in this guide assumes the Ratals files have already been deployed to the website. Downloading, extracting, or cloning the Ratals package can also be automated by the hosting platform, but that process is separate from the installer submission shown below.
Before submitting the one-click installation request, the hosting platform should have the website and database environment ready for Ratals.
The database used for a new Ratals installation should be empty. Ratals creates the required database structure during installation.
The following PHP example creates a secure installation token, writes the temporary token file used by the Ratals installer, submits the installation values using cURL, validates the successful installation response, and redirects the customer to their new administration area.
Values between the START - MODIFY INSTALL VARIABLES and END - MODIFY INSTALL VARIABLES comments can be populated by the hosting platform using customer selections, generated credentials, hosting account information, or provider defaults.
<?php
$installation_root = __DIR__;
//Create a secure one-click installation token.
$install_token = bin2hex(random_bytes(32));
$install_token_file = $installation_root.'/core/install-token.php';
$install_token_contents = "<?php\n".
"if(!defined('RATALS_INSTALLER'))\n".
"{\n".
"\t//Block direct access to this file in case an Nginx user has not yet configured the server to block access to the /core/ directory.\n".
"\thttp_response_code(403);\n".
"\tdie('Forbidden');\n".
"}\n\n".
"\$install_token = '".$install_token."';\n";
//Create installation token file.
if(file_put_contents($install_token_file, $install_token_contents, LOCK_EX) === false)
{
throw new Exception('Could not create /core/install-token.php.');
}
///////////////////////////////////////
//START - MODIFY INSTALL VARIABLES
///////////////////////////////////////
//URL where the Ratals files are installed.
//If you select Yes for HTTPS and/or WWW below, make sure they are also included in this URL.
$install_url = 'https://www.your-domain.com/';
//Set installation values.
$post_fields = array(
//INSTALLATION TOKEN
'install_token' => $install_token, //REQUIRED - Must match the token stored in /core/install-token.php.
//DATABASE CONNECTION
'database_hostname' => 'localhost', //REQUIRED
'database_name' => '', //REQUIRED
'database_username' => '', //REQUIRED
'database_password' => '', //REQUIRED
//SITE SETTINGS
'site_name' => 'Your Site Name', //REQUIRED
'https_in_url' => 'Yes', //OPTIONAL - Default: Yes. Can be Yes or No.
'www_in_url' => 'Yes', //OPTIONAL - Default: Yes. Can be Yes or No.
'tld' => 'your-domain.com', //REQUIRED - Domain only. Do not include http://, https://, or www.
'site_language' => 'en', //OPTIONAL - Default: en
'timezone' => 'America/New_York', //OPTIONAL - Default: America/New_York
'load_with_cache' => 'Yes', //OPTIONAL - Default: Yes. Can be Yes or No.
//CURRENCY FORMAT
'currency_type' => 'USD', //OPTIONAL - Default: USD
'front_symbol' => '$', //OPTIONAL - Default: $
'back_symbol' => '', //OPTIONAL - Default: empty
'thousand_separator' => ',', //OPTIONAL - Default: ,
'fractional_separator' => '.', //OPTIONAL - Default: .
'zeros_after_separator' => '2', //OPTIONAL - Default: 2
//OUTGOING SMTP EMAIL DELIVERY
//All SMTP fields are optional.
//If SMTP is not configured, Ratals will attempt to send email using the server's PHP mail() function.
//A persistent notice will display in the Ratals admin until the required SMTP delivery settings are completed.
'smtp_email_name' => '', //OPTIONAL - Default: empty
'smtp_email_address' => '', //OPTIONAL - Default: empty
'smtp_email_hostname' => '', //OPTIONAL - Default: empty
'smtp_email_port' => '', //OPTIONAL - Default: empty / NULL
'smtp_email_username' => '', //OPTIONAL - Default: empty
'smtp_email_password' => '', //OPTIONAL - Default: empty
//USER & COMPANY INFORMATION
'first_name' => '', //OPTIONAL - Default: empty
'last_name' => '', //OPTIONAL - Default: empty
'country' => '', //REQUIRED - Two-character uppercase country code, e.g. US
'street_address' => '', //OPTIONAL - Default: empty
'city' => '', //OPTIONAL - Default: empty
'state' => '', //OPTIONAL - Default: empty
'postal_code' => '', //OPTIONAL - Default: empty
'phone_number' => '', //OPTIONAL - Default: empty
'display_contact_information' => 'No', //OPTIONAL - Default: No. Can be Yes or No.
//ADMIN LOGIN CREDENTIALS
'admin_directory' => 'admin-login-url-path', //REQUIRED - Lowercase a-z, 0-9, and hyphens only. Must not use a common admin path.
'username' => 'admin-user-username', //REQUIRED
'user_email' => '[email protected]', //REQUIRED - Used for admin password recovery, security notifications, and other admin email.
'password' => 'ChangeMe123!', //REQUIRED - Minimum 10 characters with at least one letter, number, and special character.
'confirm_password' => 'ChangeMe123!' //REQUIRED - Must exactly match password.
);
///////////////////////////////////////
//END - MODIFY INSTALL VARIABLES
///////////////////////////////////////
//Initialize cURL.
$curl = curl_init();
if($curl === false)
{
throw new Exception('Could not initialize cURL.');
}
curl_setopt_array($curl, array(
CURLOPT_URL => $install_url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($post_fields),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 120
));
//Run installation.
$response = curl_exec($curl);
if($response === false)
{
$curl_error = curl_error($curl);
curl_close($curl);
throw new Exception('Ratals installation cURL request failed: '.$curl_error);
}
//Get response information.
$http_status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
curl_close($curl);
//Separate response headers and body.
$response_headers = substr($response, 0, $header_size);
$response_body = substr($response, $header_size);
//Expected successful installation redirect.
$expected_redirect = '/'.$post_fields['admin_directory'].'/?signup=success';
//Get Location header if one was returned.
$redirect_location = '';
if(preg_match('/^Location:\s*(.+)$/mi', $response_headers, $location_match))
{
$redirect_location = trim($location_match[1]);
}
//Make sure Ratals returned the expected successful installation redirect.
if($http_status >= 300 && $http_status < 400 && $redirect_location === $expected_redirect)
{
header('Location: '.rtrim($install_url, '/').$expected_redirect);
exit;
}
else
{
echo '<pre>';
echo 'Ratals installation did not return the expected success response.'."\n\n";
echo 'HTTP Status: '.$http_status."\n";
echo 'Expected Redirect: '.$expected_redirect."\n";
echo 'Returned Redirect: '.($redirect_location ?: 'None')."\n\n";
echo 'Response:'."\n";
echo htmlspecialchars($response_body);
echo '</pre>';
}
The one-click installation script can submit both required and optional Ratals installation settings. Optional fields can be populated by the hosting provider or left at their defaults.
install_token - Required for one-click installation
A secure temporary token used to authorize the automated installation request. The example script generates this value automatically, writes it to /core/install-token.php, and submits the same value to the Ratals installer. Hosting providers do not need to manually create this value when using the example script.
database_hostname - Required
The hostname used to connect to the database. This is commonly localhost when the database is hosted on the same server.
database_name - Required
The name of the empty database created for the Ratals installation.
database_username - Required
The database username with access to the Ratals database.
database_password - Required
The password for the database user.
site_name - Required
The name of the website being created.
https_in_url - Optional
Controls whether Ratals uses HTTPS in the website URL. Set to Yes or No. Default: Yes.
www_in_url - Optional
Controls whether Ratals uses www in the website URL. Set to Yes or No. Default: Yes.
tld - Required
The website domain without the protocol or www. Example: example.com.
site_language - Optional
The default Ratals site language. Default: en.
timezone - Optional
The default timezone used by the site. Example: America/New_York. Default: America/New_York.
load_with_cache - Optional
Controls whether Ratals frontend caching is enabled. Set to Yes or No. Default: Yes.
currency_type - Optional
The default currency code. Default: USD.
front_symbol - Optional
The currency symbol displayed before monetary values. Default: $.
back_symbol - Optional
An optional currency symbol or value displayed after monetary values. Default: empty.
thousand_separator - Optional
The character used as the thousands separator. Default: comma.
fractional_separator - Optional
The character used as the decimal or fractional separator. Default: period.
zeros_after_separator - Optional
The number of digits displayed after the fractional separator. Default: 2.
All SMTP settings are optional during installation. If SMTP is not configured, Ratals will attempt to send email using the server's PHP mail() function. Ratals will display an administration notice until the required SMTP delivery settings are completed.
smtp_email_name - Optional
The name displayed with outgoing SMTP email.
smtp_email_address - Optional
The email address Ratals uses to send outgoing SMTP email.
smtp_email_hostname - Optional
The SMTP server hostname.
smtp_email_port - Optional
The SMTP server port. When left empty, no SMTP port is configured.
smtp_email_username - Optional
The SMTP authentication username when required by the email provider.
smtp_email_password - Optional
The SMTP authentication password when required by the email provider.
first_name - Optional
The initial administrator or account holder's first name.
last_name - Optional
The initial administrator or account holder's last name.
country - Required
The two-character uppercase country code for the installation. Example: US.
street_address - Optional
The site or company street address.
city - Optional
The site or company city.
state - Optional
The site or company state, province, or region.
postal_code - Optional
The site or company postal code.
phone_number - Optional
The site or company phone number.
display_contact_information - Optional
Controls whether the supplied contact information can be displayed by the site. Set to Yes or No. Default: No.
admin_directory - Required
The custom virtual administration login path. Use lowercase letters a-z, numbers 0-9, and hyphens only. Do not use common administration paths such as admin, administrator, admin-login, or dashboard. The value should be difficult to guess.
username - Required
The username for the initial Ratals administrator account. Do not use common usernames such as admin, administrator, and root.
user_email - Required
The initial administrator's email address. Ratals uses this address for password recovery, security notifications, and other administrator email.
password - Required
The initial administrator password. It must contain at least 10 characters and include at least one letter, one number, and one special character.
confirm_password - Required
Must exactly match the value submitted for password.
After Ratals completes the installation successfully, the installer returns a redirect to the newly created custom administration path with ?signup=success.
The example cURL script does not automatically follow the Ratals redirect. Instead, it verifies that Ratals returned the expected successful installation location. After validation, the script redirects the customer's browser to the new Ratals administration area.
This allows the hosting platform to confirm that the installation completed before presenting the new administration login to the customer.
Ratals includes Apache configuration files with the CMS package. Nginx servers require equivalent server configuration for Ratals routing, protected directories, and the custom administration path.
Use the Ratals Nginx Configuration Generator to generate the configuration required for the installation.
The Nginx configuration should be prepared for the domain and custom administration path being submitted by the one-click installer. If the server already has an HTTPS or Certbot configuration, preserve the existing SSL configuration when applying the Ratals routing and security rules.
During development, a successful one-click installation can be reset and tested again without extracting and uploading the entire Ratals CMS package.
This process is intended only for development and installation testing. Do not perform these steps on a live Ratals installation.
Delete the following from the test installation:
/core/database/DbCredentials.php /sites/1 /sites/media
Re-upload the original versions of the following files from the clean Ratals CMS package:
/admin/.htaccess /admin/.user.ini /.htaccess /.user.ini
Remove all tables from the database used for the test installation. The database should be empty before the one-click installer is run again.
After the generated files and directories have been removed, the modified files restored, and the database emptied, the same Ratals files can be used for another one-click installation test without re-extracting the full CMS package.
For production provisioning, always begin each new customer installation with a clean, current Ratals CMS package.
Adding Ratals CMS as a one-click application does not require a hosting provider to recreate the Ratals installation process. The provider needs to deploy the current Ratals files, provision an empty database, supply the required installation values, and submit the server-side installation request.
Ratals handles the application setup and returns the customer's new administration location when installation is complete. This allows the same installer to support manual installations, hosting-panel integrations, and automated application provisioning while keeping the Ratals installation process consistent.
Hosting providers should test their automated process against the current Ratals CMS release before making an installer available to customers.