Installation & activation

Drop the module into modules/servers/, drop the addon into modules/addons/, activate, and add a license key. Most installs are done in 10 minutes.

Time: ~10 min · Requires: WHMCS 9.0+ · PHP 8.2–8.4 · ImpulseCore 1.61.19+

1. Prerequisites

Confirm the host where WHMCS runs has these in place:

• WHMCS 9.0 or later on PHP 8.2, 8.3 or 8.4.
• ImpulseCore 1.61.19+ — the shared Impulse addon. ImpulseObjects depends on it for licensing, project membership, hook dispatch, the cron runner, audit, and the Security & Maintenance pipeline. Install and activate impulsecore before activating ImpulseObjects.
• ionCube Loader 13+ for your PHP version. The module’s PHP files are encoded.
• File access to the WHMCS server to upload the release, and ideally a system cron entry for ImpulseCore’s cron runner (step 6).
• A VPS provider account with an API token that can create and destroy servers: Vultr, Hetzner Cloud, DigitalOcean, Linode, Amazon EC2, Microsoft Azure, Google Cloud, or Proxmox VE. Attached block-storage volumes are available on Vultr, Hetzner, DigitalOcean and Linode. You can also bring a server you already own (see Adding a storage server).
• A DNS provider account — Cloudflare (recommended), AWS Route 53, DigitalOcean, Vultr, Linode or Hetzner DNS. The module creates each server’s hostname records through it. Let’s Encrypt certificates are issued with a Cloudflare DNS-01 challenge, so automatic TLS needs the hostname’s zone on Cloudflare.

You do not need an SSH key. Storage servers are managed through a scoped Admin Proxy on each server. SSH is a HIGH RISK break-glass option that is off by default (Settings → General & Access); turn it on only for rescue work.

Verify ionCube first

Run php -m | grep -i ionCube with the PHP binary your WHMCS uses: /opt/plesk/php/8.3/bin/php on Plesk, /opt/cpanel/ea-php83/root/usr/bin/php on cPanel, or /usr/bin/php (whatever which php returns) on a plain Linux server. No output means the loader is missing — enable it under Tools & Settings → PHP Settings on Plesk or in WHM’s PHP extension settings on cPanel, or install the loader from ioncube.com and add its zend_extension line to php.ini.

2. Upload the files

Extract the release archive into the WHMCS root. From the WHMCS directory:

cd /path/to/whmcs
unzip /tmp/impulseobjects-<version>.zip

You should end up with this layout:

whmcs/
├── modules/
│   ├── servers/impulseobjects/        ← Server module
│   └── addons/impulseobjects_addon/   ← Admin UI
└── includes/hooks/
    ├── impulseobjects_hooks.php
    ├── impulseobjects_overage.php
    └── impulseobjects_usage_sync.php

Make sure the WHMCS web user can read everything — on Plesk that’s the subscription owner; on cPanel it’s the cPanel user; on a vanilla LAMP it’s typically www-data:

chown -R www-data:www-data \
  modules/servers/impulseobjects \
  modules/addons/impulseobjects_addon \
  includes/hooks/impulseobjects_*.php

Keep modules/servers/impulseobjects/vendor/ intact — it bundles the S3 SDK the module uses.

3. Activate the addon

1. Log in to WHMCS Admin.
2. Go to System Settings → Addon Modules.
3. Find ImpulseObjects in the list and click Activate.
4. Set Access Control → Full Administrator (or whichever admin role(s) should see the addon).
5. Click Save Changes.

What activation does

Activation creates every mod_impulseobjects_* table, seeds three example plans flagged “(Example — configure before selling)”, seeds default settings, installs the customer email templates that aren’t already present (your edits are never overwritten), and registers the module manifest with ImpulseCore. ImpulseCore finds the module’s security classes on its own, so the Security & Maintenance pipeline picks the module up on its next cron run.

4. Choose a tier

There is no tier to pick at install time. Without a license key, the install runs as Standard: one RustFS storage server, full provisioning, customer dashboard, billing and lifecycle — no replication, no migration, no public buckets or custom domains, no second server. Adding an IOBJ- license key unlocks the Licensed tier: unlimited servers across regions and providers, cross-region replication, public buckets with CORS and Cloudflare CDN, cloud data migration, and custom domains with Cloudflare for SaaS. See Standard vs Licensed features.

5. Enter your license key

Skip this step on the Standard tier. Licensing is handled by ImpulseCore:

1. Open Addons → ImpulseCore → Modules & Licensing → Licenses.
2. Paste your license key (starts with IOBJ-) into the ImpulseObjects row.
3. Click Save. ImpulseCore validates the key against the licensing server and records your WHMCS install’s domain the first time it validates — you don’t enter the domain anywhere.
4. The row shows the license as active, with the registered domain. In ImpulseObjects, Diagnostics → License shows the same status, tier and unlocked features, with a link back to ImpulseCore.

A successful check is cached for 24 hours. If the licensing server can’t be reached, licensed features keep working for a 7-day grace period, so a network blip never disrupts billing or customer access.

6. Walk the Setup Checklist

Back on the Dashboard tab, the First-Time Setup checklist detects what’s configured and what’s missing. Each item links straight to the right form. Work through them in order:

• License key (Licensed tier only)
• Background automation — ImpulseObjects’ tasks run on ImpulseCore’s cron runner. Install the crontab line shown under ImpulseCore → Operations → Cron → Automation & Setup (it runs modules/addons/impulsecore/cron/runner.php every 5 minutes with the PHP binary from step 1). Without it, ImpulseCore still runs the tasks whenever WHMCS’s own cron fires.
• WHMCS server IPs (baked into each storage server’s firewall so only WHMCS can reach its Admin Proxy)
• Break-glass SSH (optional — off by default)
• VPS provider API key (so it can create and destroy servers)
• DNS provider (so per-server hostnames and Let’s Encrypt certificates can issue)
• At least one active storage server
• At least one configured (non-example) plan
• Optional: Cloudflare for SaaS — needed for public buckets, custom domains and CDN

Don’t proceed to adding a server until the WHMCS IP, VPS provider and DNS items are green.