Tutorials How to get started with UpCloud WHMCS module

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.

Apache2

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

MariaDB

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.

sudo mysql_secure_installation

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.

PHP

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 firewall

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.

certbot --help

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.

certbot --apache

This starts an interactive installation script that will ask a few questions to help you set up the certificate.

  1. On the first installation on any specific host, you will need to enter a contact email.
  2. Next, go through the Let’s Encrypt Terms of Service and select Agree if you accept the terms and wish to use the service.
  3. 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.
  4. 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.
  5. 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.

http://whmcs.exampe.com/

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.

http://whmcs.exampe.com/loader-wizard.php

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.

https://whmcs.example.com

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:

  1. Select the Show on Order Form option
  2. Set the display name for the payment gateway.
  3. 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.

Additional configurations

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.

crontab -e
*/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

Summary

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!

8 thoughts on “How to get started with UpCloud WHMCS module

  1. Hi,

    I interested to use this official module for WHMCS to resell your service, but i need to ensure this module have the following features or not?

    – Both Admin and Client has Complete Access on Servers to Reboot, View Assigned IPs, Setup RDNS
    – Both Admin and Client have access to View Datatraffic, Server Login Information, Server Information, VNC Information
    – Admin Can do Start/Stop, Suspend/Unsuspend, Reboot/Terminate the server
    – Admin can do Assign/Release of Additional IP Address, Server Import as WHMCS Server
    – Auto Created Server on First Payment Receive from Customer and Auto Suspend on Bandwidth Overusage
    – Client will get Bandwidth Notification on 95% of usage

    Thanks,

    1. Hi there, thanks for the comment. The initial release of our WHMCS module includes most of these features. However, it’s still in development and we are looking for feedback from users to hear what features are required.

      1. Another question, when customers configure the server, NS1 & NS2 will automatically be made to Upcloud DNS and can use it?
        can you give me more information about that?

        I look at your competitors module, that they support the vanity name servers. So I can use the whitelabel nameservers for vps created.

        1. Hi and thanks for the question. The UpCloud DNS does not support user-configured records. You would need to use DNS of your own and authorise it at your domain registrar.

  2. I get the following error when I try to accept an order (after completing this installation tutorial):
    Module Create Failed – Service ID: 1 – Error: The request body contains an unknown attribute vnc.

    Google does not help and log files don’t show anything.

    1. Hi Tino, thanks for reaching out. This is a current known bug due to changes to an upcoming API specification that is already in experimental use with the WHMCS module. The module itself is still in beta, you can report any problems on the GitHub issues page.

  3. Hi Janne, thanks for the update.

    So in other words, currently it does not work, we should wait for the update?

    1. Unfortunately, I’m not aware of any workarounds at this time. We are working getting the bug fixed which should resolve the problem you encountered.

Leave a Reply

Your email address will not be published. Required fields are marked *

Locations

Helsinki (HQ)

In the capital city of Finland, you will find our headquarters, and our first data centre. This is where we handle most of our development and innovation.

London

London was our second office to open, and a important step in introducing UpCloud to the world. Here our amazing staff can help you with both sales and support, in addition to host tons of interesting meetups.

Singapore

Singapore was our 3rd office to be opened, and enjoys one of most engaged and fastest growing user bases we have ever seen.

Seattle

Seattle is our 4th and latest office to be opened, and our way to reach out across the pond to our many users in the Americas.