1. クイックスタート（docker compose）

リポジトリの docker-compose.example.yml（各リリースに添付されるので、取得した copy はそのリリースのイメージと一致します） が、2 つのコンテナと仮の upstream を配線しています。用意するものはありません:

curl -fsSL -o docker-compose.example.yml https://unmask.sh/dl/docker/docker-compose.yml
docker compose -f docker-compose.example.yml up -d
docker compose -f docker-compose.example.yml logs admin | grep "setup token"

https://localhost/unmask/admin/ を開きます。初回起動は admin が生成した自己署名証明書を配信するのでブラウザが一度警告します （いったん受け入れてください）。管理画面もサイトと同じ保護の内側にあるので、次に短い security check が表示され、通過するとインストール ウィザードが続きます。ログのセットアップトークンを貼り、SQLite（既定）か自分の DB を選び、管理者ユーザーを作れば完了。 あとは 設定 → Gateway で、転送先 (upstream)・応答するホスト名・本番の証明書（Let's Encrypt / 貼り付け / mount したファイル）を設定します。

管理画面で変更した設定は共有 volume に描画され、nginx コンテナがファイルの変化を数秒以内に検知して自分で reload します。 事前に nginx -t を通すので、解釈できない描画があればログに残してスキップし、稼働中の設定はそのまま保ちます。手で実行するものはありません。 自分のタイミングで reload したい場合は UNMASK_AUTORELOAD=0 で watcher を止められます。

2. gateway モード: 任意の HTTP サーバーの前段に

UNMASK_GATEWAY=1 にすると、nginx コンテナが :443 で TLS を終端し（クライアントの ClientHello を直接見るので JA4 が取れます）、 チャレンジ判定を行い、通過したリクエストを upstream へ proxy します。アプリ側には何もインストールしません。 配信しているものが Node でも Rails でも Go でも Apache でも別の nginx でも、静的ファイルサーバーでも構いません。

gateway の設定は管理画面の 設定 → Gateway にあります: 転送先 (upstream)（Docker ホスト上のサーバーなら http://host.docker.internal:8080、別ホストなら http://10.0.0.5:8080、同じ compose 内のコンテナなら http://app:3000）、応答するホスト名、証明書。前段ロードバランサーの信頼するプロキシは 設定 → Network → 信頼する LB / CDN （GCP / Cloudflare などの preset あり）で、JA4 header を信頼する相手と同じ集合です。転送先が未設定の間、gateway はその旨の案内ページを返します。同じホストで動いているサーバーを転送先にする場合は、:80/:443 を gateway に譲って自分のサーバーを 8080 へ移します (Apache は Listen 8080、nginx は listen 8080;)。コンテナから届くアドレスに bind する必要があるので 127.0.0.1 は不可、8080 は firewall で外から閉じておきます。compose ファイルには host.docker.internal がホストを指す設定が最初から入っています。下の環境変数は初回起動時にタブへ 流し込むだけです（nginx サービス側の UNMASK_UPSTREAM / UNMASK_TRUSTED_PROXIES は、タブが空の間のフォールバックとして引き続き効きます）。

ホスト名と証明書

どちらも管理画面の 設定 → Gateway で、互いに独立した 2 つの問いとして設定します。どのホスト名に応答するか: すべて（Host をそのまま upstream に渡す。upstream 側が複数サイトを持つ場合向け）か、指定したリストか — リストにない Host は TLS ハンドシェイクの段階で拒否します。どの証明書を持つか: 証明書ごとに 1 エントリで、入手元と「どのドメインの証明書か」を 持ちます。nginx は SNI で証明書を選び、1 枚目が既定としてどの証明書のドメインにも一致しないホスト名に配信されます（リストのホスト名に 証明書が無ければタブが警告します）。つまり 1 つの gateway で複数サイト・複数証明書を扱え、ホスト名を変えても証明書には触れません。 各証明書には :443 がその最初のドメインに実際に配信している証明書（発行者・有効期限・名前の一致）も表示されます。 入手元は 3 つ:

