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/](https://kamal-deploy.org/docs/configuration/builder-examples/) for more information.

## Builder options

Options go under the builder key in the root configuration.

```yaml
builder:
```

## Arch

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

Allowed values are `amd64` and `arm64`:

```yaml
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.

```yaml
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:

```yaml
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/](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/use-project-toml/) for more information.

```yaml
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:

```yaml
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.

```yaml
context: .
```

## Dockerfile

The Dockerfile to use for building, defaults to `Dockerfile`:

```yaml
dockerfile: Dockerfile.production
```

## Build target

If not set, then the default target is used:

```yaml
target: production
```

## Build arguments

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

```yaml
args:
  ENVIRONMENT: production
```

## Referencing build arguments

```shell
ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION-slim as base
```

## Build secrets

Values are read from `.dash/secrets`:

```yaml
secrets:
  - SECRET1
  - SECRET2
```

## Referencing build secrets

```shell
# 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:

```yaml
ssh: default=$SSH_AUTH_SOCK
```

## Driver

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

```yaml
driver: docker
```

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

```yaml
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.

```yaml
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.

```yaml
sbom: true
```

> **Note:** 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.