PingWAF WAF
日本語
English EN 简体中文 ZH Español ES Français FR 日本語 JA
GitHub
概要 機能 クイックスタート インストール ドキュメント GitHub ↗

インストール

1 コマンドでゼロから稼働ノードまで

Docker Compose を推奨します。1 コマンドでコントロールプレーン、内蔵エージェント、PostgreSQL を起動します。systemd 管理のバイナリが必要な場合はスクリプトインストールを利用できます。

実行 1 コマンド モード all-in-one · server · agent プラットフォーム Linux amd64 / arm64 所要時間 約 2 分
bash 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

コマンドビルダー

インストールコマンドを組み立てる

Docker Compose を既定で選択しています。1 コマンドでデータベース込みで起動します。項目は既定値が入っているので、変更が必要な箇所だけ編集してください。スクリプトインストールは 2 つ目のタブにあります。

Docker Compose

Docker Compose でデプロイ

Docker Compose が公式推奨です。1 コマンドでコントロールプレーン、内蔵エージェント、PostgreSQL を起動し、データと証明書は名前付きボリュームに保存します。更新はイメージタグの変更だけです。

  • Docker Engine 24+ と Compose v2 プラグイン（docker compose。旧 docker-compose コマンドではない）。
  • ホストの 80・443・9080・9090 ポートが空いていること — または下のフィールドで変更できます。
  • 外部データベースは不要：compose ファイルには PostgreSQL 16 コンテナが同梱され、名前付きボリュームで永続化されます。
  • ダッシュボードは初回起動時、自己署名証明書で HTTPS を提供します。「設定 → Control plane HTTPS」から正式な証明書をアップロードするか、TLS_ENABLED=false で平文 HTTP にできます。
ワンコマンドインストール 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

空のディレクトリで実行してください。インストーラは docker-compose.yml を取得し、本人のみ読み取り可能な .env を書き込み、イメージを取得して起動します。既存の .env は上書きしません（アップグレードは同じコマンドを再実行）。

  1. 1

    ワンコマンドを実行

    空のディレクトリで上のコマンドを実行します。インストーラが ./pingwaf を作成し、compose ファイルを取得して私有 .env を書き込みます。

  2. 2

    起動を待つ

    Compose がイメージを取得し、PostgreSQL を起動してヘルスチェック後に PingWAF を起動します。初回は 1〜2 分かかります。

  3. 3

    コンソールにログイン

    https://<ホスト>:9080 を開き、ADMIN_EMAIL / ADMIN_PASSWORD でログインします（既定パスワードは初回ログイン時に変更が必須）。その後サイトを追加します。

カスタマイズする場合：オプション付きコマンドを生成

変更が必要な項目だけ入力してください。既定値と異なるオプションだけが追加されます。管理者パスワードはコマンドに含めません。

スタックの起動 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

初回ログイン：https://<ホスト>:9080 に上記の ADMIN_EMAIL / ADMIN_PASSWORD でサインイン（正式な証明書をアップロードするまで自己署名の警告を受け入れてください）。Agent は :9090 でコントロールプレーンに接続します。

アップグレード

.env のタグのイメージを取得し、同じボリュームでコンテナを再作成します — 設定・データ・証明書は再起動後も保持されます。計画的なアップグレードにはタグを固定してください。

bash 
docker compose pull && docker compose up -d
docker compose up -d がネットワークとボリュームを作成し、PostgreSQL と PingWAF を起動してダッシュボード URL を表示するターミナル
docker compose up -d はイメージを取得し、PostgreSQL を起動して healthy になるのを待ち、ダッシュボードを起動します。

インストーラーの既定値で事前入力済み — 変更した値だけがコマンドに追加されます。

生成されたインストールコマンド 
curl -fsSL https://raw.githubusercontent.com/shuaiZend/PingWAF/main/deploy/compose/install.sh | bash

既定値と異なる値だけがフラグとして追加されるため、未編集のままでは最短のワンライナーが生成されます。引数は bash -s -- でパイプ先のスクリプトに渡されます。

対話式インストール

あるいはインストーラーに質問させる

フラグなしでターミナルからスクリプトを実行すると、モード・認証情報・データベース・証明書名を順に尋ね、確定した計画を表示して確認を待ちます。

  1. デプロイモードを選ぶ

    1 all-in-one、2 server、3 agent — Enter で括弧内の既定値を受け入れます。

  2. パラメーターを入力する

    agent はコントロールプレーン URL と登録キーを、server モードは管理者アカウント・PostgreSQL URL・証明書名を尋ねます。シークレットは入力中も表示されません。

  3. サマリーを確認する

    何かを書き込む前に、インストーラーは確定済みの計画（モード・バージョン・プラットフォーム・パス・systemd の状態・マスク済みのデータベース URL）を表示します。

  4. 完了して確認する

    server モードは起動コマンドを表示し、agent は自動で有効化・起動されます。ダッシュボードの「ノード」でノードを確認してください。

