Set up a WHMCS staging copy for testing

Testing a WHMCS upgrade, a new theme or a third-party module directly on your live installation risks billing errors and angry customers. A staging copy lets you try everything first. The key is making sure the copy cannot email customers, charge cards or touch your servers.

Before you start

• A separate subdomain such as staging-billing.example.com with SSL, ideally password-protected.
• A development or test licence. WHMCS offers dev licences for owners of a full licence; check your account or provider.

Copy WHMCS

1. Export the live database and import it into a new database for staging.
2. Copy all WHMCS files to the staging folder.
3. Edit the staging configuration.php: new database credentials and the development licence key. Keep $cc_encryption_hash identical so encrypted data stays readable.
4. Update the WHMCS System URL in the staging database to the staging address (for example via a SQL update of the SystemURL setting in tblconfiguration), so links do not point to production.

Make staging harmless

• Do not add the cron job, or the copy will generate invoices and send reminders.
• Disable outgoing email: set the mail provider to a test SMTP catcher, or enable Disable Email Sending in General Settings → Mail.
• Switch gateways to sandbox/test mode or deactivate them; see Stripe test keys.
• Disable server modules or point servers to a test WHM account so no real accounts are suspended or terminated.
• Disable registrar modules or use registrar test environments.
• Enable Maintenance Mode or HTTP password protection so search engines and customers cannot find it.

What to test

• Upgrades: run the update on staging first and test orders, payments in sandbox and ticket import; see update WHMCS.
• Themes: develop your child theme on staging; see theme customisation.
• Hooks and modules: check new code with debug output enabled; see hooks.

Privacy

Staging contains real customer data. Protect it like production: strong admin passwords, 2FA, restricted access, and delete old staging copies when no longer needed. Consider anonymising client emails in the staging database.

Troubleshooting

• Licence invalid on staging: production licence used; switch to the dev licence.
• Links redirect to production: System URL still points to live.
• Customers received emails from staging: email sending was not disabled – fix immediately and apologise.

Next steps

• Database backups.
• Move WHMCS to a new server.
• Security checklist.