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.

Installation

Installation — WSA pour cPanel/WHM

Web Site Accelerator (WSA) — module de cache Nginx + protection anti-bots
pour cPanel/WHM. Ce document couvre l'installation initiale, la
vérification du bon fonctionnement, puis l'activation du module
Brotli (compression complémentaire à gzip).

Pour la documentation d'utilisation complète, voir
documentation-fr.md.

1. Prérequis

Avant de commencer, vérifier que le serveur respecte les conditions
suivantes.

Requis Version / état
Système d'exploitation AlmaLinux, Rocky Linux, Oracle Linux, CloudLinux ou CentOS — versions 8, 9 ou 10
cPanel/WHM Installation valide et licenciée
Accès SSH Compte root (l'installateur en a besoin)
Nginx Sera installé par WSA si absent. Pour Brotli : Nginx ≥ 1.30 est requis.
IonCube Loader Activé automatiquement par l'installateur si absent

Note CentOS 7 : plus supporté depuis WSA 1.4.0 (juin 2024, fin de
vie upstream). Mettre à niveau vers AlmaLinux/Rocky 8+ avant
l'installation.

2. Installation

2.1 Connexion au serveur

Se connecter en SSH en tant que root :

ssh root@votre-serveur.exemple.com

2.2 Lancer l'installateur

Une seule ligne de commande télécharge et exécute l'installateur
officiel :

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

L'argument stable correspond à la branche de mise à jour. Quatre
valeurs sont acceptées :

  • stable — recommandée pour la production (par défaut si absente)
  • current — versions stables récentes, légèrement en avance
  • edge — versions de validation pré-stable

2.3 Étapes exécutées par l'installateur

L'installateur effectue automatiquement :

  1. Vérification que IonCube Loader est actif ; activation via
    whmapi1 set_tweaksetting key=phploader value=ioncube si absent.
  2. Détection de l'IP publique du serveur (gère le NAT 1:1 cPanel via
    /var/cpanel/cpnat).
  3. Téléchargement des dépendances vendor + du module dans un dossier
    temporaire wsa/.
  4. Installation des fichiers dans :
    • /etc/wsa/ — dossier principal (configuration, librairies, CLI)
    • /usr/local/cpanel/whostmgr/docroot/cgi/wsa/ — interface WHM
    • /usr/local/cpanel/base/frontend/{paper_lantern,jupiter}/wsa/ —
      interface cPanel
    • /var/log/wsa/ — journaux
  5. Installation de la base SQLite (/etc/wsa/conf/wsa.sqlite).
  6. Activation et démarrage du service wsad (daemon de surveillance
    cache + cron).
  7. Installation des hooks cPanel (rebuild automatique des vhosts à
    chaque changement SSL).
  8. Proposition d'installer Brotli (voir section 4).
  9. Démarrage de la période d'essai de 60 jours.

L'installateur affiche le résultat de chaque étape en couleur. Une
sortie sans message rouge confirme un succès.

3. Vérification dans WHM

Important : après installation, toujours valider visuellement dans
WHM avant de mettre en production.

