How to get started with UpCloud WHMCS module
If you would have an idea to create a business around web hosting but didn’t quite want to go about reinventing the wheel you’ve come to the right place! WHMCS is a web hosting management platform that gives you all the tools needed to start your web hosting business.
Build your ideas on effortless automation with WHMCS at the heart of your business. The modular, extensible, well-documented API’s and ORM all make developing with and customising WHMCS easy. Furthermore, UpCloud is now also available on WHMCS via our new module! Follow along with this guide on how to install WHMCS and configure your first cloud plan.
Note that WHMCS requires a monthly subscription for a licence to use the software and does not currently offer a free trial. As such, you should register with WHMCS before beginning if you are not already their existing customer.
1. Setting up API access
First of all, WHMCS will need API access to your UpCloud account to deploy and manage cloud servers on your behalf. We recommended using separate API credentials for each service you integrate with your UpCloud account. Therefore, you should create a new workgroup member for WHMCS API management.
Follow the instructions at our API tutorial to configure new API credentials for WHMCS.
2. Installing pre-requisite LAMP stack
WHMCS works much like any web-based platform and needs the usual LAMP stack components to work. In this guide, we’ll be installing WHMCS and its pre-requisites on a CentOS7 cloud server. The process would be similar if you choose another Linux distribution instead.
Before beginning, you should already have deployed a clean cloud server and gained SSH access to the terminal. You’ll also need a domain pointing to the public IP of your server to be able to install SSL certificates. Refer to your domain registrar for more info about how to accomplish this.
The first part of our hosting environment is the web server software itself. For this purpose, we’ve picked Apache2 due to the ease of install and configuration.
Start by installing Apache2, or httpd as it’s called on CentOS repositories.
sudo yum install httpd
Then create a new configuration file using the following command.
sudo vi /etc/httpd/conf.modules.d/whmcs.conf
Include the example configuration as shown below but replace the ServerName highlighted in red with your own domain name.
<VirtualHost *:80> ServerAdmin [email protected] ServerName whmcs.example.com DocumentRoot /var/www/html/whmcs/ ErrorLog /var/www/html/whmcs/error.log CustomLog /var/www/html/whmcs/access.log combined <Directory /var/www/html/whmcs/> Options Indexes FollowSymLinks MultiViews AllowOverride All </Directory> </VirtualHost>
Once done, save the file and exit the editor.
Then create the following directory to match the document root of your future WHMCS install.
sudo mkdir /var/www/html/whmcs
The second part of our web server is a MySQL compliant database server for which MariaDB is a great choice. It’s a popular open source alternative to MySQL and our go-to database server for many uses.
Install MariaDB server with the following command.
sudo yum install mariadb-server
Next, start the server software and enable it to run at boot as well.
sudo systemctl start mariadb sudo systemctl enable mariadb
Then complete the install by securing the system using the built-in procedure.
Complete the following steps:
- Set a secure password for root access
Change the root password? [Y/n] y
- Remove anonymous users? [Y/n] y
- Disallow root login remotely? [Y/n] y
- Remove test database and access to it? [Y/n] y
- Reload privilege tables now? [Y/n] y
Once done, open the client to connect to the database server with the command below. Enter the root password you just set in the previous step.
mysql -u root -p
Then create a new database for WHMCS with the following commands.
MariaDB [(none)]> create database whmcs; MariaDB [(none)]> GRANT ALL ON whmcs.* TO [email protected] IDENTIFIED BY 'whmcs'; MariaDB [(none)]> FLUSH PRIVILEGES; MariaDB [(none)]> exit
With the database ready, continue on to the next part in preparing your server.
WHMCS is built on PHP scripting language and requires the preprocessor to function. The latest release of PHP is not yet available in the default repositories so you’ll need to install the following additional packages and repositories.
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm sudo yum install yum-utils sudo yum install http://rpms.remirepo.net/enterprise/remi-release-7.rpm sudo yum-config-manager --enable remi-php72
Then finally install PHP along with its extra modules.
sudo yum -y install php php-pdo php-mysql php-gd php-xml php-mbstring php-soap php-xmlrpc php-zip
You might also need to create the following symbolic link to allow your server to discover the newly installed software.
ln -s /usr/bin/php72 /usr/bin/php
Test that everything is working by checking for the PHP version number.
php -v PHP 7.2.17 (cli) (built: Apr 3 2019 10:02:16) ( NTS )
If you see something like the example output above, you’ve successfully installed PHP and can continue on.
CentOS has a secure firewall configured by default which would prevent web access to your server. Enable connections through the firewall for HTTP and HTTPS services using the following command.
sudo firewall-cmd --permanent --add-service=http --add-service=https
Then reload the firewall rules to apply the changes.
sudo firewall-cmd --reload
Done! Your web server is now ready and you can continue with the next part of our tutorial.
3. Installing SSL certificates with Let's Encrypt
Let’s Encrypt greatly simplifies server management by automating obtaining SSL certificates and configuring web services to use them. The client is fully-featured and extensible for the Let’s Encrypt Certificate Authority or any other CA that supports the ACME protocol.
First, install the Certbot client and the Apache plug-in with the command below.
sudo yum install certbot python2-certbot-apache
Once installed, you can use the next command to test the client is working correctly.
Given that the help command works, the client is good to go.
To allow the Certbot client to accomplish the required tasks it supports a number of plugins that can be used to obtain or install certificates. With Apache2 you can use their dedicated plugin. The plugin automates both obtaining and installing certificates on an Apache web server. To use this plugin on the command line, simply include the flag --apache.
Begin obtaining and installing new certificates using the next command.
This starts an interactive installation script that will ask a few questions to help you set up the certificate.
- On the first installation on any specific host, you will need to enter a contact email.
- Next, go through the Let’s Encrypt Terms of Service and select Agree if you accept the terms and wish to use the service.
- Then, select whether you want to share your email address with the Electronic Frontier Foundation, a founding partner of the Let’s Encrypt project and the non-profit organization that develops Certbot.
- Enter the domain name hosted on the server you are installing the certificate on. If you have multiple domains on the same server, write them all here separated by a comma.
- Lastly, select whether you wish to use both HTTP and HTTPS or to redirect traffic to use encryption. We recommend using redirection for better security.
If everything worked correctly you’ll get a message that HTTPS was successfully enabled.
That is all you need to continue with this guide. However, you might wish to check how to set up automated renewals and improve your server security with our guide into Let’s Encrypt on Apache.
4. Installing WHMCS
Once you’ve made it this far, you are ready to install WHMCS itself. To begin, download the software from your WHMCS portal. You will need an active licence with WHMCS to access the downloads. Once you have the software package on your computer, upload it to your server, for example, using the secure copy scp.
scp download.zip [email protected]:~/whmcs.zip
You’ll also need to uncompress the file so install unzip with the following command.
sudo yum install unzip
Then depending on the file name of your download, e.g. whmcs.zip as shown below, unzip it to the default web directory.
sudo unzip /root/whmcs.zip -d /var/www/html
Next, give your web server controlling access to the files by changing the owner of the directory and the files within it.
sudo chown apache:apache -R /var/www/html/whmcs
Now, to be able to set up the site, you’ll need to rename the configuration file. Change into the site directory and remove the .new from the end of the configuration.php.new using the following command.
cd /var/www/html/whmcs sudo mv configuration.php.new configuration.php
Then open the web site on a browser by going to your domain to check that the page loads.
You’ll likely see the following error message, this is normal and will be resolved in the next step.
The error above is due to the last missing component you’ll need to download and install before WHMCS will run correctly. The software is encoded for copyright purposes and requires the PHP encoding tool called ionCube.
Download the ionCube loader scrip with the command below.
curl -L http://www.ioncube.com/loader-wizard/loader-wizard.zip -o ~/loader-wizard.zip
Unzip the files to, for example, your home directory.
sudo unzip ~/loader-wizard.zip -d ~/
Then copy the loader-wizard.php script to your web site directory and set the permissions.
sudo cp ~/ioncube/loader-wizard.php /var/www/html/whmcs sudo chown apache:apache /var/www/html/whmcs/loader-wizard.php
Next, restart the web server.
sudo systemctl restart httpd
You should then be able to open the script on your web site.
Select your server hosting type and press next to continue.
On the next page are outlined the steps required to download and install the necessary libraries. The same steps are listed below to ease the process.
Next, you will need to download the ionCube package either through the link on the loader page or with the following command below.
curl -L http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz -o ~/ioncube.tar.gz
Afterwards, extract the files and make them executable with the next two commands.
tar zxvf ~/ioncube.tar.gz -C ~/ chmod +x ~/ioncube/ioncube_loader*
Then move the ionCube files from the extracted folder to your PHP modules.
sudo mv ~/ioncube/ioncube_loader* /usr/lib64/php/modules
You will also need to create the following init file to enable the modules for your PHP version.
sudo vi /etc/php.d/ioncube.ini
zend_extension = /usr/lib64/php/modules/ioncube_loader_lin_7.2.so
Finally, restart your web server to apply all changes.
sudo systemctl restart httpd
The ionCube encoder should now be up and running. Click the loader tester link on the web page to check that everything is working correctly.
Once done, remove the loader wizard file for security reasons.
sudo rm /var/www/html/whmcs/loader-wizard.php
Then return to your web browser and reload your domain page. You should be redirected to the configuration page without errors.
WHMCS will perform system requirement checks and once passed you can continue by clicking the Begin Installation button.
In the next screen, enter your license details and configure database access as shown in the picture below.
Create an admin account then click the Complete Setup button.
With the installation completed successfully, you’ll be greeted with a confirmation page like shown in the example underneath. The page also includes additional steps to secure your WHMCS installation which we’ve outlined below.
First, delete the /install directory using the following command.
sudo rm -rf /var/www/html/whmcs/install
Then set the configuration file to read-only to prevent accidental or malicious changes.
sudo chmod 400 /var/www/html/whmcs/configuration.php
That’s it! You are now done with the installation and ready to begin configuring your admin portal. Continue in the next section on how to install the UpCloud module on your WHCMS site.
You might also wish to check the further security steps to-do list at their documentation.
5. Installing the WHMCS UpCloud module
Download the module from our GitHub repository, for example, by using git. If you do not already have git installed, get it first with the following command.
sudo yum install git
git clone https://github.com/UpCloudLtd/upcloud-whmcs-module.git ~/upcloud-whmcs-module
Next, copy the UpCloud module to the web server directory
sudo cp -r ~/upcloud-whmcs-module/modules /var/www/html/whmcs/
Then update the permissions to allow the web server user to make changes.
sudo chown apache:apache -R /var/www/html/whmcs/modules/servers/upCloudVm/
Finally, reload your web server again.
sudo systemctl reload httpd
All set! UpCloud can now be found as an infrastructure provider on your WHMCS admin panel. But before you can begin setting up cloud plans, you’ll need to configure API access to your UpCloud account if you haven’t already done so.
6. Configuring the UpCloud WHMCS module
You should now have a working installation of WHMCS together with the UpCloud module and can finally start configuring your services.
1. To begin, log into your WHMCS Admin Area and find the following section from the navigation bar.
Setup → Products/Services → Servers
First, create a new server configuration that will act as the API control. This does not actually deploy anything but only servers to store your API credentials.
In the new server configuration, select UpCloud VM as the server type. Enter necessary API credentials in the following fields for Username and Password. Then test the connection to confirm the details are correct and click the button to Save Changes.
Next, create a new group for the server and assign it to that group. By creating multiple different API credentials, you can isolate deployed cloud servers to prevent unintentional changes between server types. The server groups then again act as organizing tools for API credential configurations.
2. To continue, navigate to the Products and Services menu.
Setup → Products/Services → Products/Services
Create a new group for your products. Products can be freely organized in groups as you see fit.
Then, create a new product. Products show up to your clients as available server plans.
Select the previously created group from the dropdown menu and name your new product.
Next, move to the product Module Settings section and select the module called UpCloud VM as well as the previously created server group.
Then in the product main configuration section, you need to make the following choices:
• Select the Default Location cloud server of this product are deployed to.
• Choose Plan setting the server resources allocated to this product.
• Pick the Template to define the operating system the product will use.
Lastly, decide whether the product requires manual approval from admins or is automatically deployed upon order. Then confirm your selections by clicking the Save Changes button.
Additionally, you may also generate the default Configurable Options and Custom Fields. that can enable you to add extra features such as SSH keys and initialization scripts.
Simply click the corresponding texts in the Module Settings.
With that done, you have your first product now available in your client area. However, before it can be ordered by anyone, even if free, you should set up a payment gateway. Continue below on how to get this done using PayPal.
7. Adding payment gateway
Payment processors allow your clients to make payments on your products according to the pricing you’ve set. At least one payment processor is required even if the prices were set to free.
The easiest option is to configure PayPal with a recipient email to allow checkouts to be completed. Go to the payment gateway settings.
Setup → Payments → Payment gateways
Set up PayPal by going to the All Payment Gateways tab and clicking the PayPal button.
Then make the following configurations:
- Select the Show on Order Form option
- Set the display name for the payment gateway.
- Enter your PayPal account email address you wish the payments to be credited to.
Optionally for live production use, you should also configure PayPal API credentials to enable refunds and subscription cancellations. You can find about more about PayPal API credentials at their documentation pages.
Once you’ve made the required entries, click the Save Changes button to confirm the settings.
8. Making test order deployment
Your first product is then configured and available for order. There are still much other maintenance related tasks you should look at but first, let’s test the client side by placing an order for a new cloud server.
Go to your client portal and register a new user.
In the client area, click Services and place an order for a new cloud server.
You’ll then see the available products you’ve created. Click the Order Now button to select a product.
Enter a domain name for the new server and two name server prefixes as shown below then click the Continue button
This will take you to the Review and Checkout page where you can see the products currently placed in the order cart. Continue by clicking the Checkout button.
The order process will then ask you to confirm your contact details after which you should click the Complete Order button.
New orders can then be found at your Admin Area where you can manage the placed and existing orders. By accepting the order, the system will automatically deploy a new cloud server according to the product configurations.
That’s the extent of product orders. If you now log into your UpCloud control panel, you should see a new server has been created.
These additional configuration options are included with the UpCloud module and can be helpful in managing your services.
Enabling noVNC Console
Make sure the storage directory is set as recursively writable.
sudo chmod -R +w /var/www/html/whmcs/modules/servers/upCloudVm/storage
Download the websockify packages using the launch utility in the noVNC directory by first setting it executable and then running the script once.
sudo chmod +x /var/www/html/whmcs/modules/servers/upCloudVm/vendor/noVNC/utils/launch.sh /var/www/html/whmcs/modules/servers/upCloudVm/vendor/noVNC/utils/launch.sh
Then start the noVNC server using the below command. Replace the domain name highlighted in red with your own WHMCS server domain.
/var/www/html/whmcs/modules/servers/upCloudVm/vendor/noVNC/utils/websockify/run \ whmcs.example.com:45969 \ --web /var/www/html/whmcs/modules/servers/upCloudVm/vendor/noVNC \ --token-plugin TokenFile \ --token-source /var/www/html/whmcs/modules/servers/upCloudVm/storage/target.config.d \ --cert /etc/letsencrypt/live/whmcs.example.com/fullchain.pem \ --key /etc/letsencrypt/live/whmcs.example.com/privkey.pem \ --daemon
Automating tasks with Cron Jobs
Add the two below cron tasks at the bottom of your crontab.
*/5 * * * * php -q /var/www/html/whmcs/modules/servers/upCloudVm/crons/bandwidth.php */1 * * * * php -q /var/www/html/whmcs/modules/servers/upCloudVm/crons/tokens.php
The UpCloud module for WHMCS allows you to create and configure new product plans for your customers using the world’s fastest cloud servers! Our cloud servers will give you the advantage you deserve over any competitors. Rest assured as the best in class performance and reliability will help you build the services to conquer the market!