depot-container-builds

Depot コンテナビルド

CI への変更を提案する前に、そのアイデアについてすでに試されたことを確認してください。何が測定されたのか、そしてなぜ一見良さそうな変更が差し戻されたり却下されたりしたのかが記録されています。

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 インスタンス上で実行されます — イメージはデフォルトでリモートキャッシュに保持されます
• ローカルの Docker にダウンロードするには --load、レジストリにプッシュするには --push、Depot の一時レジストリに保存するには --save を使用します
• キャッシュは永続的な NVMe SSD 上で完全に自動です — 手動のキャッシュ設定は不要です
• マルチプラットフォームビルドは amd64 と arm64 を同時に ネイティブ CPU ビルダーで実行します（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 Registry 用のカスタムタグ
--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	来歴証明（provenance attestation）を制御します（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 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 myrepo/app:v1    # Save to 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

HCL ベイクファイルの例

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	1分あたり	分数の倍率	プラン
Default	16	32 GB	$0.04	1x	すべて
Large	32	64 GB	$0.08	2x	Startup+
Extra Large	64	128 GB	$0.16	4x	Startup+

秒単位で課金されます。Large および Extra Large ビルダーは、1分あたりのコストが高くなることに加えて、倍率によって含まれるビルド分数をより早く消費します。

Depot Registry

OCI 準拠のレジストリで、ビルド出力用の軽量な一時ストアとしても、Depot 以外でビルドされたものを含むすべてのイメージの完全なプライマリレジストリとしても機能します。各組織は独自のサブドメイン {orgId}.registry.depot.dev を取得し、グローバル CDN に支えられて、最大 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 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 short-lived (1-hour) read-only token to pull from the Depot Registry
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>

# Docker auth for Depot Registry (each org has its own subdomain)
docker login {orgId}.registry.depot.dev -u x-token -p <depot-token>
# 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 タグ)で設定できます。

プルスルーキャッシュ: 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、およびカスタムレジストリです。プルスルーはリポジトリの作成時に設定する必要があり、既存のリポジトリに追加することはできません。

特別な出力形式

# 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 を有効にする必要があります。