3.1 Ouvrir l'interface WHM

  1. Se connecter à WHM (https://votre-serveur:2087).
  2. Dans la barre de recherche en haut à gauche, taper « WSA ».
  3. Cliquer sur « WSA – Cache pour serveur cPanel » sous le groupe
    Plugins.

3.2 Vérifier le bandeau de statut

En haut de la page d'accueil WSA s'affiche un bandeau à deux lignes :

  • Ligne 1 — État du module : doit indiquer Module enabled (vert).
    Si Module disabled, cliquer sur Enable module dans la section
    rouge en bas de la page.
  • Ligne 2 — État de Nginx : doit indiquer Nginx is running (vert).
    Sinon, cliquer sur la tuile Restart Nginx (rouge) dans la rangée
    d'actions.

3.3 Vérifier les jauges d'utilisation du cache

Dans la rangée Cache row, trois barres de progression montrent
l'utilisation des trois zones de cache :

  • Dynamic Cache — pages PHP/HTML
  • CSS / JS Cache — fichiers statiques scriptables
  • Media Cache — images, fontes, fichiers téléchargeables

Au démarrage, les trois sont à 0 %. Au bout de quelques minutes de
trafic réel, les barres devraient se remplir progressivement (vert).

Code couleur :

  • < 75 % : vert — sain
  • 75 – 90 % : ambre — surveillance
  • ≥ 90 % : rouge — augmenter la taille de cache dans
    Module Configuration

3.4 Tester un site hébergé

  1. Ouvrir un site cPanel hébergé sur le serveur dans un navigateur.
  2. Activer les outils développeur (F12) → onglet Réseau.
  3. Recharger la page (Ctrl+F5 puis Ctrl+R).
  4. Cliquer sur la requête de la page HTML principale.
  5. Dans les en-têtes de réponse, chercher :
    • X-Server-Powered-By: Nginx for WHM/cPanel by Astral Internet
    • X-Nginx-Cache-Status: HIT (au 2e rechargement) ou MISS (au 1er)

La présence de ces en-têtes confirme que Nginx sert effectivement la
page et que le cache fonctionne.

3.5 Consulter les statistiques anti-bots

Dans le panneau Bot Protection (last 24 h) :

  • Total blocked — nombre total de requêtes bloquées (HTTP 444)
  • Unique IPs — nombre d'IPs distinctes bloquées
  • Top User-Agent — User-Agent le plus offensif

Au démarrage, ces compteurs sont à zéro. Ils se remplissent
naturellement après quelques heures de trafic.

4. Installer et activer Brotli

Brotli est un codec de compression environ 15 à 25 % plus efficace
que gzip pour les fichiers texte (HTML, CSS, JavaScript, JSON). Il est
optionnel mais fortement recommandé.

4.1 Prérequis spécifiques à Brotli

  • Nginx 1.30 ou plus récent — vérification automatique par
    l'installateur. Si Nginx est plus ancien, mettre à niveau via le
    dépôt officiel : https://nginx.org/en/linux_packages.html
  • Outils de compilation : git, gcc, make, cmake ou cmake3 —
    installés automatiquement à la demande.
  • ~ 200 Mo libres dans /usr/local/src/ pour la compilation.

4.2 Méthode A — depuis WHM (recommandé)

  1. Page WSA → Nginx Configuration.
  2. Section Compression → bouton « Build & install Brotli ».
  3. Confirmer dans la fenêtre.
  4. Une console affiche le déroulement de la compilation (3 à 8
    minutes selon le serveur). À la fin, un message vert « Brotli
    modules installed for nginx X.Y.Z »     confirme le succès.
  5. Cocher la case Enable Brotli dans la section Compression,
    puis Save. Ceci ajoute les directives brotli on; et
    brotli_static on; à la prochaine régénération de la
    configuration Nginx.
  6. Cliquer Rebuild Nginx conf depuis la page d'accueil pour
    appliquer.

4.3 Méthode B — depuis la ligne de commande

Si l'on préfère faire l'opération en SSH (utile en cas
d'automatisation par script Ansible/cron) :

# Compilation + installation des modules .so
/etc/wsa/./wsa --nginx-install=brotli --verbose

# Activation des directives dans nginx.conf
/etc/wsa/./wsa --nginx-enable=brotli

# Régénération de la configuration Nginx
/etc/wsa/./wsa --rebuild-forced

4.4 Vérification

Tester la compression Brotli sur un site hébergé :

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

Le retour attendu :

content-encoding: br

Si le retour est gzip, le navigateur ou le client n'a pas demandé
Brotli (en-tête Accept-Encoding: br requis), ou la directive Brotli
n'est pas active. Vérifier dans l'interface cPanel d'un domaine que
l'indicateur compression dans le coin supérieur droit affiche
● Brotli/Gzip (ou au moins ● Brotli).

4.5 Désinstaller Brotli (si besoin)

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

5. Désinstallation complète du module

⚠ Cette opération supprime WSA, désactive Nginx et restaure Apache
sur les ports 80/443. Tous les sites continueront de fonctionner
mais sans cache.

sh /etc/wsa/uninstall.sh

Le script demande confirmation, retire les fichiers, désactive le
service wsad et réassigne Apache aux ports standards.

6. Dépannage rapide

Symptôme Solution
L'installateur échoue sur IonCube Activer manuellement : whmapi1 set_tweaksetting key=phploader value=ioncube
WHM ne montre pas le menu WSA Vider le cache du navigateur ; vérifier /usr/local/cpanel/whostmgr/docroot/cgi/wsa/
Nginx refuse de démarrer nginx -t pour voir l'erreur, puis page WHM → Rebuild Nginx conf
Sites lents après install Rangée Cache row → cliquer Clear Nginx cache, attendre 10 min de trafic
Brotli build échoue (-Werror=cast-function-type) Mettre Nginx à jour vers ≥ 1.30 (résolu en WSA 1.5.7)
Brotli build OK mais nginx -t échoue avec undefined symbol Réinstaller : --nginx-uninstall=brotli puis --nginx-install=brotli (correctif WSA 1.5.8)

Pour toute autre question, consulter le journal complet :

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

Document mis à jour pour WSA 1.5.8 — avril 2026.

Sidebar