インストール

Pingclair は単一の Linux バイナリとして配布されます。このページでは導入し、インストーラが何を残したかを示し、サーバーが応答することを確認します。現在のリリースは v0.2.0-rc.3（リリース候補）で、このサイトの全ページがそのリリースを説明しています。

🧾 必要なもの

x86_64 または aarch64 の Linux ホスト。どちらにもリリースバイナリが公開されています。
sudo または root。インストーラは /usr/local/bin、/etc/Pingclair、 /var/lib/pingclair、/etc/systemd/system に書き込みます。
サービスとして動かす場合は systemd。ない場合は Docker か、フォアグラウンドでの起動を使います（どちらも以下で扱います）。
公開証明書が必要なら、インターネットから 80 と 443 に到達できること（HTTPS）。クラウドのインスタンスでは、プロバイダ側のファイアウォールも開ける必要があります。

macOS でのソースビルドは開発用にサポートされます。macOS は出荷対象ではありません。

📦 リリースバイナリからのインストール

curl -fsSL https://pingclair.com/install.sh | sudo bash

スクリプトは releases.pingclair.com のリリースチャネルを読み、導入しようとしているタグを表示し、そのチャネルが公開している SHA-256 とアーカイブを照合します——一致しないアーカイブは展開せずに拒否します。このホストに到達できない場合は GitHub のリリース API とアーカイブの隣に公開されているチェックサムファイルに退避するので、導入が一つの提供元に依存しません。続いてサービス用ユーザーを作成し、低いポートにバインドする権限を与え、既定の設定を書き、ユニットを導入してサービスを開始します。最後まで進むと次のように終わります。

Detected architecture: x86_64
Installing v0.2.0-rc.3 — a release candidate, not a final release.
Downloading https://releases.pingclair.com/pingclair/releases/0.2.0-rc.3/pingclair-linux-x86_64.tar.gz (from releases.pingclair.com)...
✅ sha256 matches the release channel document
Creating system user 'pingclair'...
Setting capabilities...
Configuring directories and assets...
Fetching default landing page...
Creating default Pingclairfile...
Installing Systemd service...
Creating 'pc' symlink...
✅ Installation Complete!
Use pc service status to check the service.
Config: /etc/Pingclair/Pingclairfile

未リリースの修正が必要なときは、リリースバイナリではなく main を導入します。

curl -fsSL https://pingclair.com/install.sh | sudo bash -s -- --main

--main はホスト上でクローンしてコンパイルします。Rust 1.98 以降と、 BoringSSL と jemalloc が必要とする C ツールチェーン（cmake、clang、 libclang-dev、g++、git）が要ります。これらのパッケージは apt でも dnf でもスクリプトが導入します。BoringSSL をソースからビルドするため、初回は数分かかります。

🗂️ インストーラが残したもの

パス	内容
`/usr/local/bin/pingclair`	サーバーのバイナリ。
`/usr/local/bin/pc`	同じバイナリへのシンボリックリンク（短い名前）。
`/etc/Pingclair/Pingclairfile`	サービスが実行する設定。
`/etc/Pingclair/Pingclairfile.example`	コメント付きの例。アップグレードでも上書きされません。
`/var/lib/pingclair/.local/share/pingclair`	証明書ストア。サービスアカウントのデータディレクトリで、バイナリの既定です。
`/var/lib/pingclair/html`	ポート 80 で配信される案内ページ。
`/var/log/pingclair`	`log` シンクを設定したときに書き出される場所。
`/etc/systemd/system/pingclair.service`	有効化され、起動済みのユニット。

スクリプトが終わった時点でサービスはすでに応答しています。動いている設定は案内用のもので、1 画面に収まります。

# 🦀 Pingclair default configuration file
# Management commands: pc service <start|stop|reload|status>

:80 {
    # Welcome page
    file_server /var/lib/pingclair/html
}

サービス用ユーザーと証明書ストアは存在しないときだけ作られ、既存の /etc/Pingclair/Pingclairfile が置き換わることはありません。だからこそインストーラの再実行は初期化ではなくアップグレードになります（アップグレードと削除）。

✅ インストールの確認

バイナリにバージョンを尋ねます。

pingclair version

v0.2.0-rc.3

pc は同じバイナリなので、pc version も同じ文字列を出力します。次に systemd に尋ねます。

