Builders

The builder configuration controls how your Docker images are built and where they are built. Asantiya supports both local and remote building, multi-architecture builds, and custom build configurations.

Overview

Builders allow you to:

• Build locally for development and testing
• Build remotely for production deployments
• Support multiple architectures (amd64, arm64)
• Use custom Dockerfiles for different environments
• Optimize build performance with caching and parallel builds

Basic Configuration

builder:
  local: true
  arch: amd64
  dockerfile: Dockerfile

Configuration Options

Local Building

The local field determines whether to build locally or remotely.

builder:
  local: true  # Build locally (default)

When to use local building:

• Development and testing
• Quick iterations
• When you have Docker installed locally
• For simple applications

When to use remote building:

• Production deployments
• When local machine lacks resources
• For multi-architecture builds
• When deploying to different architectures

Architecture Support

The arch field specifies the target architecture for the build.

builder:
  arch: amd64  # x86_64 architecture

Supported architectures:

• amd64 - x86_64 (Intel/AMD 64-bit)
• arm64 - ARM 64-bit (Apple Silicon, ARM servers)

Multi-architecture builds:

builder:
  arch:
    - amd64
    - arm64

Remote Builder

The remote field specifies a remote Docker builder for builds that don’t match the local architecture.

builder:
  local: false
  remote: ssh://docker@docker-builder

Remote builder formats:

• ssh://user@host - SSH connection
• ssh://user@host:port - SSH with custom port
• tcp://host:port - TCP connection
• unix:///path/to/socket - Unix socket

Custom Dockerfile

The dockerfile field specifies which Dockerfile to use for building.

builder:
  dockerfile: Dockerfile.production

Default: Uses Dockerfile in the project root if not specified.

Build Scenarios

Local Development

builder:
  local: true
  arch: amd64
  dockerfile: Dockerfile

Use case: Quick development iterations, testing locally.

Production Deployment

builder:
  local: false
  remote: ssh://docker@production-builder
  arch: amd64
  dockerfile: Dockerfile.production

Use case: Production deployments with optimized builds.

Architecture-Specific Builds

Asantiya supports building for a single architecture per configuration. For multi-architecture support, you’ll need to create separate configuration files for each architecture.

# For AMD64 architecture
builder:
  local: false
  remote: ssh://docker@amd64-builder
  arch: amd64
  dockerfile: Dockerfile

# For ARM64 architecture (separate config file)
builder:
  local: false
  remote: ssh://docker@arm64-builder
  arch: arm64
  dockerfile: Dockerfile

Use case: Supporting different architectures (Intel and Apple Silicon) with separate deployment configurations.

Environment-Specific Builds

For different environments, create separate configuration files with environment-specific builder settings.

Development Configuration (deploy.dev.yaml):

service: my-app-dev
image: my-app-dev
app_ports: "3000:3000"
host: false
 
builder:
  arch: amd64
  local: true
  dockerfile: Dockerfile.dev
  build_args:
    NODE_ENV: development

Staging Configuration (deploy.staging.yaml):

service: my-app-staging
image: my-app-staging
app_ports: "8080:80"
host: false
 
builder:
  arch: amd64
  local: false
  remote: ssh://docker@staging-builder
  dockerfile: Dockerfile.staging
  build_args:
    NODE_ENV: staging

Production Configuration (deploy.production.yaml):

service: my-app-prod
image: my-app-prod
app_ports: "80:80"
host: false
 
builder:
  arch: amd64
  local: false
  remote: ssh://docker@production-builder
  dockerfile: Dockerfile.production
  build_args:
    NODE_ENV: production

Advanced Configuration

Build Arguments

Pass build arguments to Docker build:

builder:
  local: true
  build_args:
    BUILD_ENV: production
    VERSION: 1.0.0
    NODE_ENV: production

For more build examples, check out the Examples section or refer to the CLI Reference for build-related commands.