Learn How To Install WHMCS with Plesk Control Panel

This WHMCS tutorial is written to guide you through the process of preparing for your WHMCS installation to post-installation tasks which include securing your billing system.

• WARNING: Avoid installing WHMCS on the same Plesk server that it will manage, as web services will restart during provisioning, leading to errors in WHMCS.
• Note: WHMCS has been tested in Linux environments using the Apache web server. Other setups, such as Windows-based configurations and NGINX, may face compatibility issues and are not supported.
• WHMCS is intended for managing remote Plesk servers. Management of the local server (the same Plesk server where WHMCS is installed) is not supported.

Initial Preparation:

If you're using cPanel, refer to the documentation below for prerequisites and pre-installation steps necessary for a successful WHMCS installation on a domain such as billings.example.com.

• Effortless WHMCS Installation Using the Softaculous 1-Click Installer
• How to Install and Configure WHMCS Using the Command Line

Requirements Specific to Plesk:

WHMCS is compatible with most web server environments that utilize PHP and MySQL®. Before installing or updating WHMCS, ensure your setup meets the system requirements for your selected version. For instance, before upgrading from WHMCS 8.9 to 8.11, verify that your system complies with all requirements for WHMCS 8.10.

System Requirements

To run currently supported versions of WHMCS successfully, your system must meet these requirements:

It is strongly recommended to use the latest stable releases of all software and extensions listed above. Memory and disk space requirements can vary based on the size and activity level of the installation. The information above pertains only to currently supported versions. For system requirements regarding updates from older End-of-Life (EOL) versions, see our HardenedPHP hosting packages.

System Environment

WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment using the standard Linux filesystem and cron subsystem. While NGINX® can be used in place of Apache, hosting WHMCS with WebHostingM means operating within Linux environments running the Apache web server. We do not support Windows®-based configurations.

Apache Handlers

With WebHostingM, you will have access to mod_lsapi, the fastest handler currently available. On other platforms, you can opt for virtual host handlers or server-wide handlers. Virtual host handlers (like suPHP or mod_ruid2) execute the PHP process based on the domain name, while server-wide handlers (like CGI or mod_php) run all PHP code as the same user.

Apache Directives

WHMCS utilizes configuration directives in the following .htaccess files:

• The ~/(dot)htaccess file contains mod_rewrite directives that route paths through the index.php file, enabling the internal routing system and creating friendly URLs.
• The ~/vendor/(dot)htaccess file prevents direct access to files in the ~/vendor directory while allowing WHMCS to access its libraries.

MySQL Database

WHMCS requires MySQL for proper database operation, but binary-compatible alternatives like MariaDB® may work for certain installations.

Database Privileges

For installation, WHMCS requires the following database privileges:

For daily operations, you can limit WHMCS's database privileges by removing ALTER, CREATE, DROP, and INDEX rights. These privileges are only necessary for installations, updates, and activating or deactivating modules.

Encrypted Database Connections

Support for encrypted MySQL connections utilizes the following variables in the configuration.php file:

If you enable db_tls_verify_cert (1), the db_host value in the configuration.php file must match the Common Name (CN) or be a Subject Alternative Name (SAN) of the certificate specified for db_tls_cert. If they do not match, an error will occur. For additional information, refer to the Could Not Connect Errors documentation.

To resolve a hostname mismatch when db_tls_verify_cert is enabled, set it to 0 or provide a new certificate with a matching CN or SAN for the db_host value.

These variables can be configured before, during, or after installation using the command-line installation method or after installation with the browser-based method.

PHP Extensions

WHMCS requires default compiled extensions (e.g., PDO, mysqlnd, JSON, libxml, DOM, or Fileinfo).

• If your hosting package supports EasyApache 4 PHP, these extensions are pre-configured for you.
• For HardenedPHP hosting, you can choose which PHP extensions to run.

- If a required extension is not listed, do not disable it.
- PCI compliance may necessitate TLS 1.2.
- Ensure PDO_MySQL is compiled with mysqlnd, not with libmysqlclient.

File Permissions

The required permissions for WHMCS depend on your system configuration. The following permissions are recommended for standard cPanel & WHM servers:

File ownership and group should match the user directory name. For example, on a cPanel & WHM server with a web root at /home/username/public_html/, the username should own the files, and the group should also be the username.

The PHP process owner and group must be the same as the user directory name. For instance, on a cPanel & WHM server with a web root at /home/username/public_html/, both the owner and group of the PHP process should be the username.

For most WHMCS installations, we recommend the following permissions:

All other files should have 644 permissions (Owner writable, otherwise readable). All other directories should have 755 permissions (Owner writable, otherwise readable and executable).

• This does not apply to installations using suPHP or phpSuExec.
• If you use DSO as your PHP handler, ensure you apply 644 permissions.

Begin by creating a new subscription (e.g., billings.example_domain.com) or selecting the domain name you wish to use for accessing WHMCS. If you decide to change the domain name later, you can easily reconfigure WHMCS to accommodate this change.

Ensure the website is secured with a valid SSL/TLS certificate using the SSL It! extension.

Update the website's PHP version to 8.1/8.2 or to any currently supported PHP version.

Create a new database by navigating to Domains > billings.example_domain.com > Databases. Take note of the database username and password, as they will be required later.

Log into Plesk and go to Domains > example.com > Databases. Click on Add Database, fill in the database details, and click OK.

Create a Database via Command Line

Log in via SSH and execute the following command, replacing example_database with your desired database name and example.com with your domain:

plesk bin database --create example_database -domain example.com -type mysql

