Top Tips For A Seamless Update

Updating a business-critical piece of software like WHMCS can be  intimidating, but at WHMCS, we put a lot of effort into ensuring  updating WHMCS is as safe and straightforward as possible. We take a  great deal of care to reduce obstacles wherever possible, for example by  avoiding template changes in maintenance updates wherever possible, and  maintaining backwards compatibility with features and functionality for  as long as possible. In this article I'll share my top tips for making  sure a WHMCS update goes smoothly.

I've split these tips into four main sections;

  • Preparation - Things to consider and prepare for before the update
  • Testing - Things to be aware of and test prior to updating
  • Execution - Tips for executing the update process on your production system
  • Validation - And finally some recommended validation checks for once the update is complete


As with many things, preparation is key, so start with some preparatory reading.  

It's  important to check that the requirements for the new version are met.  The latest system requirements are always available in our documentation.

If you intend to use the Automatic Updater, there are some additional system requirements  for that tool that are worth checking too. Most importantly, ensure  there's enough free disk space, and that PHP open_basedir contains the  entire WHMCS docroot.

The last bit of reading I'd recommend is to get familiar with the Release Notes.  Release Notes often contain important information about new features  and changes, as well as deprecation and removal notices, and of course,  any template changes.

The next consideration is for custom  modules and third party extensions, including hooks. Each should be  checked for compatibility with the new version.

Review the WHMCS Marketplace  listing, which will be updated by individual vendors when support for a  new version is added. If yours is not listed in the Marketplace,  contact the vendors directly. An update may be required to these  extensions or modules.

Now let's consider templates. First you should always ensure that all  your template customisations are contained within their own directory,  as any changes you make to the default templates will likely be  overwritten.

The Release Notes contain a Template Changes section with links to our template repos on Github. These repos and the links we provide allow you to see visual diffs of  the template changes between two versions making it easy to see the  changes you need to apply to custom templates.  

By making our templates available on GitHub, you can leverage the power  of Git to make the process of template updating faster and reduce the  potential for human error. Our Customising templates...the easy way blog post has a step by step walkthrough to help you get started.

A  number of customisations can also be made with override files. Override  files allow you to customise parts of the products in a way that is  safely preserved through the update process. For this reason we  recommend making the following customisations via override files. Click  on an item below to learn more.


I always recommend creating an exact replica of your installation for  testing purposes. This is useful not only for testing out updates, but  also testing out new features and functionality, as well as  customisations you make. All direct licence holders are entitled to a  free second licence for private testing and development purposes.  If  you don't already have one, you can request a development licence by  contacting our friendly Customer Service team.

To  create your test installation, create a full copy of the files and  database. Remember to update the configuration.php file in your copy to  use your development license key and new database credentials. You can  then use this installation to test the update process, third party  addons/extensions and templates on a separate development installation  first.

Often, you will want to ensure that the duplicate  installation can't send emails or actually charge your customers, so I  recommend performing the following steps:

  • Disable email sending  - Do this by navigating to Setup > General Settings > Mail tab  and select the "SMTP" Mail Type. Leave the SMTP credentials field blank  so that SMTP will fail.
  • Set payment gateways to test mode - Do this by navigating to Setup > Payments > Payment Gateways and checking the test mode boxes
  • Set domain registrars to test mode - Do this by navigating to Setup > Products/Services > Domain Registrars
  • Disconnect from live servers  - Do this by navigating to Setup > Products/Services > Servers  and invalidating the username and password credentials for your servers.

Now  you are ready to test the most important actions and functionality that  you use. Before we publish any new version, we run a whole suite of  automated and manual tests to ensure everything is working as we expect,  but differences in environments, setup configuration and customisations  can always impact the behaviour of a new version. Here are some of the  areas you should check:

  • The Admin Area - If some pages look a little weird; a hard refresh of browser or clearing browser cache usually does the trick.
  • The Client Area  - Login as a client and navigate to the service details and domain  details pages. Try submitting a ticket (remember, when masquerading as a  client you won't receive a new ticket notification email).
  • The Order Process - Place a new order. In the admin area, mark it as paid, to ensure provisioning is triggering as expected.
  • Automation Tasks  - At the daily automation settings "time of day" look for the Cron Job  Activity Report email to confirm the automation tasks completed  successfully

Once you're happy everything is working as it should, you're ready to perform the update!


The first step in executing a successful update is to take backups.  Typically we see people use a web based tool such as phpMyAdmin - but  you can also use mysqldump from the command line - to  backup the WHMCS MySQL database. Also take a copy of the entire WHMCS  files directory using your preferred method. This way, in the unlikely  event there is a problem, you can quickly revert.

The update process will need to create and alter tables in the MySQL database. So ensure the MySQL User has all available permissions granted for the duration of the update process.

I recommend using the Automatic Updater  as my experience is that users have the most success when using it.  Using the Automatic Updater will download, validate, extract the new  files and update the database - all in one click.

To do this, navigate to Utilities > Update WHMCS and click the Update Now button.  If the update was only recently released you may need to click the Check for Updates button first.

The manual option is always available for power users. If you do decide to update this way, here are some tips:

  • Always  upload the full version distro zip file and extract directly on the  server. Uploading individual files can take longer and it's easier for  files to be missed.
  • Ensure that all files upload, extract and  overwrite successfully. Permissions issues or lack of disk space are a  frequent cause of update failures we see in support.

For power users using the command line, the process might look something like:

mysqldump -u [username] -p [databaseName] >  whmcsdatabasebackup-$(date +%F).sqlmkdir  /home/whmcs/public_html/upgradestaging && cd  /home/whmcs/public_html/upgradestaging 
unzip /path/to/ 
cp /home/example/public_html/whmcs/configuration.php /home/example/public_html/upgradestaging/whmcs/ 
php -f home/example/public_html/upgradestaging/whmcs/install/bin/installer.php 
rm -rf /home/example/public_html/upgradestaging/whmcs/install/ 
mv /home/example/public_html/whmcs /home/example/public_html/whmcs_backup_xxxx-xx-xx/ 
mv /home/example/public_html/upgradestaging/whmcs/ /home/example/public_html/whmcs/ 
rm -rf /home/example/public_html/upgradestaging


When the update success message is displayed, you're nearly there. The  final step is to check everything is working as expected.

As before in the testing phase, we recommend testing key areas of  functionality such as can you login as a client, can you view product  details, can you submit a support ticket and can you place a new order.

I also recommend monitoring the Help > System Health Status page for any attention items in the following 24 hours.

If you follow the process outlined above, your chances for success when updating WHMCS are far higher.


 - John

Head of Support



Originally published at