How to Install Your WHMCS Monthly License (Step-by-Step)

This guide takes you from "I just bought a license" to "WHMCS is running on my server" in about 10 minutes.

The new installer (v2) handles everything in a single command: IonCube, web server config, Let's Encrypt SSL, database setup, WHMCS schema, admin user, and our daily license verification. You don't need to be a sysadmin.

Two install modes:

1. Fresh install — you don't have WHMCS yet. We install + configure everything.
2. Convert existing — you already have WHMCS running. We add our daily license monitoring on top, without touching your data.

The installer will ask you which mode at the start. If you already chose at purchase, you can pass --mode=fresh or --mode=convert to skip the prompt.

What You Need

• A Linux server with root SSH access (Ubuntu, Debian, CentOS, AlmaLinux, RHEL, Rocky all supported)
• PHP 8.1, 8.2, or 8.3 installed (the installer adds 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
• A fresh empty database OR you can ask the installer to create one (--db-create)
• Your WHMCS Monthly License credentials from the customer portal

Critical: Your domain must already resolve to this server's public IP before you run the installer. The installer checks DNS up front and stops with a helpful message if DNS isn't right yet. Run dig +short yourdomain.com and confirm it returns your server's IP.

1. Log into the customer portal: https://theserverlicense.com/login
2. Click Licenses in the left sidebar
3. Find the row labeled WHMCS and click it
4. Scroll to the Install command section
5. Click the copy button — the command goes to your clipboard

📸 Screenshot: customer portal

Terminal

Copy

/licenses

page with the WHMCS row.

📸 Screenshot: license detail page showing the "Install command" block with copy button.

The base command looks like:

curl -fsSL https://theserverlicense.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 (Mode 1), you'll add a few more flags before running. See Step 3.

If you're converting an existing WHMCS install (Mode 2), the command above is everything you need — paste and run.

Caution: That command contains your license_key, license_secret, and download_token. Do not share it publicly (forums, Discord, screenshots). If it ever leaks, open a support ticket — we'll rotate the credentials.

ssh root@your-server-ip

Or if your server uses a non-root user with sudo:

ssh youruser@your-server-ip
sudo -i

You should see a # prompt.

Caution: Don't run the installer inside an existing WHMCS install directory. Always start from

Terminal

Copy

/tmp

or your home directory:

Terminal

Copy

cd /tmp

If you're doing Fresh install (no existing WHMCS):

Extend the command from Step 1 with these flags:

curl -fsSL https://theserverlicense.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:

• whmcs.yourdomain.com — the domain pointing at this server
• CHANGE_TO_A_STRONG_PASSWORD (twice) — pick strong passwords for the DB user and the WHMCS admin
• [email protected] — your email (also used for Let's Encrypt notifications)

--db-create tells the installer to create the database + user via local root MySQL. If you already have an empty database ready, drop --db-create and use your existing DB name/user.

If you're doing Convert existing (already have WHMCS):

Just paste the base command from Step 1 and add --mode=convert:

curl -fsSL https://theserverlicense.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

What the installer does (Fresh mode)

The script runs in stages and shows progress for each:

==> Preflight checks
==> Install mode
==> DNS check: whmcs.yourdomain.com   ← if DNS is wrong, it stops here
==> 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
==> Tslz monitoring                     ← writes tslz.config.php + .user.ini
==> Web server config                   ← detects nginx/Apache, writes server-block
==> Let's Encrypt SSL                   ← issues cert + redirects HTTP → HTTPS
==> Done

📸 Screenshot: terminal output of a successful install showing the green ✓ progress lines.

Time: about 3–5 minutes.

What the installer does (Convert mode)

Much shorter — it just lays down the monitoring files:

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

Backs up your existing License.php (timestamped), replaces it with our patched version, drops

tslz-client.php

tslz.config.php

1. Open your browser to https://whmcs.yourdomain.com/admin/ (or your custom admin path)
2. Log in with the admin email + password you supplied
3. Go back to your customer portal: Licenses → your WHMCS license
4. Scroll to Recent verify activity — within 30 seconds you'll see a row with result=active and trigger=first_page_load
5. The Server IP and Domain fields are now populated — the license is bound to this server

📸 Screenshot: license detail page "Recent verify activity" section showing the first active row.

You're done. From now on, the daily license verification runs silently in the background.

What NOT to Do

• Don't delete
  Terminal

  Copy

  tslz.config.php

  from your WHMCS root. Without it, the install locks immediately on the next request.
• Don't delete the .user.ini or the # TSLZ block in .htaccess. Without them, the daily verify never fires; install locks after 7 days offline.
• Don't modify the patched
  Terminal

  Copy

  vendor/whmcs/whmcs-foundation/lib/License.php

  . Replacing it with the official WHMCS file makes WHMCS phone home to whmcs.com which will reject your install.
• Don't use WHMCS' built-in upgrader. It overwrites the patched License.php. To upgrade, re-run our install command with --version=<new_version> --mode=convert against the same target directory.
• Don't change your server IP without first authorizing the new IP via the Change Server IP ($1) button on your license detail page.
• Don't run the installer twice in the same target directory. If something failed and you need to retry, delete the target and start over (
  Terminal

  Copy

  rm -rf /var/www/whmcs

  ).
• Don't commit
  Terminal

  Copy

  tslz.config.php

  to your git repo. Add it to .gitignore.

Common Issues

DOMAIN does not resolve to any A record

Your DNS doesn't have an A record for the domain you passed. Add one at your DNS provider pointing to this server's IP, wait 1–10 minutes for propagation, then re-run.

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

DNS points somewhere else. Either fix the DNS record or run the installer on the server the DNS actually points to.

Cannot connect to database

Either:

• The DB credentials you passed are wrong → fix them
• The database/user doesn't exist → add --db-create to let the installer create them (requires local MySQL root socket access)

IonCube install failed

The installer couldn't fetch IonCube. Check

curl -fsSL https://downloads.ioncube.com/

certbot failed

Usually means:

• Port 80 isn't open inbound (Let's Encrypt validates over HTTP)
• DNS only just changed and Let's Encrypt's resolver hasn't picked it up — wait 10 minutes and re-run just the certbot step: certbot --nginx -d yourdomain.com

