depot-container-builds

Depot コンテナビルド

Depot は、リモートの高性能ビルダー（16 CPU、32 GB RAM、NVMe SSD キャッシュ）で Docker イメージのビルドを実行します。depot build は docker build／docker buildx build のドロップイン置き換えです。depot bake は docker buildx bake に置き換わります。

複数組織のユーザー向けプロジェクトの選択

コンテナビルドコマンドの対象は、組織ではなく特定のプロジェクトです。想定しているプロジェクトが表示されない場合や、ビルド時に予期せずプロジェクトの選択を求められる場合は、現在のデフォルト組織が正しくない可能性があります。

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Optional: set default org

主な概念

• ビルドは一時的な EC2 インスタンス上でリモート実行されます。イメージはデフォルトでリモートキャッシュに保持されます
• --load を使うとローカルの Docker にダウンロードし、--push を使うとレジストリにプッシュし、--save を使うと Depot の一時レジストリに保存します
• キャッシュは永続的な NVMe SSD 上で完全に自動管理されるため、手動でキャッシュを設定する必要はありません
• マルチプラットフォームビルドでは、ネイティブ CPU ビルダーを使って amd64 と arm64 を同時にビルドします（QEMU エミュレーションは使いません）
• プロジェクトのチームメンバー全員が同じレイヤーキャッシュを共有します

depot build — 基本パターン

# Build remotely (image stays in remote cache)
depot build -t repo/image:tag .

# Build + download to local Docker daemon
depot build -t repo/image:tag . --load

# Build + push directly to registry (fast — doesn't route through local network)
depot build -t repo/image:tag . --push

# Multi-platform build (native CPUs, no emulation)
depot build --platform linux/amd64,linux/arm64 -t repo/image:tag . --push

# Save to Depot ephemeral registry (7-day default, configurable per repository)
depot build --save .
depot build --save --save-tag my-tag .

# Suppress provenance metadata (fixes "unknown/unknown" platform in registries)
depot build -t repo/image:tag --push --provenance=false .

# Lint Dockerfile before building
depot build -t repo/image:tag . --lint

# Build with secrets
depot build --secret id=mysecret,src=./secret.txt -t repo/image:tag .

# Build with SSH forwarding
depot build --ssh default -t repo/image:tag .

# Specify a Depot project explicitly
depot build --project <project-id> -t repo/image:tag .

主なフラグ

フラグ	説明
--load	イメージをローカルの Docker デーモンにダウンロードします
--push	レジストリにプッシュします
--save	Depot の一時レジストリに保存します
--save-tag	Depot レジストリ用のカスタムタグ
--platform	ターゲットプラットフォーム：linux/amd64、linux/arm64（ネイティブ、エミュレーションなし）、および linux/arm/v6、linux/arm/v7、linux/386
--build-platform	ビルドを実行するアーキテクチャを指定します（デフォルトは dynamic）
--project	Depot プロジェクト ID
--token	Depot API トークン
--lint	ビルド前に Dockerfile をリントします
--provenance	プロベナンス証明を制御します（unknown/unknown を解消するには false を設定します）
--sbom	SBOM 証明を生成します（--attest type=sbom の省略形）
--sbom-dir	SBOM 証明の保存先ディレクトリ
--attest	証明パラメーター（例：type=sbom,generator=image）
--no-cache	このビルドのキャッシュを無効にします
-f / --file	Dockerfile へのパス
-t / --tag	イメージ名とタグ
--target	特定のステージをビルドします
--build-arg	ビルド時の変数を設定します
--secret	シークレットを公開します（id=name[,src=path]）
--ssh	SSH エージェントを公開します
--output / -o	カスタム出力（type=local,dest=path）

コンテナビルドのキャンセル

キャンセルを求められた場合にのみ depot build cancel を使用してください。--token または DEPOT_TOKEN を使って組織 API トークンを指定してください。プロジェクトトークン、リーダートークン、旧式のログイントークン、CI OIDC 認証情報ではビルドをキャンセルできません。

