This guide walks you through installing WHMCS on your server using a ServerLicenser Monthly License. The installer handles IonCube, web server configuration, Let's Encrypt SSL, database setup, the WHMCS schema, the admin user, and daily license verification in a single command. Most installs take about 10 minutes, with the script itself running for 3–5 minutes.

Two Install Modes

The installer supports two modes:

  1. Fresh install — you don't have WHMCS yet. The script installs and configures everything.
  2. Convert existing — you already have WHMCS running. The script adds daily license monitoring on top, without touching your existing data.

The installer asks which mode to use at the start. You can skip the prompt by passing --mode=fresh or --mode=convert.


What You Need

  • A Linux server with root SSH access (Ubuntu, Debian, CentOS, AlmaLinux, RHEL, and Rocky are all supported)
  • PHP 8.1, 8.2, or 8.3 installed (the installer adds any missing extensions automatically)
  • MySQL 5.7+ or MariaDB 10.5+ running locally
  • Your domain (e.g. whmcs.yourdomain.com) with DNS already pointing to your server's IP address
  • A fresh, empty database, or you can let the installer create one for you with --db-create
  • Your WHMCS Monthly License credentials from your ServerLicenser customer portal

Important: Your domain must already resolve to your server's public IP before you run the installer. The installer checks DNS first and will stop with a clear message if DNS isn't configured yet. You can confirm this yourself by running:

Terminal
dig +short yourdomain.com

Confirm the output matches your server's IP address before continuing.


Step 1 — Get the Install Command from Your Portal

  1. Log into your ServerLicenser customer portal.
  2. Click Licenses in the left sidebar.
  3. Find the row labeled WHMCS and click it.
  4. Scroll to the Install command section.
  5. Copy the command shown — it already contains your license credentials.

The base command will look similar to this:

Terminal
curl -fsSL https://serverlicenser.com/api/v1/whmcs/install.sh | bash -s -- \
  --token=tok_xxxxxxxxxxxx \
  --license-key=WMC-XXXXX-XXXXX-XXXXX \
  --license-secret=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --version=8.13.0

If you're doing a fresh install, you'll add a few more flags before running — see Step 3. If you're converting an existing WHMCS install, the command above is everything you need.

Caution: This command contains your license key, license secret, and download token. Do not share it publicly (forums, chat groups, screenshots). If it ever leaks, open a support ticket and we'll rotate the credentials.


Step 2 — Connect to Your Server as Root

Terminal
ssh root@your-server-ip

If your server uses a non-root user with sudo access instead:

Terminal
ssh youruser@your-server-ip
sudo -i

You should see a # prompt once you're logged in as root.

Caution: Don't run the installer from inside an existing WHMCS install directory. Always start from /tmp or your home directory:

Terminal
cd /tmp

Step 3 — Run the Install Command

Fresh Install (No Existing WHMCS)

Extend the command from Step 1 with these additional flags:

Terminal
curl -fsSL https://serverlicenser.com/api/v1/whmcs/install.sh | bash -s -- \
  --mode=fresh \
  --token=tok_xxxxxxxxxxxx \
  --license-key=WMC-XXXXX-XXXXX-XXXXX \
  --license-secret=xxxx... \
  --version=8.13.0 \
  --domain=whmcs.yourdomain.com \
  --db-create \
  --db-name=whmcs \
  --db-user=whmcs \
  --db-pass=CHANGE_TO_A_STRONG_PASSWORD \
  [email protected] \
  --admin-password=CHANGE_TO_A_STRONG_PASSWORD

Replace the following before running:

  • whmcs.yourdomain.com — the domain already pointing to this server
  • CHANGE_TO_A_STRONG_PASSWORD (appears twice) — use a strong, unique password for the database user and the WHMCS admin account
  • [email protected] — your email address, also used for Let's Encrypt renewal notifications

--db-create tells the installer to create the database and user automatically via local MySQL root access. If you already have an empty database ready, remove --db-create and point the flags at your existing database name and user instead.

Convert Existing (Already Have WHMCS)

Use the base command from Step 1 with --mode=convert added:

Terminal
curl -fsSL https://serverlicenser.com/api/v1/whmcs/install.sh | bash -s -- \
  --mode=convert \
  --token=tok_xxxxxxxxxxxx \
  --license-key=WMC-XXXXX-XXXXX-XXXXX \
  --license-secret=xxxx... \
  --version=8.13.0 \
  --target=/var/www/your-existing-whmcs

Replace /var/www/your-existing-whmcs with the actual directory your existing WHMCS install lives in (the folder containing init.php).

What Happens During a Fresh Install

The installer runs through several stages and reports progress for each:

Terminal
==> Preflight checks
==> Install mode
==> DNS check: whmcs.yourdomain.com   ← stops here if DNS isn't correct
==> Download WHMCS 8.13.0 bundle       ← ~154 MB, verified by SHA-256
==> PHP + IonCube                       ← installs IonCube loader if missing
==> Install WHMCS files to /var/www/whmcs
==> Database setup                      ← creates DB + user + loads schema
==> License monitoring setup            ← writes config + monitoring files
==> Web server config                   ← detects nginx/Apache, writes server block
==> Let's Encrypt SSL                   ← issues cert + redirects HTTP to HTTPS
==> Done

Expect this to take around 3–5 minutes.

What Happens During a Convert

Convert mode is much quicker — it only lays down the license monitoring files:

Terminal
==> Preflight checks
==> Download WHMCS 8.13.0 bundle
==> Convert mode — patch existing WHMCS
==> Done

