PingWAF WAF
Français
English EN 简体中文 ZH Español ES Français FR 日本語 JA
GitHub
Aperçu Fonctionnalités Démarrage Installation Documentation GitHub ↗

Installation

De zéro à un nœud opérationnel en une commande

Docker Compose est la méthode recommandée : une commande démarre le plan de contrôle, l'agent intégré et PostgreSQL. L'installation par script reste disponible pour les hôtes gérés par systemd.

Exécution Une commande Modes all-in-one · server · agent Plateforme Linux amd64 / arm64 Durée ~2 minutes
bash 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

Générateur de commande

Composez votre commande d'installation

Docker Compose est présélectionné — une commande, base de données incluse. Les champs sont préremplis ; ne modifiez que le nécessaire. Le script reste disponible dans le second onglet.

Docker Compose

Déployez avec Docker Compose

Docker Compose est la méthode recommandée : une commande démarre le plan de contrôle, son agent intégré et PostgreSQL, avec données et certificats dans des volumes nommés. Une mise à jour ne change que le tag de l'image.

  • Docker Engine 24+ avec le plugin Compose v2 (docker compose, pas l'ancien binaire docker-compose).
  • Ports 80, 443, 9080 et 9090 libres sur l'hôte — ou remplacez-les dans les champs ci-dessous.
  • Aucune base de données externe requise : le fichier compose embarque son propre conteneur PostgreSQL 16 avec des volumes nommés.
  • Le tableau de bord sert HTTPS avec un certificat auto-signé au premier démarrage. Téléversez-en un vrai sous Paramètres → Control plane HTTPS, ou mettez TLS_ENABLED=false pour du HTTP simple.
Installation en une ligne 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

Lancez-la dans un répertoire vide : l'installateur télécharge docker-compose.yml, écrit un .env privé, récupère l'image et démarre la stack. Un .env existant n'est jamais écrasé — relancez la même commande pour mettre à jour.

  1. 1

    Lancez la commande

    Exécutez la commande ci-dessus dans un répertoire vide. L'installateur crée ./pingwaf, télécharge le compose et écrit un .env privé.

  2. 2

    Attendez la stack

    Compose récupère l'image, démarre PostgreSQL, attend son health check puis lance PingWAF. Le premier démarrage prend une à deux minutes.

  3. 3

    Connectez-vous

    Ouvrez https://<hôte>:9080 et utilisez ADMIN_EMAIL / ADMIN_PASSWORD (le mot de passe par défaut doit être changé à la première connexion), puis ajoutez un site.

Besoin de personnaliser ? Générez une commande avec options

Ne modifiez que le nécessaire ; la commande n'ajoute que les options différentes des valeurs par défaut. Le mot de passe administrateur n'est jamais écrit dans la commande.

Démarrer la pile 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

Première connexion : https://<votre-hôte>:9080 avec le ADMIN_EMAIL / ADMIN_PASSWORD ci-dessus (acceptez l'avertissement du certificat auto-signé jusqu'à en téléverser un vrai). Les agents joignent le plan de contrôle sur :9090.

Mise à niveau

Télécharge l'image du tag de votre .env et recrée le conteneur avec les mêmes volumes — configuration, données et certificats survivent au redémarrage. Épinglez le tag pour des mises à niveau maîtrisées.

bash 
docker compose pull && docker compose up -d
Terminal montrant docker compose up -d créant le réseau et les volumes, démarrant PostgreSQL et PingWAF puis affichant l'URL du tableau de bord
docker compose up -d télécharge l'image, démarre PostgreSQL, attend qu'il soit healthy et lance le tableau de bord.

Prérempli avec les valeurs par défaut de l'installateur — seules les valeurs que vous modifiez sont ajoutées à la commande.

Votre commande d'installation 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

Seules les valeurs différentes des valeurs par défaut sont ajoutées comme flags : le générateur intact produit donc la ligne la plus courte. Les arguments atteignent le script canalisé via bash -s --.

Installation interactive

Ou laissez l'installateur poser les questions

Lancez le script dans un terminal sans flags : il passe en revue le mode, les identifiants, la base de données et les noms de certificat, puis affiche le plan résolu pour confirmation.

  1. Choisissez le mode de déploiement

    1 all-in-one, 2 server ou 3 agent — appuyez sur Entrée pour accepter la valeur par défaut entre crochets.

  2. Renseignez les paramètres

    Les agents demandent l'URL du plan de contrôle et la clé d'enrôlement ; les modes server demandent le compte administrateur, l'URL PostgreSQL et les noms de certificat. Les secrets restent masqués pendant la saisie.

  3. Confirmez le résumé

    Avant d'écrire quoi que ce soit, l'installateur affiche le plan résolu — mode, version, plateforme, chemins, état systemd et URL de base de données masquée.

  4. Terminez et vérifiez

    Les modes server affichent la commande de démarrage ; les agents sont activés et démarrés automatiquement. Vérifiez le nœud sous Nodes dans le tableau de bord.

Le mode interactif nécessite un terminal local. Avec curl | bash, stdin est le script lui-même — téléchargez-le d'abord, puis lancez bash install.sh pour répondre aux questions.
Installateur interactif demandant le mode, le compte administrateur, l'URL PostgreSQL et les noms de certificat, puis affichant le plan d'installation
L'installateur interactif pose les questions dans l'ordre et affiche le plan résolu avant d'écrire quoi que ce soit.
Bannière de succès de l'installateur listant les chemins du binaire, de la configuration, des données et du service, plus les étapes suivantes
Une exécution réussie enregistre pingwaf.service et affiche où tout a été déposé.

Référence des flags

Les flags de l'installateur en un coup d'œil

Tous les flags acceptés par install.sh. Chacun possède un équivalent sous forme de variable d'environnement PINGWAF_*.

--mode

Mode de fonctionnement : all-in-one, server ou agent. Par défaut all-in-one.

--version

Installe une version précise (le v initial est retiré). Vide ou 'latest' résout la dernière publication GitHub.

--db-url

Chaîne de connexion PostgreSQL pour server/all-in-one. Par défaut postgres://pingwaf:pingwaf@localhost:5432/pingwaf.

--server-url

URL gRPC du plan de contrôle pour le mode agent. Utilisez https:// — gRPC est servi en TLS par défaut.

--api-key

Jeton d'enrôlement de l'agent. Peut aussi être fourni via PINGWAF_API_KEY pour ne pas figurer sur la ligne de commande.

--admin-email

E-mail de l'administrateur initialisé (server/all-in-one). Par défaut admin@pingwaf.local.

--admin-password

Mot de passe de l'administrateur initialisé (server/all-in-one). Vide conserve pingwaf123, que la console impose de changer à la première connexion.

--tls-sans

Noms d'hôtes séparés par des virgules que le certificat généré du tableau de bord doit couvrir.

--no-systemd

Ne pas créer l'unité systemd — pour les conteneurs, les mises à niveau ou vos propres superviseurs de processus.

--interactive / --non-interactive

Force les questions même lorsque des flags sont fournis, ou ne pose jamais de question et utilise les valeurs fournies plus les défauts. Canalisé sans flags, le script reste non interactif.

--dry-run

Affiche le plan résolu — mode, version, plateforme, chemins — puis quitte sans installer.

Manuel CLI sur GitHub

Dépannage

Quand l'installation ne se termine pas proprement

Les cinq échecs les plus fréquents au support, et la commande qui permet de cibler chacun.

L'installateur ne peut pas joindre PostgreSQL

Les modes all-in-one et server exigent PostgreSQL 14+ avant le premier démarrage. Le script avertit lorsque psql ne peut pas se connecter — installez le serveur, créez l'utilisateur et la base pingwaf (createuser / createdb), relancez l'installateur ou modifiez /etc/pingwaf/pingwaf.toml puis exécutez systemctl restart pingwaf.

bind() failed sur 0.0.0.0:80 ou :443

Le plan de données lie 80/443 sous l'utilisateur non privilégié pingwaf, ce qui ne fonctionne que parce que l'unité accorde CAP_NET_BIND_SERVICE. Si la liaison échoue encore, vérifiez systemctl show pingwaf -p AmbientCapabilities et ajoutez la capacité via un drop-in : sudo systemctl edit pingwaf → [Service] AmbientCapabilities=CAP_NET_BIND_SERVICE. Les unités écrites avant l'octroi de la capacité continuent d'échouer tant que le drop-in n'est pas ajouté.

Le binaire échoue avec une erreur de symbole glibc versionné

Les artefacts de publication sont compilés sur Ubuntu 24.04 et exigent glibc 2.39 ou plus récent. Sur des distributions plus anciennes (Debian 11, Ubuntu 20.04, CentOS/RHEL, Alpine, …), le test de fumée de l'installateur s'arrête avec un message clair — compilez depuis les sources à la place.

Le service systemd ne démarre pas

Inspectez le journal de l'unité avec journalctl -u pingwaf -e et vérifiez /etc/pingwaf/pingwaf.toml. Il n'y a pas de rechargement : appliquez toute modification avec systemctl restart pingwaf puis contrôlez avec systemctl status pingwaf.

Le conteneur ne démarre pas avec "bind() failed on 0.0.0.0:443" / Permission denied

L'image accorde déjà CAP_NET_BIND_SERVICE au binaire au moment de la compilation, donc l'utilisateur non privilégié pingwaf peut lier 80/443 en mode bridge avec un simple docker run ou docker compose up -d. Si cela échoue encore, le runtime a supprimé les capacités de fichier — ajoutez --cap-add=NET_BIND_SERVICE (le fichier compose fourni définit déjà cap_add) ou passez en réseau host network_mode: host (commentez alors ports: et networks: ; 9080/9090 écoutent directement sur l'hôte). Vérifiez avec docker exec pingwaf getcap /usr/local/bin/pingwaf (attendu : cap_net_bind_service=ep) et docker exec pingwaf id -u (non nul). Détails complets : https://github.com/shuaiZend/PingWAF/blob/main/docs/deployment.md#binding-ports-80443-in-containers

Installé ? Ajoutez maintenant votre premier site.

La documentation couvre le modèle de site, les topologies distribuées, la priorité de configuration et la référence complète des variables d'environnement.

Lire la documentation Releases sur GitHub