depot build cancel <build-id> <another-build-id>
depot build cancel --all-running --project <project-id> --dry-run
depot build cancel --all-running --project <project-id> --yes --output json

明示的なビルド ID、または --all-running --project のどちらかを選択してください。両方は指定できません。一括選択には明示的なプロジェクトが必要です。depot.json と DEPOT_PROJECT_ID はプロジェクトの指定には使われません。一括キャンセルを事前確認するには --dry-run を使用してください。非対話型でのキャンセルが承認済みの場合にのみ --yes を使用してください。選択対象には、その後に開始されたビルドは含まれません。

キャンセルは非同期で実行されます。成功はリクエストが受け付けられたことを意味し、実行が停止したことを意味するものではありません。完了済みのビルドに対しては何も行われず、成功として扱われます。JSON には各ビルドの結果またはエラーが報告されます。リクエストに失敗が1つでもある場合、コマンドは失敗します。

depot bake — 複数イメージのビルド

docker buildx bake のドロップイン置き換えです。複数のイメージを並列にビルドします。

depot bake                                    # Default file lookup
depot bake -f docker-bake.hcl                 # Specific HCL file
depot bake -f docker-compose.yml --load       # Build compose services + load locally
depot bake --save --save-tag v1               # Save as v1-<target-name> in Depot Registry
depot bake --print                            # Print resolved config without building

デフォルトのファイル検索順序： compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.hcl → docker-bake.override.json → docker-bake.override.hcl

ターゲット引数を指定しない場合、depot bake は default グループをビルドします。保存されるタグは <build-id>-<target-name> です。--save-tag v1 を指定すると、v1-<target-name> が追加されます。Depot Registry に保存し、設定済みのターゲットタグをプッシュするには、--save --push を使用します。Depot プロジェクトを選択するには、HCL ターゲットに project_id を設定します。

HCL Bake ファイルの例

variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["app", "worker"]
}

target "app" {
  dockerfile = "Dockerfile"
  platforms  = ["linux/amd64", "linux/arm64"]
  tags       = ["myrepo/app:${TAG}"]
  args = { NODE_VERSION = "20" }
}

target "worker" {
  dockerfile = "Dockerfile.worker"
  tags       = ["myrepo/worker:${TAG}"]
  contexts   = { app = "target:app" }  # Share base between targets
}

変数の上書き：TAG=v2.0 depot bake

サービスごとにプロジェクト ID を指定する Docker Compose

services:
  api:
    build:
      dockerfile: ./Dockerfile.api
      x-depot:
        project-id: abc123
  web:
    build:
      dockerfile: ./Dockerfile.web
      x-depot:
        project-id: def456

Docker Compose との統合

# Preferred: build all services in parallel, then load
depot bake -f docker-compose.yml --load
docker compose up

# Alternative: zero code change (less efficient, each service = separate build)
depot configure-docker
docker compose build

Docker からの移行

# docker build → depot build (same flags, one-line swap)
depot build -t my-image .

# docker buildx bake → depot bake
depot bake -f docker-bake.hcl

# Zero code change via Docker plugin
depot configure-docker
docker build .  # Routes through Depot (look for [depot] prefix in logs)

移行時には、次のフラグを削除してください — Depot がキャッシュを自動的に処理します。

• --cache-from type=gha — 「services aren't available」エラーが発生します
• --cache-to type=gha — 同じ問題が発生します
• 手動で設定した BuildKit キャッシュ設定

よくある間違い

