depot-container-builds

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Depot Container Builds

Depot容器构建

Depot runs Docker image builds on remote high-performance builders (16 CPU, 32 GB RAM, NVMe SSD cache).

depot build

is a drop-in replacement for

docker build

docker buildx build

depot bake

replaces

docker buildx bake

Depot在远程高性能构建节点（16 CPU、32 GB内存、NVMe SSD缓存）上运行Docker镜像构建。

depot build

是

docker build

docker buildx build

的直接替代工具，

depot bake

则替代

docker buildx bake

。

Key Concepts

核心概念

Builds run remotely on ephemeral EC2 instances — images stay in remote cache by default
Use
```
--load
```
to download to local Docker,
```
--push
```
to push to a registry,
```
--save
```
to store in Depot's ephemeral registry
Cache is fully automatic on persistent NVMe SSDs — no manual cache config needed
Multi-platform builds use native CPU builders (no QEMU emulation) for amd64 and arm64 simultaneously
All team members on a project share the same layer cache

构建任务在临时EC2实例上远程运行——镜像默认存储在远程缓存中
使用
```
--load
```
将镜像下载到本地Docker守护进程，
```
--push
```
推送到镜像仓库，
```
--save
```
存储到Depot的临时镜像仓库
缓存完全自动在持久化NVMe SSD上实现——无需手动配置缓存
多平台构建使用原生CPU构建节点（无QEMU模拟），同时支持amd64和arm64架构
项目的所有团队成员共享同一层缓存

depot build

— Essential Patterns

depot build

— 核心使用模式

bash

undefined

bash

undefined

Build remotely (image stays in remote cache)

远程构建（镜像保留在远程缓存）

depot build -t repo/image:tag .

Build + download to local Docker daemon

构建并下载到本地Docker守护进程

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)

多平台构建（原生CPU，无模拟）

depot build --platform linux/amd64,linux/arm64 -t repo/image:tag . --push

Save to Depot ephemeral registry (default 7-day retention)

保存到Depot临时镜像仓库（默认保留7天）

depot build --save . depot build --save --save-tag my-tag .

Suppress provenance metadata (fixes "unknown/unknown" platform in registries)

禁用溯源元数据（修复镜像仓库中的"unknown/unknown"平台问题）

depot build -t repo/image:tag --push --provenance=false .

Lint Dockerfile before building

构建前检查Dockerfile语法

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

通过SSH转发构建

depot build --ssh default -t repo/image:tag .

Specify a Depot project explicitly

显式指定Depot项目

depot build --project <project-id> -t repo/image:tag .

undefined

depot build --project <project-id> -t repo/image:tag .

undefined

Key Flags

关键参数

Flag	Description
`--load`	Download image to local Docker daemon
`--push`	Push to registry
`--save`	Save to Depot ephemeral registry
`--save-tag`	Custom tag for Depot Registry
`--platform`	Target platforms ( `linux/amd64` , `linux/arm64` , or both)
`--build-platform`	Force build to run on specific arch ( `dynamic` default)
`--project`	Depot project ID
`--token`	Depot API token
`--lint`	Lint Dockerfile before build
`--provenance`	Control provenance attestation (set `false` to fix unknown/unknown)
`--no-cache`	Disable cache for this build
`-f` / `--file`	Path to Dockerfile
`-t` / `--tag`	Image name and tag
`--target`	Build specific stage
`--build-arg`	Set build-time variables
`--secret`	Expose secrets ( `id=name[,src=path]` )
`--ssh`	Expose SSH agent
`--output` / `-o`	Custom output ( `type=local,dest=path` )

