Skip to content

Installation

Install Proxmox Suite

Installation 4 min read

This page lists requirements and the install order for Proxmox Suite. It is written for the administrator putting the modules on a WHMCS host.

Requirements

  • WHMCS 8.13 or later
  • PHP 8.2 or later
  • ionCube Loader 13 or later for an encoded build
  • A Proxmox VE API token that can manage guests on the nodes you sell
  • A license key (PS-…) and, for encoded trees, srvprox.lic

Note

Development trees may be plain PHP and symlinked from ServBay. Production trees are encoded. A blank addon page that mentions ionCube is a loader or .lic problem, not a missing cluster.

Upload the module files

Proxmox Suite ships as two folders. The folder name is the technical identifier SrvProxmoxSuite. The name shown in WHMCS is Proxmox Suite.

  1. Upload modules/addons/SrvProxmoxSuite/ to modules/addons/.
  2. Upload modules/servers/SrvProxmoxSuite/ to modules/servers/.
  3. On an encoded build, place srvprox.lic in both folders. A license file only on the addon is not enough when the server module boots a Client Area page.

The web server must be able to read the uploaded files. The addon writes logs under modules/addons/SrvProxmoxSuite/storage/logs/%60 and a cron lock under storage/cron.lock`, so that storage directory must be writable by PHP.

Activate the addon

  1. Log in to WHMCS as a full administrator.
  2. Open System Settings → Addon Modules.
  3. Find Proxmox Suite and click Activate.
  4. Set Access Control to the admin roles that may manage the farm.
  5. Open Addons → Proxmox Suite.

Activation runs the schema installer and seeds the built-in cloud-init snippets. Success text: Proxmox Suite addon activated and schema installed. Deactivate does not drop tables. Every later addon page load runs the installer again; it is safe to repeat.

The addon configuration screen has no fields. The license key is entered on Info, not under System Settings → Addon Modules.

You should see the families Overview, Nodes, VM List, Resource, Media Manager, Products, Operations, Configuration, and Error Log. Until Info accepts a license, the other families stay closed.

Attach the server module to a product

  1. Open System Settings → Products/Services.
  2. Create or edit a product.
  3. Module Settings → Module Name = Proxmox Suite.
  4. Set the three options after you have a policy and a package:
Option What to choose
Distribution Policy An Active policy from Nodes → Policy Manager
Guest Type KVM or LXC. Default is KVM.
Hardware Package An Active package from Products → VM Plan, or None (module defaults)

The package’s own Policy field overrides the product’s Distribution Policy at create time when the package has one.

The server module does not implement Test Connection, List Accounts, or single sign-on. RequiresServer is off: do not create a WHMCS server row for Proxmox.

WHMCS action What Proxmox Suite does
Create Checks the license, resolves policy and package, may mint a hostname and password, writes the service password, enqueues a provision job, and runs that job once immediately.
Suspend Stops the linked guest.
Unsuspend Starts the linked guest.
Terminate Follows Configuration → General → Terminate mode (destroy now, or stop now and destroy after the grace period).
Change Package Enqueues an upgrade job.

Note

Package fields Suspension action, Terminate action, and Change package action are saved on the VM Plan. Suspend, Terminate, and Change Package do not read them. Terminate follows the global terminate policy. Suspend always stops the guest.

Cron is part of install

Copy the lines from Configuration → Cron Scheduler into the system crontab. The CLI entry point is:

text
php -q /path/to/whmcs/modules/addons/SrvProxmoxSuite/cron/run.php

AfterCronJob uses the same storage/cron.lock as cron/run.php. Until cron runs, catalog dropdowns stay empty, leftover provision jobs stay pending, and backup schedules and resource alerts never fire.

Details: Cron Scheduler.

Console

Browser consoles talk to Proxmox directly unless you turn on the optional proxy. Details: Console.

Next step

Continue to the post-install checklist, then first steps.