Pi-holeをdocker runだけで起動する

Pi-holeのDocker公式イメージはdocker-composeでの起動が案内されている。しかしNAS製品の多くはGUIからコンテナを管理する設計であり、docker-composeを使うにはSSHでログインする必要がある。Pi-holeを動かすためだけにSSHの管理を増やすのは合理的でない。

実際にはdocker-composeの設定はすべて docker run のオプションに変換できるため、docker-compose無しでもPi-holeは起動できる。本稿では、公式のdocker-compose設定を docker run コマンドに変換した例を示し、あわせて各オプションの意味を整理する。

docker runコマンド

以下は、Pi-hole公式のdocker-compose設定と同等の docker run コマンドである。

docker run -d \\
  --name pihole \\
  -p 53:53/tcp \\
  -p 53:53/udp \\
  -p 80:80/tcp \\
  -p 443:443/tcp \\
  -e TZ='Asia/Tokyo' \\
  -e FTLCONF_webserver_api_password='任意のパスワード' \\
  -e FTLCONF_dns_listeningMode='ALL' \\
  -v /path/to/etc-pihole:/etc/pihole \\
  --cap-add=NET_ADMIN \\
  --cap-add=SYS_TIME \\
  --cap-add=SYS_NICE \\
  --restart unless-stopped \\
  pihole/pihole:latest

NASのコンテナ管理GUIにこれらのパラメータを入力するか、SSH不要でコマンドを実行できる手段があればそれを利用する。

オプションの説明

ポートマッピング（-p）

• 53:53/tcp および 53:53/udp: DNS用ポート。TCP/UDPの両方が必要
• 80:80/tcp: 管理用WebインターフェースのHTTPポート
• 443:443/tcp: 管理用WebインターフェースのHTTPSポート。Pi-hole FTLが自己署名証明書を自動生成する

Pi-holeをDHCPサーバとしても使用する場合は -p 67:67/udp を追加する。NTPサーバとしても使用する場合は -p 123:123/udp を追加する。

環境変数（-e）

• TZ: タイムゾーン。IANA形式で指定する（日本の場合は Asia/Tokyo）
• FTLCONF_webserver_api_password: 管理用Webインターフェースのパスワード。未指定の場合はランダムなパスワードが自動生成される
• FTLCONF_dns_listeningMode: DNSの待ち受けモード。Dockerのデフォルトネットワーク（bridgeモード）を使用する場合は ALL を指定する

ボリューム（-v）

• /path/to/etc-pihole:/etc/pihole: Pi-holeのデータベースと設定ファイルの永続化先。コンテナを再作成してもデータが保持される。/path/to/etc-pihole は実際のパスに置き換える

Pi-hole v5からv6へ移行する場合で、以前にdnsmasqのカスタム設定を使用していた場合は、初回起動時のみ /path/to/etc-dnsmasq.d:/etc/dnsmasq.d のマウントと環境変数 FTLCONF_misc_etc_dnsmasq_d=true の追加が必要になる。移行完了後は不要になる。v6から新規導入する場合はこの設定は不要である。

ケーパビリティ（--cap-add）

• NET_ADMIN: Pi-holeをDHCPサーバとして使用する場合に必要。DNSのみの用途では不要だが、公式設定に含まれているためそのまま指定している
• SYS_TIME: Pi-holeをNTPクライアントとして使用し、ホストのシステム時刻を設定する場合に必要
• SYS_NICE: Pi-holeのプロセスに高い処理優先度を付与する。任意の設定

再起動ポリシー（--restart）

• unless-stopped: 手動で停止した場合を除き、コンテナが停止したときに自動で再起動する。NASの再起動後もPi-holeが自動的に起動するようになる

docker-compose（日本語注釈版）

参考として、公式のdocker-compose設定に日本語の注釈を付けたものを以下に示す。

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      # DNSポート（TCP/UDP両方必要）
      - "53:53/tcp"
      - "53:53/udp"
      # 管理画面 HTTPポート
      - "80:80/tcp"
      # 管理画面 HTTPSポート（FTLが自己署名証明書を自動生成）
      - "443:443/tcp"
      # DHCPサーバとして使う場合は以下を有効にする
      #- "67:67/udp"
      # NTPサーバとして使う場合は以下を有効にする
      #- "123:123/udp"
    environment:
      # タイムゾーンをIANA形式で指定（日本: Asia/Tokyo）
      TZ: 'Asia/Tokyo'
      # 管理画面のパスワード（未指定ならランダム生成）
      FTLCONF_webserver_api_password: '任意のパスワード'
      # Dockerのbridgeネットワーク使用時は'ALL'を指定
      FTLCONF_dns_listeningMode: 'ALL'
    volumes:
      # データベースと設定ファイルの永続化
      - './etc-pihole:/etc/pihole'
      # v5からv6への移行時のみ必要（初回起動後は削除可）
      # 環境変数 FTLCONF_misc_etc_dnsmasq_d: 'true' も併せて設定すること
      # v6新規導入の場合は不要
      #- './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      # DHCPサーバとして使う場合に必要
      - NET_ADMIN
      # NTPクライアントとしてホストの時刻を設定する場合に必要
      - SYS_TIME
      # プロセスの処理優先度を上げる（任意）
      - SYS_NICE
    # 手動停止以外では自動再起動
    restart: unless-stopped