間違い	対処法
--cache-from type=gha または --cache-to type=gha を使用する	削除してください。Depot は NVMe SSD 上でキャッシュを自動的に処理します。
マルチプラットフォームイメージのプラットフォームが unknown/unknown と表示される	--provenance=false を追加してください
depot build の後にイメージがローカルにあることを期待する	ダウンロードするには --load を、レジストリにプッシュするには --push を追加してください
ビルドコンテキストに .git ディレクトリがない	--build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 を追加してください
ビルドが停止する、または「failed to mount」エラーが発生する	プロジェクト設定、または depot cache reset でキャッシュをリセットしてください
ベースイメージの取得時に「401 Unauthorized」が発生する	Docker Hub のレート制限です — docker login で認証するか、public.ecr.aws/docker/library/ ミラーを使用してください
--load で「client version 1.43 is too old」が発生する	Docker Engine v29 では最小 API バージョンが 1.44 に引き上げられています — ビルドコマンドの先頭に DOCKER_API_VERSION=1.52 depot build --load . を付けてください
「Keep alive ping failed」／OOM	プロジェクト設定でビルダーのサイズを大きくするか、自動スケーリングを有効にしてください

ビルダーのサイズ

サイズ	CPU	RAM	分あたりの料金	分数倍率	プラン
デフォルト	16	32 GB	$0.04	1x	すべて
大	32	64 GB	$0.08	2x	Startup+
特大	64	128 GB	$0.16	4x	Startup+

秒単位で課金されます。大および特大のビルダーは、1 分あたりの料金が高くなるほか、倍率によって含まれるビルド時間をより速く消費します。

ビルドの自動スケーリング

自動スケーリングはデフォルトで無効になっているため、Depot はプロジェクトのビルドをアーキテクチャごとに 1 つのビルダーへルーティングします。同時ビルドに別々のビルダーが必要な場合は、プロジェクト設定で水平自動スケーリングを有効にしてください。設定フォームでは、インスタンスあたりのビルド数として 16 があらかじめ選択されています。同時ビルド数が設定した上限に達すると、Depot は別のビルダーを起動します。

各ビルダーのキャッシュは独立しています。自動スケーリングを多用するとキャッシュ効率が低下する場合があるため、1 つのビルドでより多くの CPU またはメモリが必要な場合は、まずビルダーのサイズを大きくしてみてください。自動スケーリングは追加料金なしですべてのプランで利用できます。

1 回の depot bake の実行は、ターゲット数にかかわらず、自動スケーリングでは 1 つのビルドとしてカウントされます。プロジェクト ID が異なれば、個別のビルドリクエストが作成されます。

組織の API トークンを使って、CLI から自動スケーリングを設定します。

depot projects update <project-id> --max-concurrent-builds 3
depot projects update <project-id> --disable-autoscaling

正の上限値は、ビルダーインスタンスごとに適用されます。2 つの更新フラグは同時に指定できません。どちらも省略すると、現在の設定が維持されます。depot projects create <name> --max-concurrent-builds 3 を使うと、新しいプロジェクトで自動スケーリングが有効になります。フラグを指定せずに作成した場合、自動スケーリングは無効のままです。

Depot Registry

ビルド出力用の軽量な一時ストアとしても、Depot でビルドしていないものを含むすべてのイメージ用の完全なプライマリレジストリとしても機能する、OCI 準拠のレジストリです。各組織にはグローバル CDN によってバックアップされた独自のサブドメイン {orgId}.registry.depot.dev が割り当てられ、最大 50 GB のイメージと OCI アーティファクト（Helm チャート、AI モデル）が保存されます。ダッシュボードの Registry Explorer で、リポジトリ、タグ、アテステーションを確認できます。

# Save a Depot build's output to the registry (project-scoped, no tagging step)
depot build --save -t myapp .

# Push any image to Depot Registry as a primary registry
docker push {orgId}.registry.depot.dev/your/app:v1

# Pull a saved project image (by build ID or by tag)
depot pull --project <id> <build-id>
depot pull --project <id> my-image:tag
depot pull --project <id> --platform linux/arm64 <build-id>   # pull a specific platform

# Generate a 1-hour read-only token for the project's registry paths
depot pull-token --project <id>
depot pull-token --project <id> <build-id>                    # scoped to a specific build

