PUQ Mautic

WEB Hosting WHMCS module

WHMCS module for automated web hosting and email hosting account provisioning. Includes addon module for centralized management and cron orchestration.

Description

PUQ Web Hosting module WHMCS

Order now | Download | Community

What this module does

PUQ Web Hosting is a WHMCS module that fully automates the selling, provisioning, billing and day‑to‑day management of web hosting and email hosting accounts on HestiaCP servers (with PowerDNS as an additional DNS backend).

From a single WHMCS order the module can create everything a customer needs — a website, databases, FTP accounts, mailboxes, DNS records and an automatic Let's Encrypt certificate — and then expose a clean, self‑service control panel inside the WHMCS client area. Your staff get a powerful admin panel embedded directly in the WHMCS service page, plus a central addon dashboard for your whole server fleet.

The module is built around three ideas that the rest of this documentation explains in detail:

Two parts: server module + addon module

The product ships as two WHMCS modules that work together:

Module Role
Server module (puqWebHosting) The product engine: provisioning, the WHMCS client‑area control panel, and the admin service panel embedded in each service page.
Addon module (puq_web_hosting) The control centre: a fleet dashboard, the Infrastructure pages (web / mail / DNS servers, server groups, DNS zones & templates), module Settings, the task queue and operation logs, and the cron orchestration that drives every deployment.

The addon module is required — it owns the database schema, the task queue and the cron runner that the server module relies on.

Addon dashboard

At a glance

System Requirements

