クイックスタート

このページは、導入済みのホストから自分で制御できるサーバーまで進みます。ディスク上の設定、検証済みのコンパイル、起動・停止・監視できるサーバー、そしてファイルサーバーが応答したことを示す確認です。インストールが済んでいることを前提にします。

🧾 はじめる前に

インストーラはポート 80 でサービスを動かしたままにしており、そのサービスが /etc/Pingclair/Pingclairfile の設定を握っています。試している間は停止してポートを空けます。

sudo pc service stop

mkdir -p ~/demo/public
cd ~/demo
echo '<h1>hello from ~/demo/public</h1>' > public/index.html

1. ✍️ 設定を書く

~/demo/Pingclairfile を作ります。

{
    admin 127.0.0.1:2019
}

http://localhost:8080 {
    file_server ./public
}

三点だけ名前を付けておきます。先頭の無名ブロックはグローバルオプションで、 admin があると pingclair start、stop、reload が実行中のサーバーと話せます。サイトアドレスはスキームを含み、http:// が平文を強制します。これが無いと Pingclair は localhost を名前として扱い、独自の認証局で HTTPS を提供するため、平文の HTTP クライアントには空の応答として見えます（HTTPS）。file_server のルートは作業ディレクトリからの相対パスです。

2. ✅ 実行前に検証する

pingclair validate

✅ Configuration 'Pingclairfile' is valid!

validate は既定で ./Pingclairfile を読み、./Caddyfile も検出します。設定をコンパイルし、証明書パスの有無といった意味的な検査を適用します。検証は助言ではありません。失敗した設定は実行されず、最後の行に理由が出ます。

3. 🧭 設定が何になるかを読む

pingclair adapt --pretty

{
  "debug": false,
  "servers": [
    {
      "name": "localhost",
      "names": [
        "localhost"
      ],
      "listen": [
        "[::]:8080"
      ],

コンパイル済みの JSON はサーバーが実際に実行する形です。ディレクティブがドキュメントどおりに動かないとき、最初に見る場所がここです。代わりに pingclair fmt がファイルに加える変更を見るには次のようにします。

pingclair fmt --diff

-    file_server ./public
+  file_server ./public

fmt は正規形を出力し、インデントは 2 スペースになります。

4. 🚀 起動する

ログが端末に残るフォアグラウンドで実行します。

pingclair run Pingclairfile

🚀 Starting Pingclair with config: Pingclairfile
🚀 Starting Pingclair v0.2.0-rc.3
📄 Loaded configuration from: Pingclairfile
🔧 Configured 1 server(s)
🔐 Auto HTTPS: enabled

--watch を付けると保存のたびに設定が再読み込みされ、開発ループになります。

pingclair run --watch Pingclairfile

♻️ Configuration reloaded successfully
✅ Configuration reloaded completed successfully in 2.478622ms

シェルから切り離してバックグラウンドで動かすこともできます。

pingclair start -c Pingclairfile

✅ Pingclair started in the background (pid 4432)

pingclair start、stop、reload は Admin API 経由で実行中のサーバーに到達します。上の設定に admin があるのはそのためです。pingclair run には必要ありません。

5. 🔍 確認する

curl -i http://localhost:8080/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 34
Last-Modified: Tue, 22 Sep 2026 03:26:39 GMT
ETag: "22-6ab1f56f"
Vary: Accept-Encoding
Accept-Ranges: bytes
server: Pingclair

ETag と Last-Modified はファイルサーバーがディスクから読んだ証拠です。本文は public/index.html です。バックグラウンドのサーバーを止めるには次のようにします。

pingclair stop

✅ Pingclair stopped

⚡ コマンド一発のサーバー

三つのサブコマンドは設定ファイルなしで配信します。試したいときや使い捨てのホストで便利です。

pingclair file-server --listen :8081 --root ./public
pingclair reverse-proxy --from :8082 --to 127.0.0.1:8081
pingclair respond --listen :8083 -s 200 -b "hello from respond"

それぞれ起動時にリスナーを表示します。

🚀 Starting file server on :8081 serving ./public (browse: false)
🚀 Starting reverse proxy: :8082 -> ["127.0.0.1:8081"]
Server address: [::]:8083

:8082 へのリクエストは :8081 のファイルサーバーへ転送され、:8083 は渡した本文をそのまま返します。respond は開発専用です。

🔁 サービスに任せる

サービスは /etc/Pingclair/Pingclairfile を実行するので、そこに置くと再起動後も生き残ります。

sudo cp Pingclairfile /etc/Pingclair/Pingclairfile
sudo pingclair validate /etc/Pingclair/Pingclairfile
sudo pc service reload
curl -i http://localhost/

pc service reload は実行中のサーバーにファイルを読み直すよう求め、ユニットはそれを SIGUSR1 で行います。pingclair reload は Admin API 経由で同じコードに到達し、サーバーがファイルをどう見たかも報告します（グローバルオプションの admin が必要です）。sudo kill -USR1 "$(systemctl show -p MainPID --value pingclair)" はどちらも使わずに同じことをします。

どちらの場合も先に検証し、そのあと答えを読みます。systemctl reload が報告できるのは信号が届いたことだけなので、サーバーの判断——適用されたか、理由付きで拒否されたか——はユニットの status line とジャーナルに残ります。拒否された再読み込みは以前の設定を動かしたままにします。それが拒否の目的です。サービスとして動かすに詳しい説明があります。

⚠️ うまくいかないとき

Address already in use。 インストーラのサービスがまだ :80 を握っているか、別のプロセスがそのポートを握っています。 sudo ss -ltnp | grep :80 が持ち主を表示し、sudo pc service stop が既定のサービスを解放します。
http://localhost:8080 で Empty reply from server。 平文で TLS のリスナーに話しかけています。サイトアドレスに http:// を付けるか、内部証明書を信頼したうえで https:// で話しかけます。
Cannot reach admin API at 127.0.0.1:2019。 設定に admin が無く、 pingclair stop と pingclair reload を受け取る相手がいません。グローバルオプションのブロックに追加するか、フォアグラウンドのプロセスを Ctrl-C で止めます。
curl がループバックで固まる。 システムのプロキシが要求を横取りしています。curl --noproxy '*' を付けて再実行します。
検証が Unsupported feature で失敗する。 ディレクティブは認識されていますが実装が無く、メッセージが代替を示します。encode br の場合、プロキシ応答に Brotli は実装されていないため encode zstd gzip を指します。

🧭 次の手順

HTTPS: 公開名に対する証明書を Let’s Encrypt か内部認証局から。
サービスとして動かす: ユニット、再読み込みの意味、ログ。
Pingclairfile: 言語そのもの。マッチャー、スニペット、インポート。

🏃クイックスタート