# Push saved image to another registry
depot push --project <id> -t registry/image:tag <build-id>

# List saved images as JSON
depot image list --project <id> --output json

# Delete selected image tags only when requested
depot image rm --project <id> app:old app:staging

# Docker auth for Depot Registry (each org has its own subdomain)
docker login {orgId}.registry.depot.dev -u x-token
# Enter a scoped registry access token at the password prompt.
# Registry URL: {orgId}.registry.depot.dev/your/app:tag
# (the legacy registry.depot.dev/<project-id>:<build-id> form still works for existing usage)

イメージの保持期間はデフォルトで 7 日間ですが、Registry Explorer からリポジトリごとに設定できます。期間（1、7、14、30 日）またはタグ数（5、10、25、50、100 個）で指定します。

カスタムイメージ名を使用するには、レジストリアクセストークンを使います。組織のオーナーは、Registry Settings → Registry access tokens でトークンを作成できます。Pull または Push の権限を選択します。Push には Pull のアクセス権も含まれます。トークンのスコープには、完全一致のパス（frontend）、1 階層（team/*）、任意の階層（team/**）、またはすべてのリポジトリ（**）を指定できます。スコープにはレジストリのホスト名とイメージタグを含めないでください。

保存済みのプロジェクトビルドやタグには depot pull を、カスタムリポジトリやプルスルーリポジトリには docker pull を使います。CLI の Pull トークンの対象は <project-id> とその子孫パスのみです。それ以外の名前には、Pull 権限を持つレジストリアクセストークンを使ってください。

プルスルーキャッシュ： Depot Registry は外部レジストリへのプロキシとして動作し、そのレイヤーを CDN にキャッシュできます。これにより、再度プルする際に上流レジストリへのアクセスを省略できます（CI でのプルを高速化し、グローバルに配信でき、Google Artifact Registry などのレジストリで認証を簡素化できます）。Registry Settings で上流を設定します。対応プロバイダーは Docker Hub、GitHub Container Registry、GitLab Container Registry、Quay.io、AWS ECR、Google Artifact Registry、Azure Container Registry、およびカスタムレジストリです。プルスルーはリポジトリの作成時に設定する必要があり、既存のリポジトリには追加できません。

latest などの変更可能なタグのキャッシュは、プルのたびに上流から更新されるわけではありません。更新されたコンテンツを選択するには、新しい不変タグまたはダイジェストを使用してください。コンテンツが存在しない場合やキャッシュから削除された場合は、引き続き上流レジストリが必要です。そのため、キャッシュがあっても上流の障害時に利用できるとは限りません。

特殊な出力形式

# estargz (lazy-pulling for faster container startup)
depot build --output "type=image,name=repo/image:tag,push=true,compression=estargz,oci-mediatypes=true,force-compression=true" .

# zstd compression (faster Fargate/K8s startup)
depot build --output type=image,name=repo/image:tag,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true,push=true .

# SOCI v2 (lazy-loading for faster startup of large images, for example CUDA/PyTorch)
depot build -t repo/image:tag --push --output type=image,soci=true,compression=gzip,force-compression=true,oci-mediatypes=true .

SOCI がインデックスを作成できるのは gzip レイヤーのみなので、compression=gzip が必要です。また、force-compression=true にすると、ベースイメージのレイヤーを含むすべてのレイヤーがインデックス化されます。インデックスは変更されていないレイヤーとともにレジストリに書き込まれるため、プッシュ後に別途処理する必要はありません。デフォルトでは 10 MB 未満のレイヤーはスキップされます（変更するには soci-min-layer-size を指定します）。起動時のメリットを得るには、プルするプラットフォームで SOCI スナップショッターを使用する必要があります。AWS Fargate では自動的に使用されますが、Amazon EKS／EC2 または独自のホストでは、containerd で soci-snapshotter を有効にする必要があります。