构建器示例

使用远程构建器进行原生多架构

如果你在 ARM64（如 Apple Silicon）上进行开发，但要在 AMD64（x86 64 位）上进行部署，则可以使用多架构镜像。默认情况下，Kamal 将通过 QEMU 仿真设置一个执行此操作的本地 buildx 配置。但这可能非常慢，尤其是在首次构建时。

如果你想通过使用远程 AMD64 主机在本地构建镜像的 AMD64 部分，而在本地构建 ARM64 部分，从而加快此流程，可以使用构建器选项

builder:
  local:
    arch: arm64
    host: unix:///Users/<%= `whoami`.strip %>/.docker/run/docker.sock
  remote:
    arch: amd64
    host: ssh://[email protected]

注意：你必须在用作构建器的远程主机上运行 Docker。此实例只应与使用相同注册表和凭据的用户进行构建时共享。

使用远程构建器进行单架构

如果你在 ARM64（如 Apple Silicon）上进行开发，想在 AMD64（x86 64 位）上部署，但不需在本地（或其他 ARM64 主机上）运行该镜像，则可以配置仅针对 AMD64 的远程构建器。这比使用多架构构建要快一些，因为无需在本地构建。

builder:
  remote:
    arch: amd64
    host: ssh://[email protected]

使用本地构建器进行单架构

如果你在多个架构上进行开发，始终在一个特定的架构上进行部署（例如 AMD64），并想在本地构建，则可以配置一个没有主机的远程构建器。Kamal 将使用一个本地 buildx 实例构建镜像。

builder:
  remote:
    arch: amd64

在不需要多架构时使用原生构建器

如果你在与你进行部署的主机相同的架构上进行开发，则可以通过放弃多架构和远程构建来加快构建速度

builder:
  multiarch: false

如果你从与部署服务器具有相同架构的 CI 服务器运行 Kamal，则这也是一个不错的选择。

在构建时使用不同的 Dockerfile 或上下文

如果你需要将不同的 Dockerfile 或上下文传递给 build 命令（例如，如果你使用的是单一仓库或你有不同的 Dockerfile），则可以在构建器选项中执行此操作

# Use a different Dockerfile
builder:
  dockerfile: Dockerfile.xyz

# Set context
builder:
  context: ".."

# Set Dockerfile and context
builder:
  dockerfile: "../Dockerfile.xyz"
  context: ".."

使用多阶段构建器缓存

Docker 多阶段构建缓存可以大幅度加快你的构建速度。目前，Kamal 仅支持使用 GHA 缓存或注册表缓存

# Using GHA cache
builder:
  cache:
    type: gha

# Using Registry cache
builder:
  cache:
    type: registry

# Using Registry cache with different cache image
builder:
  cache:
    type: registry
    # default image name is <image>-build-cache
    image: application-cache-image

# Using Registry cache with additional cache-to options
builder:
  cache:
    type: registry
    options: mode=max,image-manifest=true,oci-mediatypes=true

GHA 缓存配置

要在 GitHub action 工作流中使其工作，你需要设置 buildx 并公开缓存的身份验证配置。

示例设置（在 .github/workflows/sample-ci.yml 中）

- name: Set up Docker Buildx for cache
  uses: docker/setup-buildx-action@v3

- name: Expose GitHub Runtime for cache
  uses: crazy-max/ghaction-github-runtime@v3

正确设置后，您应在 GHA 工作流动作缓存部分看到缓存条目/条目。

有关构建缓存优化的更多见解，请查看 Docker 官方网站上的文档：https://docs.dockerd.com.cn/build/cache/。

使用构建秘密为新映像

一些映像需要在构建期间传递一个秘密，例如 GITHUB_TOKEN，以访问私有 gem 存储库。可以通过将该秘密保存在 ENV 中，然后在构建器配置中引用它来完成此操作

builder:
  secrets:
    - GITHUB_TOKEN

然后可以在 Dockerfile 中引用此构建秘密

# Copy Gemfiles
COPY Gemfile Gemfile.lock ./

# Install dependencies, including private repositories via access token (then remove bundle cache with exposed GITHUB_TOKEN)
RUN --mount=type=secret,id=GITHUB_TOKEN \
  BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \
  bundle install && \
  rm -rf /usr/local/bundle/cache

为新映像配置构建参数

还可以配置非机密的构建参数

builder:
  args:
    RUBY_VERSION: 3.2.0

然后可以在 Dockerfile 中使用此构建参数

ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION-slim as base