Builder

The builder configuration controls how the application is built with docker build.

See Builder examples for more information.

Builder options

Options go under the builder key in the root configuration.

builder:

Arch

The architectures to build for — you can set an array or just a single value.

Allowed values are amd64 and arm64:

  arch:
    - amd64

Remote

The connection string for a remote builder. If supplied, Kamal will use this for builds that do not match the local architecture of the deployment host.

  remote: ssh://docker@docker-builder

Local

If set to false, Kamal will always use the remote builder even when building the local architecture.

Defaults to true:

  local: true

Buildpack configuration

The build configuration for using pack to build a Cloud Native Buildpack image.

For additional buildpack customization options you can create a project descriptor file(project.toml) that the Pack CLI will automatically use. See https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/use-project-toml/ for more information.

  pack:
    builder: heroku/builder:24
    buildpacks:
      - heroku/ruby
      - heroku/procfile

Builder cache

The type must be either ‘gha’ or ‘registry’.

The image is only used for registry cache and is not compatible with the Docker driver:

  cache:
    type: registry
    options: mode=max
    image: kamal-app-build-cache

Build context

If this is not set, then a local Git clone of the repo is used. This ensures a clean build with no uncommitted changes.

To use the local checkout instead, you can set the context to ., or a path to another directory.

  context: .

Dockerfile

The Dockerfile to use for building, defaults to Dockerfile:

  dockerfile: Dockerfile.production

Build target

If not set, then the default target is used:

  target: production

Build arguments

Any additional build arguments, passed to docker build with --build-arg <key>=<value>:

  args:
    ENVIRONMENT: production

Referencing build arguments

ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION-slim as base

Build secrets

Values are read from .kamal/secrets:

  secrets:
    - SECRET1
    - SECRET2

Referencing build secrets

# 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

SSH

SSH agent socket or keys to expose to the build:

  ssh: default=$SSH_AUTH_SOCK

Driver

The build driver to use, defaults to docker-container:

  driver: docker

If you want to use Docker Build Cloud (https://www.docker.com/products/build-cloud/), you can set the driver to:

  driver: cloud org-name/builder-name

Provenance

It is used to configure provenance attestations for the build result. The value can also be a boolean to enable or disable provenance attestations.

  provenance: mode=max

SBOM (Software Bill of Materials)

It is used to configure SBOM generation for the build result. The value can also be a boolean to enable or disable SBOM generation.

  sbom: true