• 自動（Let's Encrypt） — ドメインと連絡先メールアドレスを入れるだけで gateway が TLS を自分で面倒みます。 公式 nginx イメージには nginx 純正の ACME モジュールが同梱されているので、エントリの全ドメインをカバーする 1 枚の証明書を :80 の http-01 チャレンジで取得し、その場で更新し続けます。クライアントも cron も sidecar も要りません。アカウントは初回取得時に自動作成され （事前登録は不要）、連絡先とディレクトリは全エントリで共通です。条件は 2 つ: ドメインがこのホストに解決し、:80 がインターネットから到達できること。そして /var/cache/nginx/unmask-acme の volume を残すこと（アカウント鍵と証明書が入っています。失うと再発行になり、 Let's Encrypt のレート制限に当たります）。設定が固まるまでは staging を使ってください。
• 証明書を貼り付け — 購入した証明書向け。証明書、CA から渡されていれば中間証明書チェーン、秘密鍵を貼り付けます。 鍵と証明書の対応と有効期限を確認したうえで 共有 volume の /etc/unmask に保存され、鍵は他のユーザーから読めない権限になります。 鍵は二度と画面に表示されず、ドメインは証明書の SAN から読み取られます。更新は新しい組を貼り直すだけです。
• ファイル — nginx コンテナ上のパス。別の仕組みで更新し続けている証明書を使う場合（/etc/unmask/tls に mount）。 compose 例のように同じディレクトリを admin サービスにも mount しておくと、対象ドメインは証明書から自動で読み取られます。 mount していない場合は、証明書が複数あるときだけこの証明書のドメインを指定します (nginx が SNI で選ぶため。1 枚だけなら不要)。
• 自己署名 — 何も設定していない初回起動が配信するもの。admin が生成した組（応答するホスト名、無ければ localhost 宛）で、 最初から https で管理画面に入れます。ブラウザは警告するので、上のいずれかに切り替えてください。
• https を使わない — 前段のロードバランサーが TLS を終端して :80 に転送する構成では、タブの「待ち受け」で https を外します。 コンテナは :443 を開かず証明書も不要で、転送された https トラフィック (X-Forwarded-Proto: https) を :80 で :443 と同じに処理します。 逆に http を外すと https のみの gateway になります (リダイレクト無し。:80 が要る Let's Encrypt は使えません)。

:80 は https へリダイレクトします。ロードバランサーの health check は user agent（GoogleHC、ELB-HealthChecker、kube-probe など。追加は 設定 → nginx → https redirect）でリダイレクトを免れます。 UNMASK_TRUSTED_PROXIES にロードバランサーの範囲を入れると、BAN・rate limit・geo ルールがロードバランサーではなく訪問者を見るようになります。upstream には Host、X-Real-IP、X-Forwarded-For、 X-Forwarded-Proto: https が渡り、WebSocket の upgrade も通します。

gateway は body サイズの上限を設けず、1 時間までのレスポンスを許容します。アップロードやストリームの制限は upstream 側の設定がそのまま効き、 gateway が勝手に決めた既定値で切られることはありません。

すでに nginx を運用している場合、その前段に置く

動きます。二段 proxy の一般的な注意が 2 つあるだけです。後段の nginx には gateway のアドレスから素の HTTP が届くので、 (1) 実クライアントの所在を教えてください — set_real_ip_from に gateway のアドレス、real_ip_header X-Forwarded-For — でないとログ・rate limit・geo 判定がすべて gateway を見ます。(2) 後段が自前で http→https リダイレクトをしているなら、受け取ったスキームではなく $http_x_forwarded_proto で判定してください。そうしないと両者がリクエストを弾き合ってループします。 あるいは TLS を後段に残したまま転送先にその https リスナーを指定する手もあります。gateway は SNI を送るので vhost の選択も効きます。 クライアント証明書（mTLS）は TLS が gateway で終わるため通せません。

その nginx を変更できるなら、module-only の方が向いています。そちらに module を足せば二段目の proxy 自体が要りません。 gateway は、それができないときのためのものです。

3. module-only: 自分の nginx イメージで

UNMASK_GATEWAY を設定しなければ、unmask.sh/nginx は module を読み込んだだけの素の nginx です。 自分の conf.d を mount し、ホストと同じ include を書きます:

# http スコープ（conf.d のファイルはすべて http スコープ）
include /etc/unmask/http.inc;
include /etc/unmask/upstream.conf;
include /etc/unmask/forward-auth-lbtrust.conf;

server {
    listen 443 ssl;
    ...
    include /etc/unmask/server.inc;
    location / {
        include /etc/unmask/protect.inc;
        proxy_pass http://app:3000;
    }
}

既存のイメージを使い続けて module だけ足すこともできます。.so は nginx のバージョンと一致し、--with-compat でビルドされている必要があります。 公式の nginx:<version> イメージはこの条件を満たしていて、 docker/nginx/Dockerfile は 2 段ビルドなのでそのまま流用できます。 COPY --from=unmask.sh/nginx:1.28 で module だけ取り出すのが最短です。admin コンテナとは /etc/unmask と /run/unmask を共有し、 admin 側の UNMASK_DAEMON_ADDR には nginx から見た admin のアドレスを指定します（compose なら admin:9477）。

4. Kubernetes と他のリバースプロキシ

JA4 は TLS handshake から読むので、TLS を終端する場所にしか存在しません。ingress controller、Traefik、Caddy、クラウドの LB の裏では nginx コンテナはクライアントの ClientHello を見られず、unmask は forward-auth モードとして動きます。 前段が JA4 を転送してくれる場合は別です（LB / CDN 設定に対応表があります）。 行動 CAPTCHA、PoW、IP、UA の各軸はそのまま効き、fingerprint の軸だけが使えなくなります。

edge を自分で握れるなら、gateway イメージを edge にしてください。小さなクラスタなら LoadBalancer Service を直接向ければ JA4 の軸を保てます。 ingress-nginx との統合はありません — あの controller はサードパーティの module を読み込みません。

5. イメージのタグ

• unmask.sh/admin:<unmask のバージョン>、:latest — amd64 / arm64。
• unmask.sh/nginx:<nginx のバージョン>（例 1.28.3）、:1.28、:latest、 両方を固定する :<unmask のバージョン>-<nginx のバージョン> — amd64 / arm64。nginx のバージョンは公式イメージのもので、 module は同じ Dockerfile 内でそのバージョン向けにビルドされます。新しい nginx 系列への追従は 1 行の変更です。

どちらのイメージもリリース workflow がタグの commit からビルドして push します。CI は push のたびに両方をビルドするので、 --with-compat で読み込めなくなる module の変更は出荷前に検出されます。