The site is still reachable on HTTP after a certbot failure — only the HTTPS redirect is missing.

Install locked: "License not configured"

tslz.config.php

Install locked: "Cannot reach licensing server"

Your server can't HTTPS to theserverlicense.com. Check firewall:

curl -fsSL https://theserverlicense.com/api/v1/whmcs/install.sh | head -3

If this fails, allow outbound HTTPS to our domain.

Install locked: "Server IP changed"

You moved the install to a different server. Click Change Server IP ($1) in your portal — the next verify (within 24h) will rebind to the new IP.

Install locked: "Domain mismatch"

You moved the install to a different domain. Open a support ticket with the old + new domain; we'll reset the binding.

Upgrading to a Newer WHMCS Version

Don't use WHMCS' built-in upgrader (it'll overwrite our patched License.php).

Instead, run our installer in convert mode with the new version:

curl -fsSL https://theserverlicense.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 lays it down over your existing install. Your DB, configuration.php, and customizations are untouched.

How to Cancel

1. Go to Licenses → your WHMCS license in the portal
2. Click Cancel auto-renew — your install keeps working until the end of the current billing period
3. After the period ends, the install will lock. Your data stays in the DB; only the WHMCS UI stops working until you reactivate.

Open a support ticket from your portal with:

• Your license key (e.g. WMC-XXXXX-XXXXX-XXXXX)
• The last 30 lines of installer output (the ==> step headers help us see where it stopped)
• The lock-page error message (if any)
• A copy of
  Terminal

  Copy

  /var/www/whmcs/.tslz-cache.json

  (if it exists)

Our team typically replies within 4 hours during business hours.