WHMCS Installation via a Browser:

If you obtained your license key from WebHostingM, please contact us for a copy of the latest version of WHMCS, or create a ticket to request that we install WHMCS for you.

If you purchased your license key directly from WHMCS, visit the WHMCS Downloads page and click Download under Full Release to get the latest WHMCS version as specified in the WHMCS documentation.

After downloading, extract the archive and upload it to the httpdocs directory of your domain by going to Domains > billings.example_domain.com > /httpdocs. For detailed instructions, refer to the How to upload a file/folder via Plesk File Manager documentation.

WHMCS Installation via Command-Line:

To download the zip file using the URL from the JSON to the website's httpdocs directory, follow these steps:

cd /var/www/vhosts/billings.example_domain.com/httpdocs/

wget https://releases.whmcs.com/v2/pkgs/whmcs-8.10.1-release.1.zip

unzip whmcs-8.10.1-release.1.zip

Set Up WHMCS:

Via a Browser:

Locate the configuration.php.new file in your domain directory and rename it to configuration.php.

Edit the file to remove the following lines:

Prevent sample file execution. Remove from live configuration.
  return;

In a web browser, navigate to the installation script at the following address: https://billings.example_domain.com/install/install.php. Remember to replace billings.example_domain.com with your actual domain name or path.

Post-Install Steps:

Connect to the server via SSH.

Delete the install directory and the WHMCS zip file you downloaded earlier, as they are no longer needed:

rm -rf /var/www/vhosts/billings.example_domain.com/httpdocs/install/

rm /var/www/vhosts/billings.example_domain.com/httpdocs/whmcs-8.10.1-release.1.zip

Set up a cron job in your control panel to execute the following command every five minutes, or as frequently as your hosting provider permits:

php -q /var/www/vhosts/billings.example_domain.com/httpdocs/crons/cron.php

Accessing WHMCS:

After completing the previous steps, you can access the WHMCS admin panel at https://billings.example_domain.com/admin.

WHMCS Configuration

It is recommended to implement enhanced security measures as outlined in the official documentation.

Secure the Configuration File

Adjust the permissions for the configuration.php file in the WHMCS root directory. This file contains sensitive information that cannot be recovered without a backup. Changing the file permissions helps prevent accidental overwriting, editing, or deletion. To update the file permissions, execute the following command:

chmod 400 /var/www/vhosts/billings.example_domain.com/httpdocs/configuration.php

Move Writable Directories

WHMCS requires three writable directories: templates_c, attachments, and downloads.

Create a New Directory

Create a new directory outside the httpdocs directory for templates_c:

mkdir /var/www/vhosts/billings.example_domain.com/whmcs/

Move the three writable directories to the newly created directory:

mv /var/www/vhosts/billings.example_domain.com/httpdocs/templates_c/ /var/www/vhosts/billings.example_domain.com/whmcs/

mv /var/www/vhosts/billings.example_domain.com/httpdocs/attachments/ /var/www/vhosts/billings.example_domain.com/whmcs/

mv /var/www/vhosts/billings.example_domain.com/httpdocs/downloads/ /var/www/vhosts/billings.example_domain.com/whmcs/

mv /var/www/vhosts/billings.example_domain.com/httpdocs/crons/ /var/www/vhosts/billings.example_domain.com/whmcs/

Rename and Edit Configuration

Rename the config.php.new file (within the cron directory) to config.php. Open the config.php file and locate the $whmcspath line. For example:

// $whmcspath = '/path/to/whmcs/';
  

Remove the two / characters at the beginning of the line and update the path with the full path to your WHMCS installation. For example:

$whmcspath = '/var/www/vhosts/billings.example_domain.com/httpdocs/';
  

Edit the configuration.php file to update the $templates_compiledir variable to point to the directory you created:

$templates_compiledir = '/var/www/vhosts/billings.example_domain.com/whmcs/templates_c';
  $crons_dir = '/var/www/vhosts/billings.example_domain.com/whmcs/crons/';
  $attachments_dir = '/var/www/vhosts/billings.example_domain.com/whmcs/attachments/';
  $downloads_dir = '/var/www/vhosts/billings.example_domain.com/whmcs/downloads/';
  

Update the Cron Job

Ensure to update the cron job in your control panel.

More Recommended Changes

Correct session.save_path

Adjust session.save_path:

1. 1. Create a directory for PHP sessions:

mkdir /var/www/vhosts/billings.example_domain.com/whmcs/sessions

1. 1. Navigate to Domains > billings.example_domain.com > PHP Settings and set session.save_path to the full path of the created folder:

session.save_path: ":/var/www/vhosts/billings.example_domain.com/whmcs/sessions"

Set PHP Timezone

Change the PHP timezone based on the How to change date timezone parameter for PHP article or follow these instructions:

1. 1. Log into Plesk.
   2. Go to Domains > billings.example_domain.com > PHP Settings and specify your timezone in the Additional configuration directives field. A list of supported time zones is available here. For example:

date.timezone = Etc/UTC

Configure Automatic Update

1. 1. Create a temporary path for staging files during updates. Ensure this directory is outside the public document root, similar to the attachments, downloads, and templates_c directories:

mkdir /var/www/vhosts/billings.example_domain.com/whmcs/updater_tmp_dir

1. 1. Navigate to Utilities > Update WHMCS.
   2. Click Configure Update Settings in the top right corner of the page.
   3. Enter the absolute path for the new directory under Temporary Path, for example:

/var/www/vhosts/billings.example_domain.com/whmcs/updater_tmp_dir