It backs up your existing License.php with a timestamp, replaces it with the patched version required for license verification, adds a client-side monitoring file, writes the license configuration file, and updates .user.ini / .htaccess so the daily license check can run.


Step 4 — Confirm Your License Is Active

  1. Open your browser to https://whmcs.yourdomain.com/admin/ (or your custom admin folder path).
  2. Log in with the admin email and password you set during install.
  3. Go back to your ServerLicenser customer portal and open Licenses → your WHMCS license.
  4. Scroll to Recent verify activity. Within about 30 seconds you should see a new entry showing result: active and trigger: first_page_load.
  5. The Server IP and Domain fields will now show your server's details — this confirms the license is bound to this install.

Once this shows up, you're done. Daily license verification will run automatically in the background from this point on.


Important: What Not to Do

  • Don't delete the license configuration file from your WHMCS root. Without it, the install locks immediately on the next page request.
  • Don't remove the .user.ini file or the license-related block in .htaccess. Without them, the daily verification check never runs, and the install locks after 7 days offline.
  • Don't modify the patched vendor/whmcs/whmcs-foundation/lib/License.php file. Replacing it with the stock WHMCS file will cause WHMCS to contact the official WHMCS licensing servers instead, which will reject your install.
  • Don't use WHMCS' built-in upgrader. It will overwrite the patched License.php. To upgrade, re-run the install command with a new --version flag and --mode=convert against the same target directory (see below).
  • Don't change your server's IP address without first authorizing the new IP through the Change Server IP option on your license detail page.
  • Don't run the installer twice against the same target directory. If an install fails partway through, remove the target directory and start again (e.g. rm -rf /var/www/whmcs).
  • Don't commit the license configuration file to a git repository. Add it to .gitignore.

Troubleshooting

"DOMAIN does not resolve to any A record"

Your DNS has no A record for the domain you passed to the installer. Add one at your DNS provider pointing to your server's IP, wait a few minutes for propagation, then re-run the command.

"DOMAIN resolves to X.X.X.X but this server is Y.Y.Y.Y"

Your DNS is pointing somewhere else. Either correct the DNS record, or run the installer on the server your domain actually points to.

"Cannot connect to database"

This usually means one of two things:

  • The database credentials you passed are incorrect — double-check and fix them.
  • The database or user doesn't exist — add --db-create so the installer can create them (this requires local MySQL root socket access).

"IonCube install failed"

The installer couldn't download IonCube. Confirm your server can reach the IonCube download servers over HTTPS. If your server has no outbound internet access, install IonCube manually first, then re-run the installer.

"certbot failed"

This is usually caused by one of the following:

  • Port 80 isn't open inbound (Let's Encrypt validates domain ownership over HTTP).
  • DNS only just changed and hasn't fully propagated yet — wait about 10 minutes and re-run just the SSL step, e.g. certbot --nginx -d yourdomain.com.

Your site remains reachable over HTTP after a certbot failure; only the HTTPS redirect is missing until the certificate is issued.

Install locked: "License not configured"

The license configuration file was deleted, has incorrect permissions, or was never written. Re-run the installer with --mode=convert to restore it.

Install locked: "Cannot reach licensing server"

Your server can't reach our licensing API over HTTPS. Check your firewall's outbound rules, and confirm your server can reach serverlicenser.com over HTTPS.

Install locked: "Server IP changed"

You've moved the install to a different server. Use the Change Server IP option in your portal — the next verification check (within 24 hours) will rebind the license to the new IP.

Install locked: "Domain mismatch"

You've moved the install to a different domain. Open a support ticket with both the old and new domain, and we'll reset the binding for you.


Upgrading to a Newer WHMCS Version

Do not use WHMCS' built-in upgrader — it will overwrite the patched License.php file and break license verification.

Instead, re-run the installer in convert mode with the new version number:

Terminal
curl -fsSL https://serverlicenser.com/api/v1/whmcs/install.sh | bash -s -- \
  --mode=convert \
  --token=tok_xxxx --license-key=WMC-... --license-secret=... \
  --version=8.14.0 \
  --target=/var/www/whmcs

This downloads the new patched bundle and applies it over your existing install. Your database, configuration.php, and any customizations are left untouched.


Cancelling Your License

  1. Go to Licenses → your WHMCS license in your customer portal.
  2. Click Cancel auto-renew. Your install will keep working until the end of your current billing period.
  3. Once the period ends, the install will lock. Your data remains in the database — only the WHMCS interface stops working until you reactivate.

FAQ

Can I run the installer on any Linux distribution?
Ubuntu, Debian, CentOS, AlmaLinux, RHEL, and Rocky Linux are all supported.

Do I need to install IonCube myself first?
No. The installer installs the IonCube loader automatically if it isn't already present.

What happens if my license expires?
The WHMCS admin and client interface will lock, but your database and files remain intact. Reactivating the license restores access without reinstalling.

How do I move my WHMCS install to a new server?
Use the Change Server IP option in your customer portal to authorize the new IP before moving, so the next verification check binds correctly.


Getting Support

If you run into an issue not covered above, open a support ticket from your ServerLicenser customer portal and include:

  • Your license key (e.g. WMC-XXXXX-XXXXX-XXXXX)
  • The last 30 lines of the installer output (the ==> step headers help us identify where it stopped)
  • The exact lock-page error message, if one appeared
  • A copy of the license cache file from your WHMCS install directory, if it exists

Our team typically responds within 4 hours during business hours.

Was this answer helpful? 0 Users Found This Useful (0 Votes)