Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mikronita/mikrom/llms.txt

Use this file to discover all available pages before exploring further.

mikrom-builder is the build engine for the Mikrom platform. It listens on NATS for build requests from mikrom-api, clones the target Git repository into a temporary workspace, detects the application stack (or falls back to a provided Dockerfile), builds an OCI-compliant container image using BuildKit, and pushes the result to the configured registry. Build logs and status updates are reported back over NATS so the dashboard and CLI can stream progress in real time.

​
Responsibilities

Git Cloning

Clones the source repository into an ephemeral workspace for each build. Supports authenticated and anonymous repositories.

Stack Detection

Auto-detects the application framework and selects the appropriate build strategy—Railpack for source-driven builds, or Dockerfile for explicit configurations.

OCI Image Build

Builds images using BuildKit. Supports both Dockerfile-based and Railpack source-driven build paths.

Registry Push

Pushes the built image to the configured OCI registry with optional authentication credentials.

NATS Integration

Receives build requests and reports build logs, metrics, and completion status back to mikrom-api over NATS.

Concurrency Control

Limits simultaneous builds with a configurable cap (MAX_CONCURRENT_BUILDS) to protect host resources.

​
Supported Application Stacks

mikrom-builder auto-detects the following stacks when no Dockerfile is present in the repository root. Detection uses Railpack’s heuristics:

Phoenix

Ruby on Rails

Django

Laravel

Go

Rust

JavaScript

Static

When a Dockerfile is present at the repository root, the builder uses it directly and skips stack detection. The Docker build path takes precedence over Railpack.

​
Build Pipeline

1

Build request arrives via NATS

mikrom-api publishes a build request to NATS containing the Git repository URL, branch or commit reference, and any build-time environment variables.
2

Repository cloned

The builder clones the repository into a temporary directory using git2. The workspace is cleaned up after the build completes or fails.
3

Build strategy selected

The builder checks for a Dockerfile at the repository root. If found, it is used directly. Otherwise, Railpack analyses the repository and generates a build plan for the detected stack.
4

Image built with BuildKit

The build is submitted to the BuildKit daemon configured in BUILDKIT_HOST. The builder uses the bollard crate (Docker API client) to drive the build and stream log output.
5

Image pushed to registry

The finished image is tagged and pushed to the registry specified in REGISTRY. If REGISTRY_USER and REGISTRY_PASS are set, authenticated pushes are used.
6

Status reported over NATS

Build completion (or failure) is reported back to mikrom-api over NATS. The API updates deployment state and forwards the result to the dashboard and CLI.

​
BuildKit Daemon

mikrom-builder requires a running BuildKit daemon. In local development, BuildKit is managed via Docker Compose. 
make up-buildkit      # Start the BuildKit container
make logs-buildkit    # Follow BuildKit logs
The builder connects to the daemon via the address in BUILDKIT_HOST: 
# Default (Docker Compose local dev)
BUILDKIT_HOST=docker-container://mikromrust-buildkit-1
In production, point BUILDKIT_HOST at the BuildKit daemon socket or address for your deployment environment.

​
Configuration

VariableDefaultDescription
NATS_URLnats://[::1]:4222NATS server URL for build request subscriptions
REGISTRYregistry.mikrom.spluca.org/mikromTarget OCI registry for pushed images
REGISTRY_URLalias for REGISTRYBackward-compatible environment name
REGISTRY_USER—Registry username for authenticated pushes
REGISTRY_PASS—Registry password for authenticated pushes
BUILDKIT_HOSTdocker-container://mikromrust-buildkit-1BuildKit daemon address
MAX_CONCURRENT_BUILDS2Maximum number of simultaneous builds
BUILD_STATE_TTL_SECS3600Retention window for build state (seconds)
BUILD_STATE_PATH/tmp/mikrom-builder-state.jsonPersistent build state file path
ENABLE_TELEMETRYtrueEnable OTLP export for traces and metrics

​
Build State Persistence

The builder persists build state to BUILD_STATE_PATH. This file survives process restarts, so in-flight build status is not lost if the service is restarted during a build. Build metrics are also exposed over NATS for querying by the scheduler and API: 
NATS subject: mikrom.builder.get_metrics

​
Stack

# mikrom-builder/Cargo.toml (key dependencies)
bollard      = "0.20.2"  # Docker / BuildKit API client
git2         = "0.21.0"  # Git repository cloning
async-nats   = "..."     # NATS build request subscriptions and status reporting
tokio        = "..."     # Async runtime
mikrom-proto = { path = "../mikrom-proto", features = ["telemetry"] }

​
Dockerfile

The builder ships a multi-stage Dockerfile for containerized deployments: 
# mikrom-builder/Dockerfile
docker build -f mikrom-builder/Dockerfile .

​
Local Development

make run-builder           # Start the builder (requires NATS and BuildKit)
make up-buildkit           # Start BuildKit daemon first
cargo run -p mikrom-builder
cargo nextest run -p mikrom-builder
make ci-smoke
make ci-fast
The ignored NATS integration tests are exercised by make ci-external-tests. These tests verify the full build-request-to-status-report loop and require a live NATS server.
When iterating on stack detection or build plan generation, use a small test repository with a known stack to verify that Railpack selects the expected build strategy before running the full CI suite.

Build docs developers (and LLMs) love

Get started for freeTalk to us