Configuration

Builder

How the image is built — arch, remote builders, args, secrets, and caching.

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

See https://kamal-deploy.org/docs/configuration/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, dash 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, dash 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 .dash/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

Generated from the gem's lib/dash/configuration/docs/builder.yml — the same reference dash docs builder prints in your terminal, so this page always matches your installed version.