Docker Desktopの公式CLI資料には、start、stop、restart、statusという4つの状態操作が掲載されています。公式コマンド一覧を踏まえ、リモートMac CIで接続に失敗したら、まず実際にジョブを実行するmacOSアカウントでDocker Desktopの状態を確認してください。その後、同じアカウントのDocker CLI、context、socketを調べます。SSHログインやCLIの存在だけでは、Docker Engineが利用可能とは判断できません。
この記事の対象
Xcodeとコンテナ構築を同じノードで行い、CIからDocker Engineに接続できない原因を探す担当者向けです。
SSHでリモートMacを操作する開発者や、アカウントと再起動後の復旧を確認してノードを受け入れるDevOps担当者にも役立ちます。
[ SECTION_01 ] Docker DesktopのリモートMac CI接続失敗は、失敗した層から切り分けます
SSH接続、Docker CLIの実行、Docker Engineへの接続、コンテナの実行は、それぞれ別の確認項目です。SSHでログインできても、CIの実行アカウントでDocker Desktopが起動しているとは限りません。CLIが見つかっても、contextが意図しない接続先を選んでいたり、socketとクライアントの接続先が一致しなかったりする場合があります。
| 症状・評価 | 確認できた証拠 | 次に行うこと |
|---|---|---|
| ○ CLIまで正常 | 対象アカウントでCLIの場所とバージョンを確認できる | Docker Desktopの状態へ進む |
| △ Engine未確認 | CLIは動くが、docker infoが接続エラーになる |
Desktop、context、socketを照合する |
| × 実ジョブ未確認 | Engineには接続するが、ビルドやコンテナ処理が失敗する | 認証、ネットワーク、イメージ、ビルドログを分けて調べる |
| ○ 運用受け入れ | 再起動後も対象CIアカウントで実ジョブが完了する | 記録を残して用途を決める |
この評価は接続経路の確認状況を示すもので、ノード性能の保証ではありません。特定のsocketパスが存在することだけを根拠に「接続正常」としないでください。
[ SECTION_02 ] CLIが見つからない場合は実行ユーザーと環境を照合します
SSHではDockerコマンドが動くのに、CIでは見つからない場合は何を確認しますか。 まず、SSHの対話シェルとCIジョブが同じmacOSユーザーで実行されているかを確認します。次に、ShellとPATHを比べます。対話セッションで読み込まれる設定が、バックグラウンドのジョブにも適用されるとは限りません。
対象アカウントで次を実行し、結果をジョブログと照合します。
id -un
printf '%s\n' "$SHELL" "$PATH"
command -v docker
docker --version
command -v dockerが何も返さない場合は、CLIが未導入か、その実行環境のPATHに含まれていない可能性があります。場所が表示されるのにEngineへ接続できない場合は、CLIの探索で止めず、Docker Desktopと接続先の確認へ進みます。インストールや動作条件は、macOS向けDocker Desktop公式手順と、利用中の版に対応する公式リリースノートで確認してください。
[ SECTION_03 ] Docker Desktop起動後もEngineに接続できない場合はcontextとsocketを確認します
Docker Desktopが起動しているように見えるのに、CIがdaemonへ接続できない場合はどう切り分けますか。 先にCIと同じアカウントで状態を確認します。Docker Desktop CLIで状態を確認できる環境では、公式資料に記載されたdocker desktop statusも照合に使えます。Desktopの設定・保守に関する公式資料も参照し、起動操作の結果だけでなくCLIからの接続を検証してください。
続けて、同じ環境でcontextと接続先を確認します。
docker context ls
docker context show
docker context inspect <CONTEXT>
printf '%s\n' "$DOCKER_HOST"
docker version
docker info
docker context lsとdocker context showで選択中のcontextを把握し、docker context inspect <CONTEXT>で接続先を確認します。contextの選択・設定はDocker公式のcontext資料とdocker context useの説明に沿って確認できます。DOCKER_HOSTが設定されていれば、contextの接続先と食い違っていないかも見ます。
socketの場所を固定値で決めつけず、実際のcontext情報とCI環境の設定を突き合わせてください。docker versionでクライアント情報だけ表示され、サーバー側に接続できない場合は、CLIではなくEngineまでの接続に問題が残っています。
socketが存在することは、対象アカウントから利用できることや、CIが同じsocketを参照していることの証明にはなりません。対話シェルとジョブの両方で接続先を記録してください。
[ SECTION_04 ] CIアカウントが異なるときは、状態と権限を別々に検証します
実行アカウントを変更したらDocker Desktopが使えなくなった場合、設定をそのまま引き継げますか。 引き継げると仮定せず、新しいアカウントの環境で確かめます。アカウントごとにPATH、環境変数、ユーザー単位のCLI設定が異なる可能性があり、別のユーザーで起動したアプリの状態も同じように見えるとは限りません。
SSHでの手動実行、CIジョブ、バックグラウンドタスクについて、実行ユーザー、PATH、DOCKER_HOST、docker context showの結果を比較します。手動実行だけ成功する場合、成功したシェルの環境をCIにも当てはめず、CIの実行条件そのものを記録してください。macOS上のインストールとアカウントの動作条件はDocker DesktopのFAQも確認します。
[ SECTION_05 ] Engine接続後の失敗は、ビルドとコンテナ側で調べます
docker infoなどでEngine接続を確認できた後に失敗するなら、ホスト接続の設定変更を続ける前に、処理の段階を分けます。イメージを取得できない場合はレジストリ認証やネットワークを確認します。取得後にビルドや起動が失敗する場合は、プロジェクトのログ、イメージのアーキテクチャ、コンテナ内の依存関係を調べます。
リモートMac CIでは、手動実行時とジョブ実行時で認証情報や環境変数が違うこともあります。対象のコマンドとエラー出力をジョブログに残し、Engine接続エラーとイメージ・アプリケーション側のエラーを区別してください。ここでsocketやcontextを無関係に変更すると、確認済みの接続条件まで崩すおそれがあります。
[ SECTION_06 ] 再起動後の実ジョブを合格条件にします
接続確認のコマンドが一度成功すれば、無人運転に移せますか。 まだ判断できません。対象のCIアカウントで最小の実コンテナタスクを実行し、管理された再起動の後にもDesktopの状態、context、socketへの接続、タスク結果を確かめます。Docker Desktopの起動や復旧が、すべてのSSH・CI実行方式で自動的に保証されるとは見なさないでください。
判定は次の条件で行います。
- 対象アカウントで実ジョブが成功し、再起動後も同じ手順で再現できる場合：ログ、終了状態、実行環境を記録して、その用途で受け入れます。
- SSHからは成功するがCIのアカウントでは失敗する場合：アカウントと環境の不一致を解消するまで、CIノードとしての受け入れを保留します。
- Engine接続は成功するがビルドやコンテナ処理が失敗する場合：ホスト接続の変更を止め、認証、ネットワーク、イメージ、プロジェクトログへ調査対象を移します。
- 再起動後に接続を再現できない場合：有人運用に制限するか、タスク要件に合う別の実行環境を検討します。
macOS SSHの接続確認とDocker Engineの利用確認は別工程です。Mac miniを含む遠隔Macの選択肢は、NOVAKVMのリモートMac案内から確認できます。購入とレンタルを比べる際は、Mac miniの案内も参照し、必要な運用期間と管理負担を見積もってください。
既存のLinux CI環境は、コンテナ処理に使えてもmacOS専用工程を代替できず、手元のMacは利用者の電源・ログイン状態に左右され、共有端末は実行アカウントの差異を生みやすいという制約があります。macOS上の処理を継続して実行する必要があり、機材購入や常時管理を避けたい場合は、NOVAKVMのリモートMacを検証用・CI用に借りる方法も選択肢です。ただし、長期に高稼働で固定利用する場合や物理ポートへの接続が必要な場合は、自社購入や別構成のほうが適することがあります。Docker DesktopのリモートMac CI接続失敗を解消した証拠として、実行アカウントと再起動後の実ジョブ記録を残してから運用を決めてください。