Installation et prérequis
Comment installer WSA sur un serveur cPanel, prérequis système, mise à jour, désinstallation.
WSA s'installe via une seule commande (« one-liner ») téléchargée depuis le serveur de distribution d'Astral Internet. Cette page décrit les prérequis, la procédure pas à pas, la mise à jour et la désinstallation.
⚠️ L'installation requiert un accès root SSH au serveur. Toutes les commandes doivent être lancées en tant que
root.
Installation rapide — one-liner
cd /root && wget https://wsa.cdn.astral360.com/pub/wsa-install && sh wsa-install stableLe dernier argument sélectionne la branche de release — choisir un parmi :
| Branche | Quand l'utiliser |
|---|---|
stable |
Serveurs en production (recommandé). Releases testées et validées. |
current |
Production légèrement plus à jour. Releases stables récemment publiées. |
edge |
Beta / staging. Évaluer les nouveautés avant qu'elles arrivent dans stable. |
La branche peut être changée plus tard depuis le WHM (Module Configuration → Release tier). Voir §2.2 ci-dessous pour le déroulement détaillé.
1. Prérequis système
1.1 Système d'exploitation
WSA est compatible avec les distributions Enterprise Linux suivantes :
| Distribution | Versions supportées |
|---|---|
| CentOS | 7, 8 |
| AlmaLinux | 8, 9, 10 |
| Rocky Linux | 8, 9, 10 |
| CloudLinux | 8, 9 |
| Red Hat Enterprise Linux | 8, 9, 10 |
Le script d'installation détecte automatiquement la distribution (rpm -q --qf "%{VERSION}" --whatprovides redhat-release) et adapte les commandes (yum sur EL 7, dnf sur EL 8+).
📝 EL 7 est encore supporté mais ne reçoit pas HTTP/3 (limite des paquets OpenSSL disponibles). EL 9 et EL 10 sont les distributions recommandées pour profiter de toutes les fonctionnalités.
1.2 cPanel/WHM
- cPanel installé et fonctionnel sur le serveur.
- Version cPanel 108 ou plus récente (cPanel ≥ 108 inclut les API requises et le thème Jupiter par défaut).
- Apache géré par EasyApache 4.
- Thème cPanel : Jupiter (recommandé) ou Paper Lantern (legacy mais supporté).
1.3 ionCube Loader
Le code de WSA est encodé avec ionCube. Le loader doit donc être actif sur les versions PHP utilisées par cPanel et le système.
Le script wsa-install détecte l'absence d'ionCube et propose de l'activer automatiquement :
# Vérification manuelle :
whmapi1 get_tweaksetting key=phploaderSi la sortie ne contient pas ioncube, l'installation l'active via :
whmapi1 set_tweaksetting key=phploader value=ioncubeTu peux refuser l'activation automatique, mais dans ce cas l'installation s'arrête immédiatement — WSA ne peut pas fonctionner sans ionCube.
1.4 Espace disque
| Élément | Espace requis |
|---|---|
| Module WSA et dépendances | ~100 Mo (/etc/wsa/) |
| Cache nginx — zone Dynamic | 512 Mo par défaut, configurable |
| Cache nginx — zone CSS/JS | 512 Mo par défaut, configurable |
| Cache nginx — zone Static/Media | 1024 Mo par défaut, configurable |
| Logs nginx + module | quelques centaines de Mo selon le trafic |
Recommandation : prévoir au minimum 5 Go libres sur /var/ pour absorber les caches sur un serveur multi-tenant.
1.5 RAM et CPU
WSA ajoute nginx au stack. Consommation typique :
| Composant | RAM | CPU |
|---|---|---|
| nginx (4 workers) | ~50-100 Mo | < 5 % en régime |
Démon wsad (Perl, inotify watcher) |
~30 Mo | négligeable |
Aucun pré-requis CPU spécifique — WSA tourne sur tout serveur sur lequel cPanel fonctionne déjà.
1.6 Réseau et pare-feu
- Ports publics 80 et 443 doivent rester ouverts.
- Apache sera reconfiguré pour écouter sur les ports 8080 et 8443 internes (gérés automatiquement par l'installateur ; aucune intervention manuelle).
- Si HTTP/3 est activé plus tard : le port UDP/443 est ouvert automatiquement par WSA (CSF ou firewalld détecté automatiquement).
- Pour la première installation, le serveur doit pouvoir joindre
wsa.cdn.astral360.cometactivation.astral360.comen HTTPS sortant (enrôlement d'activation + téléchargement des sources vérifiées).
2. Procédure d'installation
2.1 Connexion au serveur
Connectez-vous en SSH au serveur en tant que root :
ssh root@votre-serveur.example.com2.2 Téléchargement et exécution du script
Une seule commande lance l'installation complète :
cd /root && \
wget https://wsa.cdn.astral360.com/pub/wsa-install && \
sh wsa-install stableLe dernier argument (stable) sélectionne la branche de release. Quatre choix :
| Branche | Pour qui ? |
|---|---|
stable |
Production. Releases testées, recommandé pour les serveurs en production. |
current |
Production légèrement plus à jour. Releases stables récemment publiées. |
edge |
Beta. Pour servers de test ou évaluation des nouveautés avant publication. |
dev |
Développement. Réservé à l'équipe Astral Internet. |
💡 Le choix de branche peut être changé plus tard depuis le WHM, page Configuration du module.
2.3 Déroulement de l'installation
L'installation se déroule automatiquement en plusieurs étapes, visibles dans le terminal :
- Vérification d'ionCube — proposition d'activation si absent.
- Téléchargement du module et des dépendances Composer.
- Création des répertoires
/etc/wsa/,/var/log/wsa/, etc. - Installation d'nginx depuis le dépôt officiel.
- Configuration des hooks cPanel (renouvellement SSL, suspension de compte, etc.).
- Démarrage du démon
wsad(surveillance temps réel). - Enregistrement du plugin WHM (icône dans le panneau admin).
- Enregistrement du plugin cPanel (icône dans le panneau client).
- Génération de la première configuration nginx et redémarrage des services.
- Activation des tâches cron internes.
Durée typique : 3 à 8 minutes selon la vitesse réseau et la taille du serveur.
2.4 Modules nginx optionnels (Brotli, HTTP/3)
L'installeur se contente de déployer et d'activer WSA — depuis la 2.3.0
il ne compile plus aucun module nginx optionnel, ce qui garde l'installation
rapide et fiable. wsa-install prend un seul argument : le canal de release
(stable — le défaut — / current / edge / dev).
Construisez Brotli (ou HTTP/3) à la demande après l'installation, depuis WHM → Nginx Build & Modules, ou en ligne de commande :
/etc/wsa/wsa --nginx-install=brotli --verboseLes versions précédentes proposaient les drapeaux
--with-brotli/--skip-brotliet un prompt Brotli interactif pendant l'installation. Ils ont été retirés en 2.3.0 : la compilation Brotli de plusieurs minutes pouvait entrer en course avec l'activation post-installation, et un module compilé contre le nginx RPM fraîchement installé pouvait être incompatible et cassernginx -t. Construisez Brotli quand vous êtes prêt, depuis WHM.
3. Vérification post-installation
3.1 Status des services
# nginx tourne
systemctl status nginx
# Démon wsad actif
systemctl status wsad.service
# Apache déplacé vers 8080/8443
ss -tlnp | grep -E ':(80|443|8080|8443)\s'
# Doit montrer nginx sur 80/443 et httpd sur 8080/84433.2 Status de WSA via CLI
# Version installée
/etc/wsa/wsa --version
# État global du module
/etc/wsa/wsa --status
# Vérification de la cache (sur un site existant)
curl -I https://example.com/ | grep -i cache-status
# Doit afficher : X-Nginx-Cache-Status: HIT (ou MISS au premier appel)3.3 Interfaces graphiques
- WHM : Plugins → WSA – Cache for cPanel server (icône orange WSA en haut à droite de la liste des plugins).
- cPanel d'un compte utilisateur : section Logiciel → WSA - Website Accelerator.
Si une des icônes manque, voir Dépannage de l'installation.
4. Mise à jour
4.1 Mise à jour automatique
Quand l'option Auto Update est activée dans le WHM (Configuration du module → Mise à jour automatique), WSA vérifie quotidiennement la dernière version disponible sur sa branche (stable, current, edge) et l'installe en arrière- plan.
L'opération se fait sans interruption de service :
- Téléchargement de la nouvelle version dans un dossier temporaire.
- Remplacement atomique du code source.
- Exécution du script
post_update.php(migrations SQLite, nettoyage). - Rechargement de nginx.
4.2 Mise à jour manuelle
Pour forcer une mise à jour immédiate (CLI ou bouton WHM Mettre à jour WSA) :
/etc/wsa/wsa --update --verboseLa sortie streamée affiche chaque étape. Compter 30 secondes à 2 minutes selon la version cible.
4.3 Changer de branche de release
Depuis le WHM : Configuration du module → Niveau de release → choisir stable, current, edge ou dev → enregistrer.
La prochaine mise à jour (automatique ou manuelle) ira chercher la dernière version de la branche choisie. Attention : passer de stable à edge peut installer une beta non testée ; faire d'abord une sauvegarde si le serveur est en production.
5. Dépannage
5.1 Le script wsa-install échoue à l'étape ionCube
Erreur :
- Activating Ioncube ... FailedCause : votre compte cPanel n'a pas les permissions whmapi1, ou le serveur est en mode CloudLinux avec PHP encadré par CageFS.
Solution :
# Active ionCube manuellement via cPanel WHM web UI :
# Home → Server Configuration → Tweak Settings → PHP loader → ioncube → Save
# Puis relancer l'installeur (re-télécharge au cas où le script se serait auto-supprimé)
cd /root && wget https://wsa.cdn.astral360.com/pub/wsa-install && sh wsa-install stable5.2 Erreur 503 sur les sites après l'installation
Cause typique : Apache n'a pas pu basculer sur les ports 8080/8443 — un autre service occupe déjà ces ports.
# Identifier le processus
ss -tlnp | grep -E ':(8080|8443)'
# Une fois identifié et arrêté, relancer Apache
systemctl restart httpd5.3 L'icône WSA n'apparaît pas dans cPanel
Cause typique : le plugin n'a pas été enregistré ou le cache des applications cPanel par utilisateur n'a pas été invalidé.
# Re-enregistrer le plugin
/usr/local/cpanel/scripts/install_plugin /etc/wsa/conf/wsa.tar.gz --theme=jupiter
/usr/local/cpanel/scripts/install_plugin /etc/wsa/conf/wsa.tar.gz --theme=paper_lantern
# Rebuild les sprites d'icônes
/usr/local/cpanel/bin/rebuild_sprites
# Vider les caches utilisateurs
find /home/*/.cpanel/datastore -name 'AVAILABLE_APPLICATIONS_CACHE_*' -delete5.4 Les logs d'installation
L'installation écrit dans plusieurs endroits utiles pour le diagnostic :
| Fichier | Contenu |
|---|---|
/var/log/wsa/wsa.log |
Log principal du module (toutes opérations) |
/var/log/wsa/install_plugin.log |
Sortie de install_plugin (registration cPanel) |
/var/log/wsa/install.log |
Log de l'install.sh initial |
/var/log/nginx/error.log |
Erreurs nginx en cours d'exécution |
6. Désinstallation
WSA peut être désinstallé proprement à tout moment. La désinstallation restaure intégralement la configuration Apache d'origine — vos sites continuent de fonctionner sans interruption.
6.1 Procédure
En SSH root :
/etc/wsa/install/uninstall.shLe script :
- Désactive le module WSA (
wsa --disable) — vhosts nginx désinstallés. - Supprime les tâches cron WSA.
- Désinstalle les hooks Perl cPanel.
- Arrête et supprime le démon
wsad. - Désinstalle nginx (paquet RPM).
- Désenregistre le plugin WHM et cPanel.
- Supprime les répertoires
/etc/wsa/et les fichiers de log.
Apache reprend les ports 80 et 443 automatiquement.
6.2 Options de désinstallation avancée
Par défaut, la désinstallation conserve :
- Le fichier
/etc/ssl/certs/dhparam.pem(généré pendant l'install). - Les éventuelles modifications de configuration nginx installées par l'admin (sous
/etc/nginx/).
Pour une suppression totale :
/etc/wsa/install/uninstall.sh
rm -rf /etc/nginx/ # uniquement si vous n'utilisez plus nginx
rm -f /etc/ssl/certs/dhparam.pem7. Cas particuliers
7.1 CloudLinux + CageFS
WSA est compatible avec CloudLinux. L'installation rebuild automatiquement le squelette CageFS quand le module ea-apache24-mod_remoteip est installé.
7.2 Serveur derrière un NAT
WSA détecte les serveurs en NAT 1:1 via le fichier /var/cpanel/cpnat. L'IP publique est utilisée pour la validation de licence et le téléchargement des mises à jour.
7.3 Migration depuis une version legacy
Si vous mettez à jour depuis une WSA antérieure à 2.1.0, le script post_update.php migre automatiquement :
- Les anciens fichiers de configuration JSON (per-user)
- L'ancienne base SQLite (ajout des nouvelles colonnes).
- Les listes de bots préchargées.
Aucune intervention manuelle n'est nécessaire.
Pour aller plus loin
- Qu'est-ce que WSA ? — Comprendre ce que fait le module avant de l'installer.
- Tableau de bord WHM — Le point d'entrée après l'installation.
- Ligne de commande — Référence complète CLI pour l'automatisation et le dépannage.