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

Démarrage

En marche en cinq minutes, protégé en dix

Deux chemins officiels : la pile compose fournie pour évaluer, ou une compilation maison pour la production.

Voie A Docker Compose Voie B Compiler Temps ~5 minutes Stockage PostgreSQL 14+

Avant de commencer

La voie compose ne demande que Docker ; compiler exige Rust, Node et protoc.

Docker

Engine 24+ avec Compose v2

Démarre le plan de contrôle, un agent et PostgreSQL.

PostgreSQL

14+ (16 recommandé)

Le plan de contrôle y stocke sites, règles et versions.

Ports

9080 · 9090 · 80 · 443

9080 sert l'API et la console, 9090 le plan gRPC.

TLS

Auto-signé au premier démarrage

Remplacez-le ou faites-lui confiance avant d'exposer la console.

Démarrage

Docker Compose

Le compose démarre PingWAF en mode all-in-one à côté de PostgreSQL avec l'image publiée.

  1. Clonez le dépôt

    Le compose et le TOML d'exemple sont à la racine du dépôt.

    bash 
    git clone https://github.com/shuaiZend/PingWAF.git
cd PingWAF

  2. Démarrez la pile

    Définissez JWT_SECRET et ADMIN_PASSWORD si l'hôte est joignable de l'extérieur.

    bash 
    export JWT_SECRET="$(openssl rand -hex 32)"
export ADMIN_PASSWORD="$(openssl rand -hex 16)"
docker compose up -d

  3. Ouvrez la console

    La console sert du HTTPS avec un certificat auto-signé généré au premier démarrage ; le navigateur alertera jusqu'à ce que vous le remplaciez.

    bash 
    curl --connect-timeout 2 --max-time 3 http://localhost:9080/healthz
# {"status":"ok","database":"up"}

  4. Ajoutez un premier site

    Créez un site avec le domaine pointé vers l'agent, puis activez uniquement les protections voulues.

Les binaires publiés ciblent Linux amd64/arm64 ; l'image Docker couvre les deux.
localhost:9080/sites
Liste des sites dans la console avec trafic et état de protection
La liste des sites est le point de départ : une ligne par domaine.

Démarrage

Compiler depuis les sources

Utile pour une compilation sur mesure ou un binaire auditable.

  1. Installez la chaîne d'outils

    protoc est obligatoire : sans lui, le crate proto bascule sur des fichiers factices et la compilation échoue.

    bash 
    # macOS
brew install protobuf

# Debian / Ubuntu
sudo apt install protobuf-compiler cmake

  2. Compilez la console

    La console est embarquée dans le binaire, elle doit donc être compilée en premier.

    bash 
    cd web && npm ci && npm run build && cd ..

  3. Compilez le binaire

    La feature full inclut le moteur WAF, les défis et l'automatisation des certificats.

    bash 
    cargo build --release --bin pingwaf --features full

  4. Lancez en all-in-one

    Pointez vers une instance PostgreSQL ; le schéma est créé au premier démarrage.

    bash 
    ./target/release/pingwaf all-in-one \
  --db-url "postgres://pingwaf:pingwaf@localhost:5432/pingwaf"
Sur Linux, install.sh (--mode all-in-one) évite la compilation.
localhost:9080/agents
Page des agents avec les nœuds de périphérie enrôlés et leur heartbeat
Une compilation maison peut servir de plan de contrôle puis enrôler des agents.

Première connexion

Le plan de contrôle crée un administrateur au premier démarrage, et la console impose un changement de mot de passe.

defaults.env

Console https://localhost:9080
E-mail admin@pingwaf.local
Mot de passe pingwaf123
Secret JWT ≥ 16 caractères

Changez les valeurs par défaut avant toute exposition

PINGWAF_JWT_SECRET et PINGWAF_ADMIN_PASSWORD ont des valeurs fonctionnelles. Définissez-les, passez PINGWAF_ALLOW_REGISTRATION à false et gardez 9080 sur un réseau privé ou un VPN.
bash 
export PINGWAF_JWT_SECRET="$(openssl rand -hex 32)"
export PINGWAF_ADMIN_PASSWORD="$(openssl rand -hex 16)"
export PINGWAF_ALLOW_REGISTRATION=false
localhost:9080/login
Page de connexion PingWAF avec champs e-mail et mot de passe
Connectez-vous avec le compte administrateur initial ; les passkeys s'ajoutent ensuite.

Étapes suivantes

Une fois le plan de contrôle joignable, tout le reste est de la configuration.

Créez un site

Un site relie un domaine aux pools d'origine, aux routes et aux protections activées.

Modèle de site

Connectez des agents

Lancez pingwaf server sur le nœud de contrôle et pingwaf agent sur chaque nœud de périphérie ; ils s'enregistrent sur gRPC :9090.

Déploiement distribué

Activez les protections

Activez le moteur WAF, le bouclier CC ou la politique anti-bots par site : rien ne s'applique avant.

Capacités

Exportez les journaux

Envoyez les journaux vers Elasticsearch et conservez les captures dans PostgreSQL pour rejouer.

Observabilité

Si le démarrage échoue

La compilation échoue dans pingwaf-proto

protoc manque. Installez protobuf-compiler (ou brew install protobuf) puis recompilez : sans lui le crate utilise des fichiers factices.

Le navigateur refuse le certificat

La console utilise HTTPS avec un certificat auto-signé. Faites confiance au certificat téléchargé ou importez le vôtre via Réglages → HTTPS du plan de contrôle ; renseignez PINGWAF_TLS_SANS.

Un agent n'apparaît jamais

Vérifiez qu'il atteint le plan gRPC sur :9090 (PINGWAF_SERVER_URL) et qu'aucun pare-feu ni proxy TLS ne l'en empêche.

Le port 443 reste fermé

443 n'ouvre qu'après l'émission ou l'import d'un certificat ; avant cela l'agent ne sert qu'en HTTP sur 80.

Besoin de la version longue ?

Les documents déploiement et architecture couvrent systemd, les topologies distribuées, la précédence de configuration et toutes les variables d'environnement.

Guide de déploiement GitHub