参数	描述
`--load`	将镜像下载到本地Docker守护进程
`--push`	推送到镜像仓库
`--save`	保存到Depot临时镜像仓库
`--save-tag`	为Depot镜像仓库设置自定义标签
`--platform`	目标平台（ `linux/amd64` 、 `linux/arm64` ，或两者同时）
`--build-platform`	强制构建在特定架构节点运行（默认 `dynamic` ）
`--project`	Depot项目ID
`--token`	Depot API令牌
`--lint`	构建前检查Dockerfile语法
`--provenance`	控制溯源认证（设置为 `false` 可修复unknown/unknown问题）
`--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

— Multi-Image Builds

depot bake

— 多镜像构建

Drop-in replacement for

docker buildx bake

. Builds multiple images in parallel.

bash

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

Default file lookup order: compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.override.json → docker-bake.hcl → docker-bake.override.hcl

可直接替代

docker buildx bake

，支持并行构建多个镜像。

bash

depot bake                                    # 默认查找配置文件
depot bake -f docker-bake.hcl                 # 指定HCL文件
depot bake -f docker-compose.yml --load       # 构建compose服务并加载到本地
depot bake --save --save-tag myrepo/app:v1    # 保存到Depot镜像仓库
depot bake --print                            # 打印解析后的配置，不执行构建

默认配置文件查找顺序： compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.override.json → docker-bake.hcl → docker-bake.override.hcl

HCL Bake File Example

HCL Bake配置文件示例

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
}

Override variables:

TAG=v2.0 depot bake

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" }  # 在目标间共享基础镜像
}

覆盖变量：

TAG=v2.0 depot bake

Docker Compose with Per-Service Project IDs

为每个服务指定项目ID的Docker Compose配置

yaml

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

yaml

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

Docker Compose Integration

Docker Compose集成

bash

undefined

bash

undefined

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

undefined

depot configure-docker docker compose build

undefined

Migration from Docker

从Docker迁移

bash

undefined

bash

undefined

docker build → depot build (same flags, one-line swap)

docker build → depot build（参数一致，一键替换）

depot build -t my-image .

docker buildx bake → depot bake

depot bake -f docker-bake.hcl

Zero code change via Docker plugin

通过Docker插件实现零代码修改

depot configure-docker docker build . # Routes through Depot (look for [depot] prefix in logs)


**When migrating, remove these flags** — Depot handles caching automatically:

- `--cache-from type=gha` — causes "services aren't available" errors
- `--cache-to type=gha` — same issue
- Any manual BuildKit cache configuration

depot configure-docker docker build . # 请求会路由到Depot（日志中会显示[depot]前缀）


**迁移时请移除以下参数**——Depot会自动处理缓存：

- `--cache-from type=gha` — 会导致"服务不可用"错误
- `--cache-to type=gha` — 同样问题
- 任何手动配置的BuildKit缓存参数

Common Mistakes

常见错误

Mistake	Fix
Using `--cache-from type=gha` or `--cache-to type=gha`	Remove them. Depot caches automatically on NVMe SSDs.
Multi-platform image shows `unknown/unknown` platform	Add `--provenance=false`
Expecting image locally after `depot build`	Add `--load` to download, or `--push` to push to registry
`.git` directory missing in build context	Add `--build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1`
Build hangs or "failed to mount" errors	Reset cache in project settings or via `depot cache reset`
"401 Unauthorized" pulling base images	Docker Hub rate limit — authenticate with `docker login` or use `public.ecr.aws/docker/library/` mirror
"Keep alive ping failed" / OOM	Scale up builder size in project settings or enable autoscaling

错误	解决方法
使用 `--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/` 镜像源
出现"Keep alive ping failed" / OOM错误	在项目设置中升级构建节点规格，或启用自动扩容

Builder Sizes

构建节点规格

Size	CPUs	RAM	Per-Minute	Plans
Default	16	32 GB	$0.004	All
Large	32	64 GB	$0.008	Startup+
Extra Large	64	128 GB	$0.016	Startup+

Billed per-second. Bake counts as one build regardless of target count.

规格	CPU数量	内存	每分钟费用	适用套餐
默认版	16	32 GB	$0.004	所有套餐
大型版	32	64 GB	$0.008	Startup+套餐
超大型版	64	128 GB	$0.016	Startup+套餐

按秒计费。Bake构建无论包含多少目标，都按一次构建计费。

Depot Registry

Depot镜像仓库

bash

undefined

bash

undefined

Save image to Depot Registry

将镜像保存到Depot镜像仓库

depot build --save -t myapp .

Pull a saved image

拉取已保存的镜像

depot pull --project <id> <build-id>

Push saved image to another registry

将已保存的镜像推送到其他仓库

depot push --project <id> -t registry/image:tag <build-id>

Docker auth for Depot Registry

为Depot镜像仓库配置Docker认证

docker login registry.depot.dev -u x-token -p <depot-token>

Registry URL: registry.depot.dev/<project-id>:<tag>

镜像仓库地址：registry.depot.dev/<project-id>:<tag>

undefined

undefined

Special Output Formats

特殊输出格式

bash

undefined

bash

undefined

estargz (lazy-pulling for faster container startup)

estargz（懒加载，加快容器启动速度）

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)

zstd压缩（加快Fargate/K8s启动速度）

depot build --output type=image,name=repo/image:tag,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true,push=true .

undefined

depot build --output type=image,name=repo/image:tag,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true,push=true .

undefined