Menu

Installation

Installation — WSA for cPanel/WHM

Web Site Accelerator (WSA) — Nginx caching + bot-protection module
for cPanel/WHM. This document covers the initial install, how to
verify the module is working, and how to install + enable the
Brotli compression module.

For complete usage documentation, see
documentation-en.md.

1. Prerequisites

Before starting, verify the server meets the following requirements.

Requirement Version / state
Operating system AlmaLinux, Rocky Linux, Oracle Linux, CloudLinux or CentOS — versions 8, 9 or 10
cPanel/WHM Valid licensed installation
SSH access root account (the installer needs it)
Nginx Will be installed by WSA if absent. For Brotli: Nginx ≥ 1.30 required.
IonCube Loader Activated automatically by the installer if missing

CentOS 7 note: no longer supported since WSA 1.4.0 (June 2024,
upstream EOL). Migrate to AlmaLinux/Rocky 8+ before installing.

2. Installation

2.1 Connect to the server

SSH in as root:

ssh root@your-server.example.com

2.2 Run the installer

A single command downloads and runs the official installer:

wget https://static.astralinternet.com/nginx/install/wsa-install && sh wsa-install stable

The stable argument is the update branch. Four values are accepted:

  • stable — recommended for production (default if omitted)
  • current — recent stable releases, slightly ahead
  • edge — pre-stable validation builds

2.3 What the installer does

The installer automatically performs:

  1. Verifies IonCube Loader is active; activates it via
    whmapi1 set_tweaksetting key=phploader value=ioncube if not.
  2. Detects the server's public IP (handles cPanel 1:1 NAT via
    /var/cpanel/cpnat).
  3. Downloads the vendor dependencies + the module into a temporary
    wsa/ directory.
  4. Installs files into:
    • /etc/wsa/ — main folder (configuration, libraries, CLI)
    • /usr/local/cpanel/whostmgr/docroot/cgi/wsa/ — WHM interface
    • /usr/local/cpanel/base/frontend/{paper_lantern,jupiter}/wsa/ —
      cPanel interface
    • /var/log/wsa/ — logs
  5. Installs the SQLite database (/etc/wsa/conf/wsa.sqlite).
  6. Enables and starts the wsad service (cache surveillance + cron
    daemon).
  7. Installs cPanel hooks (auto-rebuild of vhosts on every SSL
    change).
  8. Offers to install Brotli (see section 4).
  9. Starts the 60-day trial period.

The installer prints the result of every step in colour. Output with
no red message confirms success.

3. Verify in WHM

Important: after install, always confirm visually in WHM before
going to production.