対話モードにはローカルターミナルが必要です。curl | bash の場合、stdin はスクリプト自身です — 先にスクリプトをダウンロードし、bash install.sh として実行して質問に答えてください。
モード・管理者アカウント・PostgreSQL URL・証明書名を順に尋ね、最後にインストール計画を表示する対話式インストーラー
対話式インストーラーは順に質問し、何かを書き込む前に確定済みの計画を表示します。
バイナリ・設定・データ・サービスのパスと次のステップを列挙したインストール成功バナー
正常に完了すると pingwaf.service が登録され、各ファイルの配置先が表示されます。

フラグ早見表

インストーラーのフラグ一覧

install.sh が受け付けるすべてのフラグ。それぞれに対応する PINGWAF_* 環境変数があります。

--mode

動作モード：all-in-one、server、agent。既定は all-in-one です。

--version

指定バージョンをインストールします（先頭の v は取り除かれます）。空欄または 'latest' で最新の GitHub リリースを解決します。

--db-url

server/all-in-one 用の PostgreSQL 接続文字列。既定は postgres://pingwaf:pingwaf@localhost:5432/pingwaf です。

--server-url

agent モード用のコントロールプレーン gRPC URL。https:// を使ってください — gRPC は既定で TLS で提供されます。

--api-key

Agent の登録トークン。コマンドラインに残さないため PINGWAF_API_KEY として渡すこともできます。

--admin-email

初期投入される管理者メールアドレス（server/all-in-one）。既定は admin@pingwaf.local です。

--admin-password

初期投入される管理者パスワード（server/all-in-one）。空欄なら pingwaf123 が使われ、コンソールが初回ログイン時に変更を強制します。

--tls-sans

生成されるダッシュボード証明書がカバーすべきホスト名をカンマ区切りで指定します。

--no-systemd

systemd ユニットの作成をスキップします — コンテナ・アップグレード・手動のプロセス管理向けです。

--interactive / --non-interactive

フラグがあっても質問を強制する、または一切質問せず指定値と既定値で実行します。フラグなしのパイプ実行は非対話のままです。

--dry-run

確定済みの計画（モード・バージョン・プラットフォーム・パス）を表示して、インストールせずに終了します。

GitHub の CLI マニュアル

トラブルシューティング

インストールがきれいに終わらないとき

サポートで最もよく見られる 5 つの失敗と、それぞれを特定するためのコマンド。

インストーラーが PostgreSQL に接続できない

all-in-one と server モードは初回起動前に PostgreSQL 14+ が必要です。psql が接続できない場合スクリプトは警告を出します — サーバーをインストールし、pingwaf ユーザーとデータベースを作成し（createuser / createdb）、インストーラーを再実行するか、/etc/pingwaf/pingwaf.toml を編集して systemctl restart pingwaf を実行してください。

0.0.0.0:80 や :443 で bind() failed になる

データプレーンは非特権ユーザー pingwaf として 80/443 をバインドします。これはユニットが CAP_NET_BIND_SERVICE を付与しているからこそ機能します。それでもバインドに失敗する場合は、systemctl show pingwaf -p AmbientCapabilities で確認し、drop-in で能力を追加してください：sudo systemctl edit pingwaf → [Service] AmbientCapabilities=CAP_NET_BIND_SERVICE。付与前に書かれた古いユニットは、drop-in を追加するまで失敗し続けます。

バイナリがバージョン付き glibc シンボルのエラーで失敗する

リリース成果物は Ubuntu 24.04 でビルドされており、glibc 2.39 以上が必要です。より古いディストリビューション（Debian 11、Ubuntu 20.04、CentOS/RHEL、Alpine など）ではインストーラーのスモークテストが明確なメッセージとともに停止します — 代わりにソースからビルドしてください。

systemd サービスが起動しない

journalctl -u pingwaf -e でユニットのログを確認し、/etc/pingwaf/pingwaf.toml を見直してください。リロードはありません。変更は systemctl restart pingwaf で適用し、その後 systemctl status pingwaf で確認します。

コンテナの起動が "bind() failed on 0.0.0.0:443" / Permission denied で失敗する

イメージはビルド時にバイナリへ CAP_NET_BIND_SERVICE を付与済みのため、デフォルトのブリッジモードでは非特権ユーザー pingwaf が通常の docker run や docker compose up -d で 80/443 をバインドできます。それでも失敗する場合は、実行環境がファイル能力を剥奪しています — --cap-add=NET_BIND_SERVICE を追加するか（同梱の compose ファイルにはすでに cap_add が設定されています）、host ネットワーク network_mode: host に切り替えてください（その場合は ports: と networks: の両方をコメントアウトし、9080/9090 はホスト上で直接リッスンします）。docker exec pingwaf getcap /usr/local/bin/pingwaf（cap_net_bind_service=ep と表示されるはずです）と docker exec pingwaf id -u（非ゼロ）で確認できます。詳細：https://github.com/shuaiZend/PingWAF/blob/main/docs/deployment.md#binding-ports-80443-in-containers

インストール完了。次は最初のサイトを追加しましょう。

ドキュメントでは、サイトモデル、分散トポロジー、設定の優先順位、環境変数の完全なリファレンスを解説しています。

ドキュメントを読む GitHub Releases