pc service status

● pingclair.service - Pingclair High-Performance Web Server
     Loaded: loaded (/etc/systemd/system/pingclair.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-09-22 03:21:55 UTC; 42s ago
       Docs: https://github.com/dorianverlaine/pingclair
   Main PID: 1808 (pingclair)
     Status: "Serving"
      Tasks: 12 (limit: 627)
     Memory: 8.2M (peak: 8.5M)

Status: "Serving" は systemd がプロセスの生存から推測したものではなく、サーバー自身が送ったものです。ユニットは notify 型で、すべてのリスナーがバインドされたあとに初めて準備完了を通知します。

最後にサーバー自身に尋ねます。

curl -i http://localhost/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 18747
Last-Modified: Tue, 22 Sep 2026 03:21:54 GMT
ETag: "493b-6ab1f452"
Vary: Accept-Encoding
Accept-Ranges: bytes
server: Pingclair

ETag と Last-Modified を伴う 200 はファイルサーバーが応答した証拠で、本文は /var/lib/pingclair/html の案内ページです。

🐳 Docker

公開イメージは設定ファイルモードで動きます。entrypoint は pingclair、既定のコマンドは run /etc/pingclair/Pingclairfile です。イメージは /etc/pingclair と /var/lib/pingclair をボリュームとして宣言し、80 と 443 を公開します。

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:v0.2.0-rc.3
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3
    volumes:
      - ./conf:/etc/pingclair:ro
      - ./site:/srv:ro
      - pingclair_tls:/var/lib/pingclair

volumes:
  pingclair_tls:

mkdir -p conf site
printf ':80 {\n    file_server /srv\n}\n' > conf/Pingclairfile
echo '<h1>hello from the container</h1>' > site/index.html
docker compose up -d
curl -i http://localhost/

間違えやすい点が三つあります。

command: を足さないこと。 イメージの既定はすでに run /etc/pingclair/Pingclairfile で、上書きするとそのコマンドが置き換わります。
/var/lib/pingclair/.local/share/pingclair だけをマウントしないこと。 ストアは証明書ディレクトリの隣にも状態を置くので、certs だけをマウントしてコンテナを作り直すとそれが失われます。/var/lib/pingclair をマウントします。
公開タグを固定すること。 latest は最新リリースを追いかけます。本番は例のようにバージョンを指定します。公開タグはパッケージページに並んでいます。

利用者が docker グループに入っていないホストではコマンドに sudo を付け、または一度 sudo usermod -aG docker "$USER" でグループに加わり、新しいログインセッションを開きます。Ubuntu では docker compose プラグインは docker-compose-v2 パッケージに入っています。

🛠️ ソースからのビルド

git clone https://github.com/dorianverlaine/pingclair
cd pingclair
cargo build --release

必要環境: Rust 1.98.1（CI が固定している版）、cmake、clang、 libclang-dev、g++、git。ビルドの一部として BoringSSL をソースからコンパイルするため、初回は数分かかります。

⚠️ インストールが失敗したとき

This script must be run as root。 スクリプトはホームディレクトリの外に書き込み、ユニットを導入します。sudo を付けて再実行します。
Fedora で setcap: command not found。 それは libcap パッケージです。インストーラは導入しますが、手作業で組んだホストには無いことがあり、その権限がないと 80 と 443 にバインドできません。
インストール直後に Job for pingclair.service failed。 journalctl -u pingclair -n 20 を読みます。よくある原因は、検証を通らない設定か、すでにポート 80 を掴んでいる別のプロセスです。
サービスは動いているのに外から何も返らない。 リスナーはバインド済みで、パケットが届いていません。まずプロバイダのファイアウォールやセキュリティグループ、次にホスト側の規則を確認します。
ホストに systemd がない。 バイナリは導入され使えますが、インストーラのサービス手順は実行できません。Docker か pingclair run を使います。

🧹 削除する

アップグレードと削除に手順と、残しておく価値のあるデータが入ったディレクトリをまとめてあります。

🧭 次の手順

クイックスタート: 案内ページを自分の設定に置き換え、実際のサイトを配信します。
HTTPS: 公開名に対する証明書。
サービスとして動かす: ユニットの役割と安全な再読み込み。

📦インストール