3.1 Open the WHM interface

  1. Log in to WHM (https://your-server:2087).
  2. In the search bar at the top-left, type "WSA".
  3. Click "WSA – Cache for cPanel server" under the Plugins
    group.

3.2 Check the status banner

The WSA home page header shows a two-row status banner:

  • Row 1 — Module state: must show Module enabled (green). If
    Module disabled, click Enable module in the red section at
    the bottom of the page.
  • Row 2 — Nginx state: must show Nginx is running (green).
    Otherwise, click the Restart Nginx tile (red) in the action
    row.

3.3 Check cache usage gauges

In the Cache row, three progress bars show usage of the three
cache zones:

  • Dynamic Cache — PHP/HTML pages
  • CSS / JS Cache — scripted static files
  • Media Cache — images, fonts, downloadable files

At startup, all three are at 0 %. After a few minutes of real
traffic, the bars should fill progressively (green).

Colour code:

  • < 75 % : green — healthy
  • 75 – 90 % : amber — watch
  • ≥ 90 % : red — increase the cache size in Module Configuration

3.4 Test a hosted site

  1. Open any cPanel-hosted site on the server in a browser.
  2. Open developer tools (F12) → Network tab.
  3. Reload the page (Ctrl+F5 then Ctrl+R).
  4. Click on the main HTML page request.
  5. In the response headers, look for:
    • X-Server-Powered-By: Nginx for WHM/cPanel by Astral Internet
    • X-Nginx-Cache-Status: HIT (on 2nd reload) or MISS (on 1st)

The presence of these headers confirms Nginx is actually serving the
page and the cache is working.

3.5 Inspect bot-protection statistics

In the Bot Protection (last 24 h) panel:

  • Total blocked — total blocked requests (HTTP 444)
  • Unique IPs — distinct IPs blocked
  • Top User-Agent — most aggressive UA

These counters start at zero. They populate naturally after a few
hours of traffic.

4. Install and enable Brotli

Brotli is a compression codec roughly 15 – 25 % more efficient than
gzip for text files (HTML, CSS, JavaScript, JSON). It is optional but
strongly recommended.

4.1 Brotli-specific prerequisites

  • Nginx 1.30 or newer — verified automatically by the installer.
    If Nginx is older, upgrade via the official repository:
    https://nginx.org/en/linux_packages.html
  • Build tools: git, gcc, make, cmake or cmake3 —
    auto-installed on demand.
  • ~ 200 MB free in /usr/local/src/ for compilation.

4.2 Method A — from WHM (recommended)

  1. Page WSA → Nginx Configuration.
  2. Compression section → button "Build & install Brotli".
  3. Confirm in the dialog.
  4. A console streams the build progress (3 to 8 minutes depending on
    the server). At the end, a green message "Brotli modules
    installed for nginx X.Y.Z"     confirms success.
  5. Tick the Enable Brotli checkbox in the Compression section,
    then Save. This adds brotli on; and brotli_static on;
    directives at the next Nginx config rebuild.
  6. Click Rebuild Nginx conf from the home page to apply.

4.3 Method B — from the command line

If you prefer doing this over SSH (handy for Ansible/cron
automation):

# Build + install the .so modules
/etc/wsa/./wsa --nginx-install=brotli --verbose

# Enable directives in nginx.conf
/etc/wsa/./wsa --nginx-enable=brotli

# Regenerate the Nginx configuration
/etc/wsa/./wsa --rebuild-forced

4.4 Verification

Test Brotli compression on a hosted site:

curl -s -H "Accept-Encoding: br" -I https://your-site.example.com/ \
  | grep -i content-encoding

Expected response:

content-encoding: br

If the response is gzip, the client did not request Brotli (the
Accept-Encoding: br header is required), or the Brotli directive
isn't active. Verify in any cPanel domain interface that the
compression indicator in the top-right corner shows
● Brotli/Gzip (or at least ● Brotli).

4.5 Uninstall Brotli (if needed)

/etc/wsa/./wsa --nginx-uninstall=brotli
/etc/wsa/./wsa --rebuild-forced

5. Complete module uninstall

⚠ This operation removes WSA, disables Nginx, and restores Apache
on ports 80/443. Every site continues working, but without cache.

sh /etc/wsa/uninstall.sh

The script asks for confirmation, removes the files, disables the
wsad service, and reassigns Apache to standard ports.

6. Quick troubleshooting

Symptom Resolution
Installer fails on IonCube Activate manually: whmapi1 set_tweaksetting key=phploader value=ioncube
WHM does not show the WSA menu Clear browser cache; verify /usr/local/cpanel/whostmgr/docroot/cgi/wsa/ exists
Nginx refuses to start nginx -t for the error, then WHM page → Rebuild Nginx conf
Sites slow after install Cache row → click Clear Nginx cache, allow 10 min of traffic
Brotli build fails (-Werror=cast-function-type) Upgrade Nginx to ≥ 1.30 (fixed in WSA 1.5.7)
Brotli build OK but nginx -t says undefined symbol Reinstall: --nginx-uninstall=brotli then --nginx-install=brotli (fix in WSA 1.5.8)

For any other issue, check the full log:

tail -f /var/log/wsa/wsa.log

Document updated for WSA 1.5.8 — April 2026.

Sidebar