以前の記事 で紹介した one-off-docker-runner に、volumes の「host bind」機能が追加・改善されました。本記事では、Run API の正確な JSON リクエスト形式、各パラメータの意味、注意点をまとめます。この記事だけでコピペ再現できます。

• リポジトリ: https://github.com/tumf/oneoff-docker-runner
• README: https://github.com/tumf/oneoff-docker-runner/blob/main/README.md
• 対象機能: Run API の volumes 指定（type = "host"）

できること（概要）

ホスト上の既存ファイルやディレクトリを、コンテナ内の任意のパスに bind mount できます。これにより、

• 実行前にホスト側で用意した入力（設定、データ）をコンテナへ渡す
• 実行後にコンテナ側で生成された成果物をホスト側でそのまま参照する といったワークフローがシンプルに実現できます。

volumes キーの基本

• キー（左側）は「コンテナ側のマウントパス」とオプションのアクセス修飾子で構成します。
  • 形式: <container_path>[:ro|:rw]
  • 例: /app/data, /etc/config:ro
  • 省略時は rw（読み書き）
• 値（右側）は VolumeConfig オブジェクトで、type により意味が変わります。
  • file | directory | volume | host
• 今回の主題である type = "host" では、以下がポイントです（README 準拠）。
  • 必須: host_path（ホスト上の絶対パス）
  • 禁止: response（true 指定はサポート外で拒否されます）

README の該当要点:

• bind source は type=host の場合、host_path に与えた「ホスト上の絶対パス」
• type=host では response はサポートされず、指定するとエラーとして拒否されます

最小リクエスト例（host のファイル + ディレクトリ）

以下はホスト上の host.txt とディレクトリをコンテナにマウントし、中身を確認する最小例です。

unchanged above

最小リクエスト例（host のファイル + ディレクトリ）

以下はホスト上の host.txt とディレクトリをコンテナにマウントし、中身を確認する最小例です。

{
  "image": "alpine:latest",
  "command": ["sh", "-c", "ls -la /app && cat /app/host.txt || true"],
  "volumes": {
    "/app/host.txt:ro": { "type": "host", "host_path": "/absolute/path/to/host.txt" },
    "/app/data": { "type": "host", "host_path": "/absolute/path/to/dir" }
  }
}

curl での呼び出し例

ローカルでサーバーを起動している前提（例: docker run --rm -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/tumf/oneoff-docker-runner）。

curl -sS -X POST 'http://localhost:8000/run' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "alpine:latest",
    "command": ["sh", "-c", "ls -la /app && cat /app/host.txt || true"],
    "volumes": {
      "/app/host.txt:ro": { "type": "host", "host_path": "/absolute/path/to/host.txt" },
      "/app/data": { "type": "host", "host_path": "/absolute/path/to/dir" }
    }
  }'

API 仕様の要点（README 準拠）

• volumes のキー（左側）は「コンテナ側のマウントパス[:ro|:rw]」
  • 例: /app/data, /etc/config:ro（省略時は rw）
• 値（右側）は VolumeConfig。type により意味が変わる
  • file | directory | volume | host
• type = "host" のとき
  • 必須: host_path（ホスト上の絶対パス）
  • 禁止: response（true 指定はサポート外で拒否されます）
• type = "file" | "directory" のとき
  • content に base64（ファイルはそのまま、ディレクトリは tar.gz の base64）
  • response: true を付けると実行後に内容がレスポンスへ返却されます

注意点（環境依存の罠）

• 絶対パス必須: host_path は絶対パスのみサポート
• 実体の存在: 指定したファイル/ディレクトリがホストに存在していること
• 権限: OneOffDockerRunner が参照できる権限が必要（パーミッション/所有者）
• SELinux/AppArmor: 制約により読み書きできない場合があります（必要に応じてコンテナ設定を見直す）
• Docker Desktop: macOS/Windows は「File Sharing（共有ディレクトリ）」設定が必要な場合があります
• Windows パス: WSL/VM 環境ではホストの実際のパス解決に注意（WSL パスと Windows パスの違い）
• ルートレス Docker: 一部のホストパスがマウント不可な構成があり得ます

よくあるエラーと対処

• 422 Unprocessable Entity（バリデーションエラー）
  • host_path が相対パス/未指定、response を誤って指定、など
• 500 Internal Server Error（実行時エラー）
  • マウント先が存在しない/権限不足/ホスト側のパス未存在 など。コンテナ出力（stdout/stderr）や API の detail を確認

関連リンク

• リポジトリ: https://github.com/tumf/oneoff-docker-runner
• README: https://github.com/tumf/oneoff-docker-runner/blob/main/README.md
• 以前の記事: https://blog.tumf.dev/posts/diary/2025/1/8/one-off-docker-runner/