Crate zlayer_builder 

ZLayer Builder - Dockerfile parsing, ZImagefile support, and buildah command generation

This crate provides functionality for parsing Dockerfiles (and ZImagefiles), converting them into buildah commands for container image building. It is designed to be used as part of the ZLayer container orchestration platform.

Architecture

The crate is organized into several modules:

• dockerfile: Types and parsing for Dockerfile content
• buildah: Command generation and execution for buildah
• builder: High-level ImageBuilder API for orchestrating builds
• zimage: ZImagefile (YAML-based) parsing and Dockerfile conversion
• tui: Terminal UI for build progress visualization
• templates: Runtime templates for common development environments
• error: Error types for the builder subsystem

Quick Start with ImageBuilder

The recommended way to build images is using the ImageBuilder API:

use zlayer_builder::{ImageBuilder, Runtime};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build from a Dockerfile
    let image = ImageBuilder::new("./my-app").await?
        .tag("myapp:latest")
        .tag("myapp:v1.0.0")
        .build()
        .await?;

    println!("Built image: {}", image.image_id);
    Ok(())
}

Using Runtime Templates

Build images without writing a Dockerfile using runtime templates:

use zlayer_builder::{ImageBuilder, Runtime};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Auto-detect runtime from project files, or specify explicitly
    let image = ImageBuilder::new("./my-node-app").await?
        .runtime(Runtime::Node20)
        .tag("myapp:latest")
        .build()
        .await?;

    Ok(())
}

Building from a ZImagefile

ZImagefiles are a YAML-based alternative to Dockerfiles. The builder auto-detects a file named ZImagefile in the context directory, or you can point to one explicitly with ImageBuilder::zimagefile:

use zlayer_builder::ImageBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let image = ImageBuilder::new("./my-app").await?
        .zimagefile("./my-app/ZImagefile")
        .tag("myapp:latest")
        .build()
        .await?;

    Ok(())
}

ZImagefiles support four build modes: runtime template shorthand, single-stage (base + steps), multi-stage (stages map), and WASM. See the zimage module for the full type definitions.

Low-Level API

For more control, you can use the low-level Dockerfile parsing and buildah command generation APIs directly:

use zlayer_builder::{Dockerfile, BuildahCommand, BuildahExecutor};

// Parse a Dockerfile
let dockerfile = Dockerfile::parse(r#"
    FROM alpine:3.18
    RUN apk add --no-cache curl
    COPY . /app
    WORKDIR /app
    CMD ["./app"]
"#)?;

// Get the final stage
let stage = dockerfile.final_stage().unwrap();

// Create buildah commands for each instruction
let executor = BuildahExecutor::new()?;

// Create a working container from the base image
let from_cmd = BuildahCommand::from_image(&stage.base_image.to_string_ref());
let output = executor.execute_checked(&from_cmd).await?;
let container_id = output.stdout.trim();

// Execute each instruction
for instruction in &stage.instructions {
    let cmds = BuildahCommand::from_instruction(container_id, instruction);
    for cmd in cmds {
        executor.execute_checked(&cmd).await?;
    }
}

// Commit the container to create an image
let commit_cmd = BuildahCommand::commit(container_id, "myimage:latest");
executor.execute_checked(&commit_cmd).await?;

// Clean up the working container
let rm_cmd = BuildahCommand::rm(container_id);
executor.execute(&rm_cmd).await?;

Features

ImageBuilder (High-Level API)

The ImageBuilder provides a fluent API for:

• Building from Dockerfiles or runtime templates
• Multi-stage builds with target stage selection
• Build arguments (ARG values)
• Image tagging and registry pushing
• TUI progress updates via event channels

Dockerfile Parsing

The crate supports parsing standard Dockerfiles with:

• Multi-stage builds with named stages
• All standard Dockerfile instructions (FROM, RUN, COPY, ADD, ENV, etc.)
• ARG/ENV variable expansion with default values
• Global ARGs (before first FROM)

Buildah Integration

Commands are generated for buildah, a daemon-less container builder:

• Container creation from images or scratch
• Running commands (shell and exec form)
• Copying files (including from other stages)
• Configuration (env, workdir, entrypoint, cmd, labels, etc.)
• Committing containers to images
• Image tagging and pushing

Runtime Templates

Pre-built templates for common development environments:

• Node.js 20/22 (Alpine-based, production optimized)
• Python 3.12/3.13 (Slim Debian-based)
• Rust (Static musl binary)
• Go (Static binary)
• Deno and Bun

Variable Expansion

Full support for Dockerfile variable syntax:

• $VAR and ${VAR} - Simple variable reference
• ${VAR:-default} - Default if unset or empty
• ${VAR:+alternate} - Alternate if set and non-empty
• ${VAR-default} - Default only if unset
• ${VAR+alternate} - Alternate if set (including empty)

Re-exports

pub use buildah::current_platform;

pub use buildah::install_instructions;

pub use buildah::is_platform_supported;

pub use buildah::BuildahCommand;

pub use buildah::BuildahExecutor;

pub use buildah::BuildahInstallation;

pub use buildah::BuildahInstaller;

pub use buildah::CommandOutput;

pub use buildah::InstallError;

pub use builder::BuildOptions;

pub use builder::BuiltImage;

pub use builder::ImageBuilder;

pub use builder::RegistryAuth;

pub use dockerfile::expand_variables;

pub use dockerfile::AddInstruction;

pub use dockerfile::ArgInstruction;

pub use dockerfile::CopyInstruction;

pub use dockerfile::Dockerfile;

pub use dockerfile::EnvInstruction;

pub use dockerfile::ExposeInstruction;

pub use dockerfile::ExposeProtocol;

pub use dockerfile::HealthcheckInstruction;

pub use dockerfile::ImageRef;

pub use dockerfile::Instruction;

pub use dockerfile::RunInstruction;

pub use dockerfile::ShellOrExec;

pub use dockerfile::Stage;

pub use dockerfile::VariableContext;

pub use error::BuildError;

pub use error::Result;

pub use templates::detect_runtime;

pub use templates::detect_runtime_with_version;

pub use templates::get_template;

pub use templates::get_template_by_name;

pub use templates::list_templates;

pub use templates::resolve_runtime;

pub use templates::Runtime;

pub use templates::RuntimeInfo;

pub use tui::BuildEvent;

pub use tui::BuildTui;

pub use tui::InstructionStatus;

pub use tui::PlainLogger;

pub use pipeline::parse_pipeline;

pub use pipeline::PipelineDefaults;

pub use pipeline::PipelineExecutor;

pub use pipeline::PipelineImage;

pub use pipeline::PipelineResult;

pub use pipeline::PushConfig;

pub use pipeline::ZPipeline;

Modules

buildah

Buildah command generation and execution

builder

ImageBuilder - High-level API for building container images

dockerfile

Dockerfile parsing and representation

error

Builder error types

pipeline

Pipeline build support for building multiple images from a manifest

templates

Runtime templates for ZLayer builder

tui

Terminal UI for build progress visualization

wasm_builder

WebAssembly component builder with multi-language support

zimage

ZImagefile - YAML-based image build format