Guides & TutorialsUpdating WHMCS TroubleshootingHow to Set Up a Development and Testing Environment

How to Set Up a Development and Testing Environment

To safeguard your installation, data, and customizations, we recommend setting up a testing and development environment before you upgrade WHMCS or whenever you write modules, themes, or other customizations. Creating a testing and development environment will let you verify all of your customizations on the new version without any changes to your production system.

This process can find many issues, but you should also make sure to perform basic steps like creating a full backup and checking our release notes for changes before upgrading.

1. Get a Development License

You will need to contact WHMCS Customer Service to obtain a development license. You can get one free development license for every active license you purchase directly from If you purchase your WHMCS license through a reseller you will need to buy the license.

The addons associated with your paid license will be available in your test installation, with the exception of Live Chat. Installations using this type of license must be private and return a Forbidden error or login prompt if accessed.

2. Meet the System Requirements

Your testing and development environment should meet the same system requirements as a production installation. For the most accurate testing, this should be identical to your production setup.

3. Duplicate your WHMCS Installation

Your installation should also be identical to your production setup, with the same data and configuration. This will help you catch small details that might otherwise be missed. There are several methods to duplicate your installation.

If you're using cPanel, it's easy to copy your WHMCS installation in the File Manager interface:

  1. Log in to cPanel and go to Files >> File Manager.
  2. Select the folder for your production installation and click Copy.
  3. Enter the new location, which should be the location of your development installation.
  4. Edit the configuration.php file in your development environment to reflect the new location.

4. Duplicate your Database

The data WHMCS operates on also needs to be duplicated. This means creating a second database, exporting the existing database, and then importing it to your new database. Like duplicating the installation, there are several ways to do this.

If you're using cPanel, you could follow this process:

  1. Use the MySQL Databases interface to create the new database.
  2. Use phpMyAdmin to export the existing data and import it into your new database.

5. Password Protect your Installation's Directory

The development license requires you to make the development installation inaccessible, either using password protection or other methods that return an error or a login prompt.

In cPanel, you can password protect the installation's directory in Files >> Directory Privacy.

6. Update the System URL

Make sure to update the system URL in the General tab at Configuration > System Settings > General Settings to use the new testing environment's URL. If you can't access the installation to do it in the interface yet, you can use this MySQL command or update the value manually in phpMyAdmin:

UPDATE `tblconfiguration` SET value ='' WHERE setting='SystemURL';

7. Prevent Sending Mail

To prevent sending test mail from your development installation to your real customers, go to Configuration > System Settings > General Settings. In the General tab, set Disable Email Sending to ON.

You can also use a service like to serve this purpose.

You may also want to set your payment gateways and domain registrars to test mode and disconnect from your production servers. As another method, you can prevent accidentally charging customers by adding extra characters to the encryption hash in your development environment's configuration.php file. This makes WHMCS unable to read encrypted data, ensuring that it can't use encrypted data to charge credit cards or perform other actions.

You must exercise caution when you do this. Accidentally making this type of change on your production installation could cause serious problems.

Testing a New Version

Once you've copied your production installation and have confirmed that everything's working as expected, it's time to upgrade WHMCS. We recommend that you use the Automatic Updater for this, since it streamlines the process for you.

After upgrade, go through WHMCS and exercise all of the features and functions that you use most. Check both the client and admin areas, and make sure to place several orders for your various products. Walk these test orders through every step of the process, including marking them as paid and ensuring correct provisioning.

Monitor Configuration > System Health and look for any problems or incompatibilities. The Cron Job Activity Report email will confirm whether your automation tasks are successful.

Once you're satisfied with the results, you'll be able to proceed to upgrading your production installation.