Docker Builder Strategies

Relevant source files

The following files were used as context for generating this wiki page:

• lib/kamal/cli/build.rb
• lib/kamal/commands/builder/base.rb
• lib/kamal/configuration.rb
• test/commands/builder_test.rb
• lib/kamal/cli/main.rb
• lib/kamal/utils.rb

Docker Builder Strategies in Kamal define how application images are constructed, tagged, and pushed to a registry. These strategies allow for local builds, remote builds via SSH, or hybrid approaches that combine multiple architectures. By leveraging Docker Buildx, Kamal provides a flexible interface to handle diverse infrastructure requirements, ranging from single-machine deployments to multi-arch cloud environments.

The builder system is integrated into the core deployment lifecycle, ensuring that images are validated with proper service labels before being pulled to target servers. It supports features such as build caching (e.g., GitHub Actions cache), secret interpolation during build-time, and port forwarding for local registries accessed by remote builders.

Builder Architecture and Logic

The builder logic is centered around the Kamal::Commands::Builder suite, which dynamically selects a strategy based on the deploy.yml configuration. The base implementation provides common functionality for cleaning images, pulling images, and generating build commands.

Strategy Selection Logic

Kamal selects the builder strategy based on the arch, remote, and local settings in the configuration:

• Local Strategy: Used by default when targeting the host's architecture.
• Remote Strategy: Used when a remote SSH host is specified and local building is disabled or incompatible.
• Hybrid Strategy: Activated when multiple architectures (e.g., amd64 and arm64) are specified and a remote builder is provided.
• Cloud Strategy: Utilizes specialized drivers like cloud for managed builder services.

Sources: test/commands/builder_test.rb:10-45, lib/kamal/commands/builder/base.rb:1-15

Core Components Diagram

This diagram illustrates the relationship between the CLI, the Configuration, and the Builder Command generator.

The diagram shows how the build command is derived from specific builder implementations managed by the configuration.
Sources: lib/kamal/cli/build.rb:5-15, lib/kamal/configuration.rb:75-80, lib/kamal/commands/builder/base.rb:5-10

Build Process Flow

The build process is executed via the deliver or push commands. It involves dependency checks, registry logins, and the execution of the Docker Buildx command.

Build and Push Sequence

The following sequence details the steps taken when a user executes a build delivery.

This sequence ensures that the environment is prepared and hooks are executed before the actual image construction begins.
Sources: lib/kamal/cli/build.rb:10-50, lib/kamal/commands/builder/base.rb:17-28

Configuration Options

Builders are configured within the builder block of the deploy.yml. These settings control the environment, performance, and output of the build process.

Option	Type	Description
arch	Array/String	Targeted CPU architectures (e.g., amd64, arm64).
remote	String	SSH connection string for remote builds (e.g., ssh://user@host).
local	Boolean	Whether to allow building on the local machine. Defaults to true.
cache	Hash	Configuration for build caching (e.g., type: gha).
args	Hash	Build arguments passed to Docker via --build-arg.
secrets	Array	List of secret keys to be passed as build secrets.
dockerfile	String	Path to the Dockerfile. Defaults to Dockerfile.
provenance	Boolean/String	Configures build provenance attestation.
sbom	Boolean	Enables or disables Software Bill of Materials generation.

Sources: lib/kamal/configuration.rb:250-280, test/commands/builder_test.rb:100-150, lib/kamal/commands/builder/base.rb:55-80

Specialized Builder Functions

Image Validation

Kamal enforces that built images contain a service label matching the configuration. This prevents accidental deployment of incorrect images.

def validate_image
  pipe \
    docker(:inspect, "-f", "'{{ .Config.Labels.service }}'", config.absolute_image),
    any(
      [ :grep, "-x", config.service ],
      "(echo \"Image #{config.absolute_image} is missing the 'service' label\" && exit 1)"
    )
end

Sources: lib/kamal/commands/builder/base.rb:43-50

Local Registry Support

When using a local registry (e.g., localhost:5000), the builder must handle network visibility. For docker-container drivers, Kamal adds --driver-opt network=host to ensure the builder can reach the host-mapped registry port.
Sources: test/commands/builder_test.rb:215-230, lib/kamal/commands/builder/base.rb:100-105

SSH Port Forwarding

If a remote builder is used with a local registry, Kamal establishes a secure tunnel to allow the remote builder to push the image back to the local machine.

def forward_local_registry_port_for_remote_builder(&block)
  if KAMAL.builder.remote?
    remote_uri = URI(KAMAL.config.builder.remote)
    forward_local_registry_port([ remote_uri.host ], **remote_builder_ssh_options(remote_uri), &block)
  else
    yield
  end
end

Sources: lib/kamal/cli/build.rb:162-170

Summary

Docker Builder Strategies in Kamal provide a robust abstraction over Docker Buildx, supporting local, remote, and hybrid workflows. By integrating validation, secret handling, and automated registry management, the builder ensures that images are consistently produced and ready for deployment across diverse server architectures.