# 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. # Requirements & Installation ### PUQ Web Hosting module **[WHMCS](https://puqcloud.com/)** ##### [Order now](https://puqcloud.com/) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-WEB-Hosting/) | [Community](http://community.puqcloud.com/) ## Requirements * A working **WHMCS** installation (see the PHP/WHMCS compatibility table below). * **ionCube Loader** enabled on the WHMCS host, matching the PHP version it runs. * One or more **HestiaCP** servers reachable over **SSH** from the WHMCS host. The module drives Hestia entirely over SSH (the panel HTTP API is not required); set up `sudo` NOPASSWD for the management user, or use the Hestia `admin` user with key/password auth. * (Optional) **PowerDNS** servers if you want PowerDNS as a DNS backend alongside HestiaCP. * Outbound HTTPS from the Hestia nodes for Let's Encrypt and for the optional file‑manager / PHP installers. ## 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](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-WEB-Hosting/) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-ux7vz1ub.png) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-auxrkhfm.png) > 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. # Add Web / Mail / DNS Servers ### PUQ Web Hosting module **[WHMCS](https://puqcloud.com/)** ##### [Order now](https://puqcloud.com/) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-WEB-Hosting/) | [Community](http://community.puqcloud.com/) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-amwu4xyh.png) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-nerx1kgb.png) | 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-evevqion.png) * **DNS zone template** — the template used for zones created on/for this node. * **Capacity max** — soft capacity used for least‑loaded placement. * **SSH command timeout** — override for slow nodes. * **Default Hestia package** for new users. 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: * **One node, all roles** → tick Web + Mail + DNS on a single server (great for starting out). * **Web/mail split** → some nodes tick **Web** only, dedicated nodes tick **Mail** only. * **Three tiers** → separate Web, Mail and **DNS** (nameserver) pools. ![Mail servers list](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-censsunx.png) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-hexrlf8c.png) > 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. # Server Groups ### PUQ Web Hosting module **[WHMCS](https://puqcloud.com/)** ##### [Order now](https://puqcloud.com/) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-WEB-Hosting/) | [Community](http://community.puqcloud.com/) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-c6dclixc.png) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-yycxpdje.png) * **Standard hosting** — web / mail / DNS servers + a DNS cluster. Used by Split and Unified products. * **Vanity** — sell `name.` / `name@` on domains you own. Choosing this hides the hosting‑config tabs and shows the **Vanity domains** tab. (See the dedicated **Vanity Mode** chapter.) ## 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-7bybvvls.png) 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. # Create a Product ### PUQ Web Hosting module **[WHMCS](https://puqcloud.com/)** ##### [Order now](https://puqcloud.com/) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-WEB-Hosting/) | [Community](http://community.puqcloud.com/) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-h8rgvqnu.png) 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-sagyjsab.png) ## 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. * **Web limits** — disk, bandwidth, cron jobs, backups kept, max subdomains (`WEB_ALIASES`), max databases, max FTP accounts, default PHP version, auto‑install Let's Encrypt. ![Web limits](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-obryo1jf.png) * **Mail limits** — mail disk, mail accounts, outbound rate limit/hour, mail backups (independent of web), max forwarders, max aliases, autoresponders/spam‑filter. ![Mail limits](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-064pwvet.png) * **DNS limits** — max DNS records, DNS disk quota, default TTL, and the **allowed record types** the customer may use (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, DNSKEY, DS, NAPTR, TLSA — on both HestiaCP BIND and PowerDNS). ![DNS limits](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-pbjjv3h6.png) > 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-7bbbfrud.png) ## 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-c38zr0lm.png) ## 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](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-qjhauege.png) After syncing they show **COMPLETE**: ![Config options — complete](https://doc.puq.info/uploads/images/gallery/2026-06/embedded-image-4fqhurk1.png) 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**.