Requirement Supported
WHMCS 8.x or 9.x
PHP 7.4, 8.1 or 8.2 (use the module build that matches your WHMCS host's PHP)
ionCube Loader enabled, matching the host PHP version
HestiaCP reachable over SSH (panel HTTP API not required)
PowerDNS optional — additional DNS backend

The module ships as per‑PHP‑version builds (7.4 / 8.1 / 8.2). WHMCS 8 runs on PHP 7.4, 8.1 or 8.2; WHMCS 9 runs on PHP 8.2; and on any host with PHP 8.3 or newer you use the 8.2 build. Full guidance is in Installation & Configuration → Requirements & Installation.

The pages that follow walk through installation, building your server infrastructure, creating products, and the full admin and client experience — with a dedicated deep‑dive on server segmentation and on Vanity mode.

Changelog

v1.0 — first release

Full HestiaCP web + email hosting automation for WHMCS.

Compatibility — WHMCS 8.x and 9.x. Distributed as ionCube‑encoded builds for PHP 7.4, 8.1 and 8.2: WHMCS 8 → PHP 7.4 / 8.1 / 8.2, WHMCS 9 → PHP 8.2, and on PHP 8.3+ use the 8.2 build.

Provisioning & infrastructure

Deployment modes

Client area

Admin

Automation

Installation & Configuration

Get the module running end‑to‑end: install both parts, build your server infrastructure, group your nodes, and create your first product. Start here, then read Deployment & Segmentation to plan how your fleet scales.

Installation & Configuration

Requirements & Installation

PUQ Web Hosting module WHMCS

Order now | Download | Community

Requirements

PHP & WHMCS compatibility

The module is distributed as ionCube‑encoded builds, one per PHP version: 7.4, 8.1 and 8.2. Always install the build that matches the PHP version your WHMCS host runs under — not the PHP versions you offer to hosting customers (those are independent and managed on each Hestia web server).

WHMCS version PHP it runs on Module build to install
WHMCS 8.x 7.4, 8.1 or 8.2 the 7.4 / 8.1 / 8.2 build matching your PHP
WHMCS 9.x 8.2 the 8.2 build
any host on PHP 8.3 / 8.4 or newer 8.3+ the 8.2 build

How to choose, in plain terms:

  1. Check the PHP version your WHMCS server runs (WHMCS → Utilities → System → PHP Info, or php -v on the host).
  2. On WHMCS 8 you may run PHP 7.4, 8.1 or 8.2 — download the build with the same number.
  3. On WHMCS 9 the host runs PHP 8.2 — use the 8.2 build.
  4. If your host runs a PHP version newer than 8.2 (8.3, 8.4, …), use the 8.2 build — it is the latest supported and is compatible with newer PHP runtimes.

Downloads for every supported PHP version are on the Download page. After any module update, re‑run the schema check (below).

Install both modules

The product is two WHMCS modules — install both:

Upload to Module
modules/servers/puqWebHosting/ the server module
modules/addons/puq_web_hosting/ the addon module

Then in WHMCS go to Setup → Addon Modules, find PUQ Web Hosting, and Activate it (grant access to the admin roles that should manage hosting). Activating the addon creates the database tables the server module needs.

First run: check the schema & find the panels

After activation you have a new PUQ Web Hosting admin page (via Addons). Its top navigation gives you everything: Home, Services, Statistics, Infrastructure, Logs, Settings, Help.

Addon nav + Settings menu

Open Settings → Maintenance and click Run schema check once. It scans every module table and brings it in sync with the current code — creating missing tables, adding missing columns and dropping columns that no longer exist. You should run this after every module update.

Maintenance — schema check

The same tab has a “delete all tables on deactivate” toggle — leave it off unless you are fully uninstalling, so your data survives an accidental deactivation.

What's next

With both modules installed you build your service from the bottom up:

  1. Add your servers and tag their capabilities — see Add web / mail / DNS servers.
  2. Group them and apply role‑targeted configuration — see Server groups.
  3. Create a product pointed at a group — see Create a product.

The module Settings (timeouts, retry policy, SSL cadence, DNS/SOA defaults, integrations, notifications) are covered in Addon Module → Settings; the defaults are sensible, so you can come back to them later.

Installation & Configuration

Add Web / Mail / DNS Servers

PUQ Web Hosting module WHMCS

Order now | Download | Community

Your fleet is managed under Infrastructure. The same physical servers appear under Web Servers, Mail Servers and DNS Servers filtered by the capabilities you give them.

Web servers list

Each row shows live CPU / RAM / Disk / Load, the Hestia version & OS, the panel‑OK indicator, the group, the capacity used/max and the row actions. A green OK means the SSH/panel probe succeeded.

Add a server

Click Add Web Server (or Mail/DNS — they open the same editor) and fill in the connection details:

Edit server — capabilities

Field Notes
Capabilities Tick Web, Mail, DNS — one, two or all three. This decides which pools the node appears in and which roles can be placed on it.
Driver HestiaCP (or PowerDNS for a DNS‑only node).
Status active to use it.
Hostname / IP / SSH port The SSH endpoint.
SSH auth Password or private key.

Lower in the editor you set per‑server defaults:

Edit server — package + template

Use Test connection before saving; the row will then show OK and start reporting live stats.

Capabilities = your topology

How you tick capabilities is your segmentation plan:

Mail servers list

DNS servers are a special case — they are independent and attached to groups (one DNS server can serve many groups). The DNS Servers page reminds you of this:

DNS servers list

See Deployment & Segmentation → Server segmentation for the full reasoning and the role‑targeted configuration that goes with these capabilities. The next page groups these servers so a product can sell from them.

Installation & Configuration

Server Groups

PUQ Web Hosting module WHMCS

Order now | Download | Community

A server group bundles a set of nodes together. A WHMCS product points at one group, and the module places each service's roles on the group's capable nodes. Groups are managed under Infrastructure → Server Groups.

Server groups list

Click Open on a row to manage the group. The H: badge shows how many hestia.conf keys the group manages.

Group purpose: Standard vs Vanity

The first decision, on the group's General tab, is Group purpose:

Group purpose — Standard vs Vanity

Attach DNS servers (the cluster)

On the group's DNS servers tab, tick the nameservers this group replicates zones to. DNS servers are independent and shared — one server can back many groups. Every zone for the group is pushed to every attached DNS node (active‑active).

Group — DNS servers

This tab is also where you set the group's default DNS zone template and SOA defaults for new zones.

Apply configuration

The group's Actions tab lets you push the managed Hestia configuration and standard files to the members, per role (all / web‑only / mail‑only / DNS‑only). The detail of role‑targeted config (hestia.conf management, drift, standard files) is covered in Addon Module → Server‑group editor and Deployment & Segmentation → Server segmentation.

A minimal setup is one group containing your nodes. As you grow, use multiple groups to separate locations/tiers or to offer different SLAs, and a separate Vanity group for your name‑selling offers.

Installation & Configuration

Create a Product

PUQ Web Hosting module WHMCS

Order now | Download | Community

Create a product in WHMCS (Setup → Products/Services), then on Module Settings choose PUQ Web Hosting and point Server Group at the group you built.

Module Settings — General

The configuration lives on a row of sub‑tabs: General · Web limits · Mail limits · DNS limits · Client · Email · Config options (in Vanity mode the limits tabs collapse to a single Vanity limits tab).

General — roles & deployment mode

On General you pick which roles the package includes (tick Web / Mail / DNS) and the Deployment mode (Split / Unified / Vanity — see Deployment & Segmentation → Deployment models).

General — deployment mode + roles

Limits — what the customer gets

The Web / Mail / DNS limits tabs define the Hestia package quotas and the module‑local caps for each ticked role. Every field maps to a Configurable Option override key (e.g. web_disk_quota) so you can offer upgradeable tiers.

Setting a role's disk quota to 0 disables that role for the product (the same as un‑ticking it on General).

Client — what the customer can do

The Client tab is a set of toggles controlling which client‑area pages/actions are visible — create/delete mailbox, change password, create database/FTP, edit DNS, install SSL, manage cron, web settings, backups, view logs, client‑side redeploy, file‑manager & webmail SSO. Untick to hide.

Client permissions

Email — lifecycle emails

The Email tab maps a WHMCS email template to each module event (Account Ready, Deploy Failed, Mailbox/Database/FTP/Backup Created, SSL Installed, SSL Expiring 14/3, Quota Warning 80/Exceeded, DNS Zone Deployed, Backup Restored/Failed). Leave an event blank to disable it.

Email events

Config options — wire up WHMCS

Finally, open Config options and click Create / sync missing. The module reads its per‑order limits from WHMCS Configurable Options; this button creates exactly the ones the product needs (it's safe to run repeatedly — existing options and values are never changed).

Config options — missing

After syncing they show COMPLETE:

Config options — complete

Tune the prices afterwards under WHMCS Configurable Options. The product is now ready to order.

For a Vanity product the limits and config‑options are different (Website/Mailbox quota + the vanity_domain option + vanity_name custom field). See Vanity Mode → The vanity product.

Addon Module

The PUQ Web Hosting addon is the control centre for your whole fleet: a dashboard, the Infrastructure pages (web / mail / DNS servers, server groups, DNS zones & templates), per‑node Server actions, module Settings, the task queue and operation logs, and the Vanity widget generator. The addon is required — it owns the schema, the queue and the cron runner.

Addon Module

Dashboard

PUQ Web Hosting module WHMCS

Order now | Download | Community

The addon Home page is a one‑glance view of your whole hosting operation.

Addon dashboard

Cards

Card Shows
Services Total provisioned services (View → the Services list).
Servers Total servers (Manage → Infrastructure).
Task Queue Tasks currently in the queue (View → Logs → Task Queue).
DNS Zones Total logical DNS zones (Manage).
Server Groups Shortcut to group management.
Settings Shortcut to cron / retry policy / tables.

Panels

Navigation

The top bar is the same everywhere:

Addon Module

Infrastructure: Servers

PUQ Web Hosting module WHMCS

Order now | Download | Community

Infrastructure is where you register and monitor every node. The same servers are presented under three filtered lists — Web, Mail and DNS — based on their capabilities.

Web servers

Each row carries live CPU / RAM / Disk / Load bars, the panel‑OK probe, the Hestia version & OS, the group, the capacity used/max, and per‑row actions (open Server Actions, refresh status, sync, edit, delete).

Capabilities decide the pools

A node's Web / Mail / DNS capability flags decide which list it appears in and which roles can be placed on it. See Add web / mail / DNS servers for the editor and Deployment & Segmentation → Server segmentation for how to design your topology.

Mail servers

DNS servers are independent and attached to groups (one server can serve many groups):

DNS servers

Open a server → Server Actions

Clicking a server's open/manage action takes you to the Server Actions page for that node — a full per‑node management console (live config, group‑config drift, PHP versions, file‑manager installs, system services, Hestia users & packages, IPs, maintenance, logs). That page is documented next.

Addon Module

Server Actions (per node)

PUQ Web Hosting module WHMCS

Order now | Download | Community

Opening a server gives you a per‑node console with live stat cards and a tab bar: System config · Group config · PHP · File Manager · Services · Users · Packages · IPs · Maintenance · Log.

Server Actions — system config

System config

A live, read‑only dump of the node's hestia.conf key/value pairs — handy for confirming what a server is actually running.

Group config (drift)

Compares the node's live config against what its group expects, key by key, with a MATCH / drift status, and lets you Apply group config to push the managed values:

Server Actions — group config drift

This is the per‑node view of the group's managed hestia.conf (see Server‑group editor).

PHP

Install / remove PHP versions (5.6 – 8.4) with their FPM service, IonCube, and the Ondrej/Sury repositories — with an online gate and a recent‑tasks panel.

Server Actions — PHP

File Manager

Install and manage the two built‑in file managers per node — FileGator (Vue SPA, drag‑and‑drop) and net2ftp (native chmod UI). Each shows its installed version & URL, a custom download URL, and Reinstall / Uninstall / Refresh.

Server Actions — file managers

Services / Users / Packages

Maintenance & Log

Addon Module

Server‑Group Editor

PUQ Web Hosting module WHMCS

Order now | Download | Community

Open a group (Infrastructure → Server Groups → Open) to manage its members, its centrally‑managed hestia.conf, its DNS cluster and (for vanity groups) its sellable domains. A standard group has these tabs: Actions · General · All‑servers config · Web config · Mail config · DNS config · Variables · Standard files · DNS servers.

Actions — bulk apply per role

Group — Actions

The Actions tab lists the members with their Type and Status, and pushes config/files per role: Apply Hestia config to all / web only / mail only / DNS only, Apply standard files to web, Refresh status. Applying enqueues one task per matching active node.

General — name & purpose

Name, description and the Group purpose (Standard vs Vanity). See Server Groups and the Vanity Mode chapter.

Managed hestia.conf (role‑targeted)

The module can centrally manage Hestia config keys and keep every node in sync (with drift detection on the node's Group config tab). The keys are split by role so they only ever land on the right tier:

Empty fields are not managed — the module only pushes the keys you fill in.

Variables

Group‑wide {name} key/value pairs substituted into DNS zone template records (e.g. ns1, ns2). Empty values fall through to the product's WHMCS configoptions; if both are empty the worker drops template records that reference the variable.

Variables

Standard files (rebranding)

Rebrandable Hestia skeleton files for web nodes — error pages (403/404/410/5xx), the default user index.html / robots.txt, the suspended‑account page, and the unassigned‑IP vhost. Each can be Overridden (your content) or Pulled from a server, with default/overridden badges.

Standard files

DNS servers (the cluster)

Attach independent DNS servers to the group (active‑active replication) and set the group's default zone template + SOA defaults.

Group — DNS servers

A Vanity group shows only General / Variables / DNS servers / Vanity domains — the hosting‑config tabs are hidden. See Vanity Mode → Setting up the vanity group.

Addon Module

DNS Zones & Templates

PUQ Web Hosting module WHMCS

Order now | Download | Community

DNS Zones

Infrastructure → DNS Zones lists every logical zone (one row per zone). The Cluster column shows the per‑DNS‑server deploy state, so you can see at a glance that a zone is live on every nameserver. A Redeploy action re‑pushes the zone.

DNS zones

Because zones are logical and replicated, the module gives you an active‑active nameserver cluster — the same zone is served identically by every attached DNS node.

DNS Zone Templates

Infrastructure → DNS Zone Templates holds the record sets used when a new zone is created. You can mark one Default, add more, or Seed from file.

DNS zone templates

Open a template to edit its records. Placeholders are substituted at provisioning time — {domain}, {server_ip}, {mail_server_ip}, {mail_server_hostname}, {ns1}…{ns8}, {domainkey} (DKIM), {client_id}, {service_id}, {year}, {unixtime}.

DNS zone template editor

The shipped Default template is a complete, modern web + mail record set:

A record that references an empty placeholder (e.g. {domainkey} when DKIM isn't ready) is simply skipped — so partial state never produces broken records.

Addon Module

Settings

PUQ Web Hosting module WHMCS

Order now | Download | Community

Settings has three pages — General, Cron and Vanity widget. The General page is organised into tabs. The defaults are sensible; tune them as you scale.

General

The General tab itself holds API timeouts and the task retry policy (max attempts, back‑off minutes, batch size per cron run, finished‑task retention):

Settings — General content

The remaining tabs:

Tab Controls
Provisioning Defaults for new users — FTP root path, login shell (nologin for managed hosting), Hestia admin/SSH usernames. Provisioning
DNS Record TTL (default/min/max, max value length) and module‑wide SOA defaults. DNS
SSL Auto‑SSL cadence (fast‑mode count/interval, normal interval, active‑cert interval) and the Let's Encrypt rate‑limit guard. SSL
Mail & Security Webmail / phpMyAdmin URL patterns, DKIM key size, max auto‑reply length, minimum password length. Mail & Security
Logging & Performance Log download size cap, tail line limits, mail‑log filter window, SSH heavy‑bash & apt‑lock timeouts. Logging
Integrations Overridable upstream URLs — FileGator/net2ftp zips, FTP host fallback, PHP repos (Ondrej PPA, Sury), GPG keyserver, IonCube installer. Integrations
Notifications Failure‑ticket toggle (department + priority), client‑area toast/poll durations, analytics lookback windows. Notifications
Maintenance The schema Check & repair tool + the deactivation data‑retention toggle. Maintenance

Cron

The Cron page picks the cron mode (WHMCS vs Standalone), shows the crontab line to install, and lists every scheduled task with its enable/interval/last‑run/status, plus concurrency limits.

Settings — Cron

Vanity widget

Generates the standalone "claim your name" shop widget — see Vanity Mode → The vanity shop widget.

Addon Module

Task Queue & Logs

PUQ Web Hosting module WHMCS

Order now | Download | Community

Everything the module does runs through a task queue processed by the cron runner. The Logs menu exposes both the live queue and a persistent operation history.

Task Queue

Logs → Task Queue is the live worker view: each task's ID, service, target, action (e.g. server.collectStatus, web.addFtp), status, attempts, priority, schedule and error.

Task Queue

Bulk controls let you tidy up: Delete success / error / cancelled, Clean all completed, and Force‑fail stuck (for tasks wedged by an unreachable node).

Operation Log

Logs → Operation Log is a persistent, per‑operation timeline (status collection, deploys, etc.) — useful for auditing what happened and when.

Operation Log

Click a row to open the full detail — the operation, target, step, status and the complete message body:

Operation Log detail

The retry policy (how many times and how fast failed tasks retry) and the optional support ticket on terminal failure are configured in Settings → General / Notifications, and explained in Cron & Automation → Task queue, retries & tickets.

Addon Module

Vanity Widget

PUQ Web Hosting module WHMCS

Order now | Download | Community

Settings → Vanity widget generates a standalone "claim your name" landing page (two files) that you can drop on any marketing domain to sell vanity slots outside the WHMCS portal.

Vanity widget config

In short, you: (1) get/regenerate a shared API key, (2) pick the vanity product, (3) copy the config block into proxy.php, (4) choose the cart behaviour, then download proxy.php + index.html and upload both to each marketing domain's web root.

Vanity widget download

The browser only ever talks to the widget's own proxy.php (which holds the key and caches answers) — the key never reaches the visitor.

The full setup, the buyer's flow and the security model are documented in the dedicated Vanity Mode → The vanity shop widget page.

Admin Area

How your staff configure products and manage individual services from inside WHMCS — the product Module Settings, and the powerful admin service panel embedded in every service page (overview, per‑resource tabs, credentials, deploy timeline, verify & repair, factory reset).

Admin Area

Product Configuration (reference)

PUQ Web Hosting module WHMCS

Order now | Download | Community

A product's behaviour is defined on its WHMCS Module Settings tabs. Installation & Configuration → Create a product walks the happy path; this page is a reference to the moving parts and how they fit together.

Module Settings

How the pieces connect

General tab            →  roles (Web/Mail/DNS) + Deployment mode (Split/Unified/Vanity)
Web/Mail/DNS limits    →  Hestia package quotas + module caps, each keyed to a Configurable Option
Client tab             →  which client-area pages/actions are visible
Email tab              →  WHMCS email template per module event
Config options tab     →  Create/sync the WHMCS Configurable Options + the vanity_name Custom Field

At order time the module reads each customer's chosen limits from the WHMCS Configurable Options (whose keys it created), overlays them on the product defaults, and stores the resolved set on the service. You can inspect that resolved set on the admin service panel (the Resolved limits table).

Deployment mode decides the tab set

Deployment mode

See Deployment & Segmentation → Deployment models for what each mode does, and Vanity Mode → The vanity product for the vanity specifics.

Limits → Configurable Options

Every limit field names its override key (e.g. web_disk_quota, mail_accounts, dns_records). The Config options tab turns those keys into real WHMCS Configurable Options in one click, so customers can pick tiers and you can price upgrades.

Config options — complete

Tab Key examples
Web limits web_disk_quota, web_bandwidth, web_databases, web_ftp_accounts, web_cron_jobs, web_backups
Mail limits mail_disk_quota, mail_accounts, mail_backups
DNS limits dns_records
Vanity limits vanity_site_disk_quota, vanity_mail_quota, vanity_domain

Client permissions & emails

The Client tab hides/shows client‑area features per product; the Email tab maps each lifecycle event to a WHMCS email template. Both are covered with screenshots in Create a product.

Re‑running Create / sync missing is always safe — it only adds what's missing and never rewrites existing options or values. Run it again after enabling a new role or switching deployment mode.

Admin Area

Service Management

PUQ Web Hosting module WHMCS

Order now | Download | Community

Every hosting service is managed from inside its WHMCS service page. At the top you get the standard WHMCS editor with the Configurable‑Option dropdowns and the Module Commands (Create / Suspend / Unsuspend / Terminate / Change Package):

WHMCS service — module commands

Below that, the module embeds a full admin service panel — your staff's day‑to‑day console for the service.

Overview

The Overview shows two role cards. Web & DNS lists the web Hestia user, the DNS user and zones (with deploy badges) and the website usage gauges; Mail lists the mail user, mail/webmail links and the mailbox gauges. Both show the SSL state. Top buttons: Edit DB row · Reveal credentials · Redeploy service · Factory reset · Change domain.

Admin service panel — overview

Per‑resource tabs

The tab bar mirrors the client area but read/write for staff:

Tab What you do
Web settings PHP version, HTTPS redirect, proxy extensions. Web settings
SSL Auto‑SSL state per role + custom‑cert upload; Issue/Renew now. SSL
FTP FTP accounts (full prefixed username). FTP
Databases Databases (name/user, engine, charset, size). Databases
DNS The service's zone records (type/name/value/pri/TTL) with per‑server deploy state. DNS
Mailboxes The service's mailboxes (email, quota, status). Mailboxes
Cron Cron jobs (schedule, command, status). Cron
Backups Web + Mail backup lists with Backup now / Sync from server / Restore / Delete / Check restore. Backups
Logs Real Hestia log tail (Apache/Exim/Dovecot), grep‑filtered to the domain. Logs

Deploy & Tasks

The Deploy tab shows live deploy status, a full event timeline and Redeploy (hard reset). The Tasks tab lists this service's tasks (action, target, server, status, attempts, timestamps); each opens a detail modal with the streamed SSH log.

Deploy timeline Tasks tab Task detail

Limits, usage & power tools

The Overview tab also carries the Resolved limits and live Usage tables, with Force usage sync and a Verify & Repair panel:

Resolved limits + usage

Cross‑service list

The addon Services page is the fleet‑wide view — search/filter by deploy or DNS state, see each service's Mode (Split/Vanity) and DNS ownership, open the admin panel, redeploy, unlock or force‑delete, and run Verify (probe panels + DNS and repair).

Services list

Client Area

The self‑service control panel your customers get inside WHMCS: a live dashboard plus pages for web settings, FTP, databases, DNS, mailboxes, SSL, cron, backups and logs. Every page is permission‑gated by the product's Client tab, and every action runs through the same asynchronous task queue (so the customer sees live "queued → creating → active" status).

Client Area

Client Dashboard

PUQ Web Hosting module WHMCS

Order now | Download | Community

When a customer opens an active hosting service they land on a two‑column Web | Mail dashboard that summarises everything at a glance.

Client dashboard — overview

Layout

Quick actions

The usage bars are read from the local database (kept fresh by the usage‑sync cron); Sync now enqueues an on‑demand recompute if the customer wants the latest numbers immediately.

Resource usage

Navigation

A sidebar lists every enabled feature — Web settings, FTP, Databases, DNS, Mailboxes, SSL, Backups, Cron, Logs. Which entries appear depends on the product's Client permissions (a Mail‑only product hides web pages, a Vanity product shows the simplified Website/Email set, etc.).

Sidebar navigation

During deployment the customer sees a live progress splash instead of the dashboard; on failure, an error screen with a Try again button (if the product allows redeploy). See Deployment & Segmentation → How deployment works.

Client Area

Web Settings

PUQ Web Hosting module WHMCS

Order now | Download | Community

The Web settings page lets the customer self‑serve the three most common website tweaks without a ticket.

Web settings

Section What it does
PHP version Pick any PHP version installed on the web server (e.g. 7.4 → 8.3). Applies the matching Hestia web template.
HTTPS redirect Force http → https. Only selectable once SSL is active for the domain.
Proxy extensions Choose which static file extensions the front proxy serves directly (with Defaults and Disable shortcuts).

Each Apply is asynchronous: the request is queued, a spinner badge shows while the worker runs, and an error tooltip surfaces if Hestia rejects the change. The page mirrors the live state back from the server, so what you see is what's actually applied.

These controls appear only if the product's Client permissions enable hosting settings. On a Vanity service this page is simplified to the relevant subset.

Client Area

FTP Accounts

PUQ Web Hosting module WHMCS

Order now | Download | Community

Customers manage their own FTP accounts here, up to the product's FTP‑account limit.

Create FTP account

Creating an account

Enter a suffix and a password (or generate one) and submit. The real Hestia username is the main web user plus your suffix (<webuser>_<suffix>) — the page shows the full username so the customer knows exactly what to type into their FTP client. The home directory and shell are set by the Provisioning defaults (typically nologin, so FTP/SFTP only).

The action is queued, so the new row appears with a Queued badge first:

FTP account queued

…and flips to Active once the worker has created it on the server:

FTP account active

The suffix length is budget‑aware: the module reserves enough characters so the combined username stays within Hestia's limit. If a suffix would overflow, it's rejected before submission.

Open the file manager (FileGator / net2ftp) from the dashboard quick actions for in‑browser file access without a desktop FTP client.

Client Area

Databases

PUQ Web Hosting module WHMCS

Order now | Download | Community

The Databases page lets customers create and manage MySQL/MariaDB databases up to the product's database limit.

Databases

Each database is created with its own dedicated user. As with FTP, the database and user names are prefixed with the main web user (<webuser>_<suffix>), and the page shows the full names plus the live size of each database.

Database size is read by the usage‑sync cron and counts toward nothing by itself, but the number of databases is capped by the product limit / Configurable Option.

Client Area

DNS Records

PUQ Web Hosting module WHMCS

Order now | Download | Community

If the product includes the DNS role, customers manage their zone's records here, up to the product's record limit.

DNS records

Editing records

Add, edit or delete A / AAAA / CNAME / MX / TXT / SRV records. The editor validates the type/value and shows the TTL within the configured min/max bounds.

Edit DNS record

Every change is fanned out to all DNS servers attached to the service's group (the active‑active cluster), so records stay identical on every nameserver. See Deployment & Segmentation → Server segmentation for how the DNS pool works.

External DNS

If the service was set up with external DNS (the customer keeps DNS elsewhere), this page instead shows the records they need to publish at their own provider, plus a Verify check that probes the live nameservers and confirms the records resolve:

Verify DNS

Client Area

Mailboxes

PUQ Web Hosting module WHMCS

Order now | Download | Community

On a service with the Mail role, customers manage their mailboxes here, up to the product's mailbox limit.

Mailboxes

Per‑mailbox settings

Create a mailbox with an address and password, then open it to manage:

Edit mailbox

Webmail opens the configured webmail URL for the mail server.

On a Vanity service this is the single name@<your-domain> mailbox, presented as a simplified Email page — see Vanity Mode → Order & client experience.

Client Area

SSL

PUQ Web Hosting module WHMCS

Order now | Download | Community

The SSL page shows certificate status and lets customers upload a custom certificate.

Custom SSL

Automatic SSL

In the common case there's nothing to do: the module issues and renews Let's Encrypt certificates automatically for the website (and for mail. / webmail. on the mail role). The page shows the current state and expiry; the cadence and rate‑limit guards are described in Cron & Automation → SSL automation.

Custom certificate

Customers who already have a certificate (e.g. a wildcard or EV cert) can upload it here — certificate, private key and optional CA bundle:

Upload custom SSL

Uploading a custom certificate installs it on the domain and suspends auto‑SSL for that role so it won't be overwritten. A daily cron checks custom‑cert expiry and notifies before it lapses.

Client Area

Backups, Cron & Logs

PUQ Web Hosting module WHMCS

Order now | Download | Community

Three more self‑service pages round out the client area.

Backups

Customers can take and restore their own snapshots, up to the product's web/mail backup quota.

Backups

Web and mail snapshots are listed and quota‑counted separately.

Cron

Customers manage scheduled jobs for their website, up to the cron‑job limit.

Cron

Add a job with a schedule and command; it's queued (Queued badge) and goes Active once installed on the server:

Cron queued Cron active

Logs

The Logs page tails the website's real server logs (Apache/Exim/Dovecot as applicable), grep‑filtered to the customer's own domain, with a size‑capped download.

Logs

Every one of these pages is gated by the product's Client permissions, so you can expose exactly the feature set each plan should have.

Deployment & Segmentation

This chapter explains the heart of the module: how a service is deployed, why you split your infrastructure across servers, and the three deployment models (Split, Unified, Vanity) you can sell. Read it before building products — the choices here decide how your hosting scales and how your costs and isolation trade off.

Deployment & Segmentation

Deployment Models (Split · Unified · Vanity)

PUQ Web Hosting module WHMCS

Order now | Download | Community

Every product you sell has a Deployment mode set on the product's Module Settings → General tab. It decides how many HestiaCP accounts back each service and where the web, mail and DNS roles live. This is the single most important product decision.

Deployment mode selector

The three modes

Mode Hestia accounts per service Best for
Split A separate Hestia user per role — one web user, one mail user, one DNS user (each can live on a different server). Classic shared/business hosting where you want maximum isolation and the freedom to put web, mail and DNS on different, independently‑scaled servers.
Unified One Hestia user holds web and mail (and local DNS) for the service. Simpler, denser, cheaper hosting where web and mail naturally live together on one node.
Vanity A per‑service web user for one subdomain + one mailbox on your shared provider mail account. Selling name.yourdomain.com websites and name@yourdomain.com mailboxes on a domain you own — see the dedicated Vanity Mode chapter.

Split deployment

In Split mode the module provisions up to three independent HestiaCP users for the service — for example customer-com-web, customer-com-mail and customer-com-dns. Each is placed on a server that has the matching capability, so the website, the mailboxes and the DNS zone can sit on completely different machines.

The admin service panel shows this clearly — a Web & DNS card and a separate Mail card, each with its own Hestia user, server and certificate:

Split service — web/mail/dns identities

Split is the mode to choose when you want to segment your fleet by role (the next page) and keep mailboxes off your web servers.

Unified deployment

In Unified mode a single Hestia user owns the website and the mailboxes, so web and mail are always co‑located. There is no separate mail user to manage. Unified products use a single combined account package and a single set of backups (role = all). Choose Unified when you run general‑purpose nodes that do both jobs and you want fewer accounts to manage.

Vanity deployment

Vanity is a different business model rather than a different server layout: you own a domain (e.g. benchwords.com) and sell slots on it. Each order becomes name.benchwords.com (a normal per‑service web account) plus name@benchwords.com (one mailbox on your shared provider mail user). The parent domain, its DNS zone and the provider mail account are never modified per order — the model is destructive‑safe by design.

Vanity service — website + shared mailbox

Vanity has its own chapter because the setup (sellable parent domains, reserved names, the order flow and a drop‑anywhere shop widget) is substantial — see Vanity Mode.

Which roles does a product include?

Independently of the mode, the product's General tab lets you tick which roles the package includes — Web, Mail, DNS. Unticking a role (or setting its disk quota to 0 in the limits tab) simply omits it. For example, a "mail‑only" product ticks Mail and leaves Web off; a "website‑only" product ticks Web and DNS.

The limits for each ticked role are configured on the matching Web limits / Mail limits / DNS limits tab (or the single Vanity limits tab in Vanity mode) — see Installation & Configuration → Create a product.

Rule of thumb: Split = isolation + segmentation; Unified = density + simplicity; Vanity = a productised "personal site + email" offer on your own domain. You can sell all three side‑by‑side — they coexist on the same servers.

Deployment & Segmentation

Server Segmentation (Web / Mail / DNS tiers)

PUQ Web Hosting module WHMCS

Order now | Download | Community

One server or many?

You can run the whole module on a single HestiaCP node that does everything. That is perfect for getting started, for small offers, and for testing.

But the module is designed so you can segment your fleet as you grow: put websites on one set of servers, mailboxes on dedicated mail (MX) servers, and DNS on separate nameservers. Each role then scales on its own hardware, and a busy mail queue or a heavy website can't starve the others.

The mechanism that makes this possible is server capabilities + server groups.

Capabilities — what a node is allowed to host

Each server you add (Infrastructure → Web / Mail / DNS Servers) has three capability flags: Web, Mail, DNS. You tick them when you add or edit the node. A node can carry one role, two, or all three.

Server capabilities Web/Mail/DNS

This is how you decide your topology. Typical patterns:

Pattern Web nodes Mail nodes DNS nodes
All‑in‑one one node ticks Web + Mail + DNS (same node) (same node)
Web / mail split nodes tick Web only dedicated Mail nodes (your MX) nodes tick DNS only
Full three‑tier Web pool Mail pool Nameserver pool (e.g. ns1, ns2)

In the Infrastructure pages the same physical servers appear under Web Servers, Mail Servers and DNS Servers filtered by their capability — so a mail‑only node only shows up under Mail:

Web servers pool Mail servers pool DNS servers pool

When a Split service is provisioned, the module places each role on a least‑loaded active node that has the matching capability: the web user lands on a Web node, the mailbox on a Mail node, the DNS zone on the group's DNS nodes. That is the load balancing — it is by role and by capacity, automatically.

Server groups — the unit you sell from

A server group ties a set of nodes together and is what a product points at (the product's Server Group dropdown). Open a group to manage it.

Server group — bulk apply per role

The group's Actions tab shows the members with their Type (WEB / MAIL) and lets you push configuration to all servers, web servers only, mail servers only or DNS servers only. That last point is the key to safe segmentation: a web‑specific setting is never applied to a mail node and vice‑versa.

Role‑targeted configuration

The group editor has separate config tabs whose values are pushed only to nodes of that role during Apply Hestia config:

The worker filters every managed key by its category target, so "mail‑only keys never land on web servers and vice‑versa". This means you can, for instance, enable ClamAV/SpamAssassin only on your mail tier without touching the web tier.

DNS is active‑active across the tier

DNS servers are independent — you attach them to a group on the group's DNS servers tab, and one DNS server can serve many groups. When a zone is created it is replicated to every attached DNS node, so you get an active‑active nameserver cluster out of the box. The DNS Zones page shows the per‑server deploy state for each logical zone:

DNS zones — active-active cluster

Watching the balance

The addon Statistics page reports usage per domain, split into Web and Mail columns, so you can see at a glance how load is distributed and when a tier needs another node:

Statistics — web vs mail usage

The Home dashboard's Server capacity table lists each node by type with its capacity and last sync time — a quick health view of every tier.

Why segment? Mail and web have very different load profiles. Keeping them on separate, capability‑tagged tiers lets you scale each independently, isolate failures, and apply role‑specific tuning — while the module's per‑capability placement spreads new accounts across the least‑loaded node automatically.

Deployment & Segmentation

How Deployment Works

PUQ Web Hosting module WHMCS

Order now | Download | Community

Orders return instantly — work happens in the background

When a service is created (a WHMCS order goes active, an admin clicks Create, or the API is called) the module does not try to build everything inside the HTTP request. It writes a service record, returns success to WHMCS immediately, and lets the cron‑driven task queue do the real work.

This is what the customer sees right after ordering — a live deployment splash that polls for progress and refreshes itself:

Deploying — start

Each step is a queued task processed by the cron runner. As steps complete, the bar advances and the recent‑activity feed updates:

Deploying — mid progress

When the last step finishes the page flips to the live control panel:

Deploying — finished

This design makes provisioning resilient to slow panels, SSH timeouts, apt‑get locks and long operations — none of them block the order, and any failed step is simply retried.

The pipeline (Split example)

A Split service is built by a chain of idempotent tasks, roughly in this order:

  1. Create the web package + web user on a Web node.
  2. Add the web domain (and the web account's quota/PHP settings).
  3. Create the mail user + mail domain on a Mail node (with DKIM).
  4. Create the DNS user + zone and deploy the zone to every attached DNS node.
  5. Seed Auto‑SSL so Let's Encrypt issues as soon as DNS resolves.

Unified runs the same idea with one combined account; Vanity runs a trimmed chain (one web account, one mailbox on the shared mail user, one DNS record). Every task is idempotent — re‑running it is safe — so the chain can resume from wherever it stopped.

Watching and driving it from the admin panel

The admin service panel's Deploy tab shows the live deploy status and a full timeline of every task with its duration and result, plus a Redeploy (hard reset) button:

Admin deploy timeline

The Tasks tab lists this service's tasks (action, server, attempts, timestamps); each row opens a detail modal with the streamed SSH log:

Admin tasks tab

Retries, failures and tickets

A failed task is retried with exponential back‑off. Once all attempts are exhausted it is terminally failed, the service shows a deploy error, and — if you enabled it — the module can open a support ticket for your staff. The retry policy and the failure‑ticket behaviour are configured in addon Settings (see Cron & Automation → Task queue, retries & tickets).

Key takeaway: deployment is an asynchronous, idempotent, resumable pipeline. The order is accepted instantly, the queue does the work, failures self‑heal on retry, and both you and the customer get live progress.

Vanity Mode

Vanity mode is the module's signature feature. It turns one domain you own into thousands of sellable “personal site + email” products: a customer picks a name and instantly gets name.yourdomain.com as a website and name@yourdomain.com as an email address. This chapter covers the whole story — what it is and why it sells, how to set up a vanity server group and its sellable domains, how to build the vanity product, what the order and client experience look like, and the standalone shop widget you can drop on any marketing site. It is intentionally detailed: Vanity is a complete go‑to‑market in itself.

Vanity Mode

What Vanity Mode Is (and Why It Sells)

PUQ Web Hosting module WHMCS

Order now | Download | Community

The idea in one sentence

You own a memorable domain — say benchwords.com — and you rent out names on it. A customer who picks ruslan gets:

…provisioned in seconds, billed by WHMCS, and fully self‑service. One domain you already own becomes an unlimited catalogue of "personal site + email" products.

Why customers buy it

Registering a domain, configuring DNS, setting up mail and getting a website online is intimidating for most people. Vanity removes all of that: pick a name on a brand they already like, and they have a real site and a real inbox. It is the simplest possible hosting product to buy — which makes it the easiest to sell.

This is exactly what the customer ends up with — a clean two‑card dashboard, Website and Email, with nothing else to configure:

Vanity client dashboard

How it differs from normal hosting

A normal (Split/Unified) service gives the customer a whole domain and the full toolbox — DNS records, multiple mailboxes, SSL, backups, subdomains. A vanity slot is deliberately minimal:

Normal hosting Vanity slot
Domain the customer's own domain one name on your domain
Website full account a per‑service web account for name.yourdomain.com
Mailbox create/delete many exactly one fixed mailbox name@yourdomain.com
DNS full zone editor nothing to manage — one record on your zone
SSL / Backups / Subdomains customer‑managed handled for them (mail SSL lives on your provider domain)

The customer never sees DNS, SSL, backups or zone editing — those don't apply to a slot. The trimmed client menu reflects that.

The safety guarantee (read this)

Vanity mode is destructive‑safe by design. No matter what a customer does — order, change password, set forwards, cancel — the module only ever touches:

It never touches the parent mail domain, the DNS zone, or your provider Hestia user. One customer's actions can never affect another customer or your base domain. You will see this guarantee restated on the setup screen — it is a load‑bearing invariant of the whole model.

Two ways to sell it

  1. Inside WHMCS — a normal product with a live name‑availability check on the order form (covered in The vanity product and Order & client experience).
  2. Anywhere — a standalone shop widget (two small files) you drop on any marketing domain. It shows a "claim your name" landing page and sends buyers straight into your prefilled WHMCS cart (covered in The vanity shop widget).

Vanity shop widget landing

The next pages set it up end‑to‑end: first the server group + sellable domains, then the product, then the order/client experience, then the widget.

Vanity Mode

Setting Up the Vanity Group & Sellable Domains

PUQ Web Hosting module WHMCS

Order now | Download | Community

A vanity offer is built on a special server group whose purpose is Vanity. This page sets up that group and the parent domains you will sell names on.

Step 1 — Make a group a Vanity group

Create a server group (Infrastructure → Server Groups → Add Server Group), open it, and on the General tab set Group purpose to Vanity.

Vanity group — General + reserved names

Switching to Vanity changes the group editor: the hosting‑config tabs disappear and a Vanity domains tab appears. A vanity group only has four tabs — General, Variables, DNS servers, Vanity domains.

Reserved names

The General tab has a Reserved names box (one per line). These are names customers may not register on this group's domains (e.g. admin2, your own brand words, etc.). They are enforced on the order form, the client setup page, the API and at provisioning — on top of the built‑in technical reservations (www, mail, admin, ns1, _dmarc, …), which you never need to list yourself.

Step 2 — Attach DNS servers

On the DNS servers tab, tick the nameservers that will carry the subdomain records for this group's domains. Subdomain records are pushed to every attached DNS node (active‑active).

Vanity group — DNS servers

If a domain uses External / wildcard DNS (next step), the module writes no DNS at all and this selection is irrelevant for that domain.

Step 3 — Add the parent domains you sell

Open the Vanity domains tab. This is the core of the setup. Note the banner restating the safety guarantee — the module only adds/removes the per‑service subdomain, one mailbox, and (in push mode) one DNS record; it never touches the parent mail domain, the zone, or your provider Hestia user.

Vanity domains — sellable parents

Click Add domain and configure each parent domain:

Edit vanity parent domain

Field What it means
Parent domain The domain you own and sell on (e.g. benchwords.com). Sold as name.<domain> (site) + name@<domain> (mailbox).
Mail server + Provider mail username The shared Hestia mail user that already owns the mail domain. This user must already own the mail domain on HestiaCP before you sell slots on it. Every customer mailbox is created on this one user.
Mail domain Usually the parent domain; leave blank to use it.
DNS mode External / wildcard — you maintain a *.domain wildcard (or manage DNS yourself) and the module touches no DNS. Push — the module writes the name A/AAAA record into your existing zone.
Web servers Which Web nodes may host this domain's sites. The least‑loaded ticked node is chosen at order time. Tick at least one (leave empty only for a mail‑only vanity product).
Status Active (sellable) to offer it; otherwise hidden from new orders.

DNS mode tip: a *.benchwords.com wildcard A‑record pointing at your web tier is the simplest setup — every new name.benchwords.com resolves immediately with zero per‑order DNS work. Use Push mode only when you need exact per‑name records in a zone the module manages.

Step 4 — Variables (optional)

The Variables tab works the same as for standard groups — group‑wide {name} values used by DNS zone templates. Most vanity setups don't need it (the subdomain record is the only DNS the module writes). Note that a vanity group shows only four tabs — General / Variables / DNS servers / Vanity domains — the hosting‑config tabs are hidden.

Vanity group — Variables

Once the group has at least one Active parent domain with a mail user and a web server, it is ready. The next page wires up the product that sells from it.

Vanity Mode

The Vanity Product

PUQ Web Hosting module WHMCS

Order now | Download | Community

With the vanity group ready (previous page), create a WHMCS product that sells from it. Create a normal product (Setup → Products/Services), set its module to PUQ Web Hosting, and point its Server Group at your vanity group.

Step 1 — Set the deployment mode to Vanity

On Module Settings → General, set Deployment mode to Vanity. The limits tabs collapse into a single Vanity limits tab.

Deployment mode = Vanity

Step 2 — Vanity limits

The Vanity limits tab sets the slot sizes and the per‑slot caps:

Vanity limits

Field Meaning
Website quota Disk for the name.<domain> website. 0 = no website (skip the web role).
Mailbox quota Disk for the single name@<domain> mailbox. 0 = no mailbox (mail‑only off).
Cron jobs / Max databases / Max FTP / Default PHP Caps for the website account (same meaning as normal hosting).
Auto‑install Let's Encrypt / Rate limit Auto‑SSL on the website + outbound mail rate limit.

Tick Web and/or Mail on the General tab to control which the buyer gets (a website‑only or mailbox‑only vanity product is possible).

Step 3 — Create the Configurable Options & Custom Field

The product needs two things wired into WHMCS so the order form can expose them:

The module creates both for you. Open the Config options tab and click Create / sync missing:

Vanity config options

You'll see vanity_domain come up as dynamic (its values come straight from your group's sellable domains), the website/mailbox quota options, and the vanity_name custom field marked PRESENT. It's safe to re‑run any time — existing options and values are never changed. Tune the prices afterwards under WHMCS Configurable Options.

Step 4 — (Optional) client permissions

The Client tab toggles which client‑area actions are visible. For vanity, the relevant control is Mailbox settings — forwards / auto‑responder (the customer gets one fixed mailbox, so "create/delete mailbox" don't apply). Leave DNS/SSL/backup toggles off for a clean vanity experience.

What it looks like to your staff

Once a vanity service exists, its WHMCS service page shows the vanity configurable options — the parent Domain, Website quota and Mailbox quota — instead of the full split set:

WHMCS admin — vanity service

The product is now ready to sell. The next page walks the buyer's experience and the client area they get.

Vanity Mode

Vanity: Order & Client Experience

PUQ Web Hosting module WHMCS

Order now | Download | Community

This page follows a vanity order from the WHMCS cart through to the live customer dashboard.

On the order form

The vanity product's order form asks the buyer to choose a name and a domain, with a single helper line: “lowercase letters, digits and hyphens — this is your website name and your email name.” Website/mailbox quota dropdowns and a live price summary sit alongside.

Vanity order — choose name

As the buyer types, the module checks availability live against your API. A taken or reserved name is rejected with the reason, and a live preview shows exactly what they'll get:

Vanity order — name taken

A free name turns green and unlocks Continue:

Vanity order — name available

In the cart

At checkout the cart line is human‑readable — it shows the resolved Website (name.domain) and Email (name@domain) plus the chosen quotas, so the buyer sees precisely what they're paying for:

Vanity checkout

Deployment

After payment the service deploys with the same live splash as any product (web account → mailbox → SSL), then flips to the dashboard. See Deployment & Segmentation → How deployment works for the progress screens.

The vanity client dashboard

The customer lands on a deliberately simple, two‑card dashboard — Website and Email — each with an Open button and a Settings button, plus a small usage gauge:

Vanity client dashboard

The sidebar is trimmed to only what applies to a slot — Information, Mailbox, Web settings, FTP, Databases, Cron Jobs, Logs. There is no DNS editor, no SSL page and no backups page, because those don't apply to a vanity slot:

Vanity client sidebar

The single mailbox page

Because a slot has exactly one mailbox, there is no mailbox list — just a Mailbox settings page for name@domain: storage, change password, forwarding, and an auto‑responder. Open webmail is one click.

Vanity mailbox settings

The customer can still manage their website like normal hosting — PHP version & HTTPS (Web settings), FTP accounts, databases, cron jobs and logs — all scoped to their name.domain site.

What your staff see

The admin service panel for a vanity service makes the shared model explicit: the Website card shows the per‑service web user and a "single record on the provider zone (cluster‑managed)" note; the Email card shows the one mailbox on the shared provider mail user, and notes that "Mail SSL is managed on the provider mail domain (not per‑service)."

Admin — vanity service overview

The SSL tab confirms it — only the website certificate is shown; mail SSL belongs to your provider mail domain, not to each slot:

Admin — vanity SSL

Everything the customer does stays inside their own slot. The parent domain, the shared mail account and the DNS zone are never modified per order — exactly as promised on the setup screen.

Vanity Mode

The Vanity Shop Widget

PUQ Web Hosting module WHMCS

Order now | Download | Community

Besides selling vanity slots through the normal WHMCS cart, the module ships a standalone “claim your name” widget — two small files you can drop on any marketing domain (you can deploy it on hundreds of them). It shows a polished landing page that live‑checks names and sends the buyer straight into your prefilled WHMCS cart.

Vanity shop widget landing

How it works (and why it's safe)

The widget is just two files — index.html (the landing page) and proxy.php. The browser talks only to the widget's own proxy.php, which holds your shared API key and talks server‑to‑server to your WHMCS. The key never reaches the visitor, and proxy.php caches answers so it stays fast.

Configure it (addon → Settings → Vanity widget)

In the addon, open Settings → Vanity widget:

Vanity widget config

  1. Shared API key — used by proxy.php to authenticate to your WHMCS. Regenerating it invalidates all deployed widgets until you update them.
  2. Vanity product — pick the vanity product to sell (grouped by product group; only this module's vanity products are listed).
  3. Copy the small config block into the top of proxy.php (it already contains your WHMCS URL + key + product id).
  4. Cart behaviour — choose what Get it now does: open the normal product‑config page, or skip configuration and land straight on the filled cart (review & pay).

Then download the two files and upload both to the web root of each marketing domain:

Vanity widget download

Prerequisites: the product must be a Vanity product whose group has Vanity domains configured, and it must have the vanity_domain Configurable Option + the vanity_name Custom Field (the product's Config options tab creates them — see The vanity product).

The buyer's flow on the widget

A reserved name is rejected inline, with the live preview:

Widget — reserved name

A free name turns green and enables the button:

Widget — available name

On Get it now the button shows a spinner while it redirects…

Widget — going to checkout

…and the visitor lands on your WHMCS cart with the Vanity product, the website and email, the quotas and the price already filled in — they just pay:

Widget — lands on WHMCS checkout

One vanity product can be fronted by a single WHMCS order form and by as many drop‑anywhere widgets as you like — every landing page funnels into the same prefilled cart.

Cron & Automation

Everything the module does in the background: the deploy pipeline, the task queue with retries and failure tickets, automatic SSL, usage metering & metric billing, and suspend/terminate. All of it is driven by the addon's cron runner.

Cron & Automation

The Deploy Process

PUQ Web Hosting module WHMCS

Order now | Download | Community

Provisioning is not done synchronously inside the WHMCS order. _CreateAccount simply records the desired service and enqueues the work; the cron‑driven task runner then builds the service step by step. This is what keeps orders instant and makes every step retryable.

The chain

A new order fans out into a chain of idempotent tasks, roughly:

create package  →  create web user   →  add web domain   →  (PHP/SSL/proxy)
                →  create mail user   →  add mail domain  →  DKIM/SPF/DMARC
                →  create dns user    →  add zone         →  add records (× every DNS server)
                →  mark service active

Each task does exactly one thing on one target, checks whether it's already done before acting, and reports back. Because every step is idempotent, re‑running the chain (a retry, a Redeploy, a Factory reset) converges on the same end state instead of duplicating resources.

What the customer sees

While the chain runs, the customer sees a live progress splash with a timeline; on success they land on the dashboard, on failure an error screen with Try again. This is covered visually in Deployment & Segmentation → How deployment works.

Why async

See the next page for the retry/back‑off policy and failure tickets.

Cron & Automation

Task Queue, Retries & Tickets

PUQ Web Hosting module WHMCS

Order now | Download | Community

Every action — deploys, client‑area changes, status collection, SSL, usage sync — is a row in the task queue, processed by the cron runner.

How a task runs

  1. The cron runner picks up due tasks (respecting per‑server concurrency limits and the batch size per run).
  2. Each task is dispatched to its target server (critical for the DNS active‑active cluster — a task carries its server_id).
  3. On success the row is marked done; on failure it's scheduled for retry.

Retry & back‑off

The retry policy lives in Settings → General:

A task that exhausts its attempts is marked error and stops retrying.

Failure tickets

When Settings → Notifications → failure ticket is enabled, a task that fails terminally opens (or notes on) a WHMCS support ticket in the chosen department/priority, so staff are alerted without watching the queue. Subsequent failures on the same operation append a note rather than spamming new tickets.

Watching & cleaning up

The addon Logs → Task Queue page shows the live queue with bulk controls (delete success/error/cancelled, clean completed, force‑fail stuck). Logs → Operation Log keeps the persistent history. See Addon Module → Task Queue & Logs.

Stuck tasks (node permanently gone) can be cleared with Force‑fail stuck; the matching Verify & Repair on the service then rebuilds whatever's missing.

Cron & Automation

SSL Automation

PUQ Web Hosting module WHMCS

Order now | Download | Community

SSL is hands‑off by default: the module issues and renews Let's Encrypt certificates automatically, and gets out of the way when a customer brings their own.

Acquisition

For each role that needs a certificate, an auto‑SSL worker:

  1. Checks DNS — confirms the domain (and mail. / webmail. for mail) resolves to the right server.
  2. Probes TLS — checks whether a valid cert is already present.
  3. Issues — runs the Let's Encrypt request only when the checks pass.

Cadence (Settings → SSL)

The check interval adapts to the situation:

Rate‑limit guard

To respect Let's Encrypt limits, a domain that fails repeatedly is frozen for a configurable window (freeze after N fails, for M hours) before trying again. All of these knobs live on Settings → SSL.

Custom certificates

When a customer uploads a custom certificate (client SSL page), auto‑SSL is suspended for that role so the upload isn't overwritten, and a daily custom‑cert expiry cron warns before it lapses.

The per‑service SSL state, plus manual Issue / Renew now buttons, are on the admin service panel's SSL tab and the client SSL page.

Cron & Automation

Usage Sync & Metric Billing

PUQ Web Hosting module WHMCS

Order now | Download | Community

The module keeps live resource figures (disk, bandwidth, mailboxes, databases…) in the local database so both the admin and client areas render instantly, and it feeds WHMCS metric billing.

Per‑server batch sync

Usage is collected per server, not per service. A server.syncUsage worker lists all users on a node in one shot and recomputes every service on it, turning what used to be N × several SSH calls into one batch call per server. The cron schedules these per‑server jobs; Refresh all, Force sync and bulk actions all enqueue the same per‑server task.

Statistics page

The addon Statistics page reads purely from the database (no SSH at render time): an aggregate summary plus a per‑service usage DataTable, with Refresh all usage to enqueue a fresh collection.

Metric billing

The module exposes usage to WHMCS's MetricProvider, so you can bill on actual consumption (e.g. disk or bandwidth over an included allowance) in addition to flat plan pricing. The figures billed are the same ones shown in the client dashboard gauges.

A customer can pull fresh numbers on demand with Sync now on their dashboard; it enqueues the recompute→sync chain for just their service.

Cron & Automation

Suspend, Unsuspend & Terminate

PUQ Web Hosting module WHMCS

Order now | Download | Community

The WHMCS lifecycle commands map onto the same async, idempotent task model as provisioning.

Suspend / Unsuspend

These follow WHMCS automation (overdue suspend, etc.) or can be triggered manually from the service's Module Commands.

Terminate

Terminate removes the service's resources from every server it touches and cleans up the local rows in a transaction. A pending‑terminate state is finalised by cron, and a force‑terminate path exists for cases where a node is unreachable at termination time so the service can still be closed out cleanly.

The Vanity invariant

On a Vanity service these operations are deliberately scoped: they only ever touch that service's own subdomain, its single mailbox and its single DNS record. The shared provider domain, its mail user and its DNS zone are never modified — that invariant holds through suspend, unsuspend, terminate, redeploy and factory reset alike. See Vanity Mode → What it is & why.

Lifecycle commands always report success to WHMCS immediately and do the real work via the queue, mirroring the provisioning model — so a slow or temporarily unreachable node never blocks the WHMCS workflow.

Troubleshooting

Common issues and the tools the module gives you to diagnose and repair them — Verify & Repair, the deploy timeline, the streamed task logs, Reveal credentials, the raw‑row editor, and the per‑service Factory reset.

Troubleshooting

Common Issues

PUQ Web Hosting module WHMCS

Order now | Download | Community

Most problems come down to one of: cron not running, a node unreachable over SSH, or DNS not yet pointing. The queue and the per‑service Verify & Repair are your main tools.

Deployment stuck or failed

The customer sees the error screen; the service shows error state.

  1. Open the service → Deploy tab and read the timeline / deploy_error.
  2. Open Tasks and the failed task's detail to see the raw SSH log.
  3. Fix the cause (credentials, package, reachable node), then Redeploy or Verify & Repair.

Common causes: SSH/sudo not set up on the node, wrong server IP, package not yet created, DNS server unreachable.

Services list — Verify

A node was unreachable

Tasks for that server pile up. Once it's back, they retry automatically. If a task is permanently wedged, use Logs → Task Queue → Force‑fail stuck, then run Verify & Repair on the affected services to rebuild what's missing.

Backups show errors

Backup rows can show an error when the snapshot failed on the server (disk full, Hestia busy). Use Sync from server to reconcile the list with reality; missing‑on‑server rows are pruned automatically on sync.

Backups with errors

FTP / DB account won't create (Vanity)

A too‑long suffix on a Vanity service can overflow Hestia's username limit. The username is budget‑aware now, but if you see an invalid format error, shorten the suffix.

Vanity FTP error

A row is in a bad state

For records that got inconsistent (e.g. a half‑created resource), use the service panel's Edit DB row to correct the raw record, or Reveal credentials to log into Hestia directly and inspect.

Edit DB row Reveal credentials

DNS doesn't resolve / SSL won't issue

Auto‑SSL waits for DNS. Confirm the records are published (client DNS page → Verify for external DNS), give it a propagation cycle, and the fast‑mode SSL worker will pick it up. Check Settings → SSL isn't in a freeze window for that domain.

Golden rule: is cron running? Almost every "nothing is happening" report is a cron that isn't firing. Verify the crontab line from Settings → Cron is installed.

Questions & Answers

Short answers to the questions providers ask most often when setting up and selling with the module.

Questions & Answers

Frequently Asked Questions

PUQ Web Hosting module WHMCS

Order now | Download | Community

Do I need separate servers for web, mail and DNS? No. One server can do all three. But you can split them by capability and balance load by server type — heavy PHP sites on web nodes, mail on mail nodes, an active‑active DNS pool — without changing products. See Deployment & Segmentation.

What's the difference between Split, Unified and Vanity? Split gives each role its own Hestia user; Unified puts web+mail under one user; Vanity sells name.<your-domain> + name@<your-domain> slots on a domain you own. See Deployment Models.

What is Vanity mode for? To monetise a domain you own by selling personal sub‑sites and mailboxes on it (e.g. john.yourbrand.com + john@yourbrand.com). It's a distinct product type with a simplified client area and an optional standalone shop widget. See Vanity Mode.

Why does provisioning happen "in the background"? Orders are instant and every step is retryable. _CreateAccount enqueues work; the cron task runner builds the service idempotently. See Cron & Automation → The deploy process.

Nothing is provisioning — what's wrong? Almost always cron isn't running. Confirm the crontab line from Settings → Cron is installed, then watch Logs → Task Queue.

How does SSL work? Let's Encrypt is issued and renewed automatically once DNS points at the server; customers can also upload a custom certificate. See Cron & Automation → SSL automation.

Can customers manage their own FTP, databases, DNS, mail, backups and cron? Yes — each is a client‑area page, and each is gated by the product's Client permissions so you decide what every plan exposes. See Client Area.

How is usage billed? Live usage is synced per‑server and exposed to WHMCS metric billing, on top of flat plan pricing. See Usage Sync & Metric Billing.

Which DNS backends are supported? HestiaCP and PowerDNS, mixable in one cluster. DNS is active‑active: every record is replicated to all attached DNS servers.

Does terminating a Vanity service hurt the shared domain? No. Vanity operations only ever touch that service's own subdomain, single mailbox and single DNS record — never the shared provider domain, mail user or zone.

A node went down mid‑deploy — did I lose the service? No. Its tasks retry when it's back; if a task is permanently stuck, Force‑fail stuck then Verify & Repair rebuilds what's missing. See Troubleshooting.

How do I move a product to a new deployment mode or add a role? Change it on the product's General tab, re‑run Config options → Create / sync missing (safe, additive), and redeploy affected services.

Which PHP version / module build do I need? Install the build that matches the PHP version your WHMCS host runs on. The module ships builds for PHP 7.4, 8.1 and 8.2. WHMCS 8 runs on PHP 7.4, 8.1 or 8.2 → use the matching build; WHMCS 9 runs on PHP 8.2 → use the 8.2 build; on any host with PHP 8.3 / 8.4 or newer, use the 8.2 build. This is the WHMCS host's PHP — separate from the PHP versions you offer to hosting customers on each Hestia web server. Full table in Installation & Configuration → Requirements & Installation.

Where do I get help or ask questions? Join the PUQ community at community.puqcloud.com.