Builder

Builder #

The builder configuration controls how the application is built with docker build or docker buildx build. If no configuration is specified, Kamal will:

  1. Create a buildx context called kamal-<service>-multiarch
  2. Use docker buildx build to build a multiarch image for linux/amd64,linux/arm64 with that context

See Builder examples for more information.

Builder options #

Options go under the builder key in the root configuration:

builder:

Multiarch #

Enables multiarch builds, defaults to true:

  multiarch: false

Local configuration #

The build configuration for local builds, only used if multiarch is enabled (the default).

If there is no remote configuration, by default we build for amd64 and arm64. If you only want to build for one architecture, you can specify it here. The docker socket is optional and uses the default docker host socket when not specified:

  local:
    arch: amd64
    host: /var/run/docker.sock

Remote configuration #

The build configuration for remote builds, also only used if multiarch is enabled. The arch is required and can be either amd64 or arm64:

  remote:
    arch: arm64
    host: ssh://docker@docker-builder

Builder cache #

The type must be either ‘gha’ or ‘registry’. The image is only used for registry cache:

  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 the environment:

  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