Skip to content

usage-guide.md

Latest commit

 

History

History
267 lines (207 loc) · 7.92 KB

usage-guide.md

File metadata and controls

267 lines (207 loc) · 7.92 KB

Usage Guide

A practical guide for common ICT workflows. For the complete command reference, see the CLI Specification.

Table of Contents

Binary Location

The path to the image-composer-tool binary depends on how you built or installed it:

Build method Binary path
go build ./cmd/image-composer-tool ./image-composer-tool
earthly +build ./build/image-composer-tool
Debian package image-composer-tool (installed to /usr/local/bin/)

The examples below use ./image-composer-tool (the go build location). Substitute the path that matches your setup.

Commands Overview

image-composer-tool build         # Build an image from a template
image-composer-tool validate      # Validate a template without building
image-composer-tool inspect       # Inspect a raw image's structure
image-composer-tool compare       # Compare two images
image-composer-tool ai            # AI-powered template generation (RAG)
image-composer-tool cache clean   # Manage cached artifacts
image-composer-tool config        # Manage configuration (init, show)
image-composer-tool version       # Display version info
image-composer-tool --help        # Show all commands and options

For the full details on every command — including inspect, compare, and cache — see the CLI Specification.

Building an Image

ISO images require the live-installer binary. Build it before starting an ISO build:

go build -buildmode=pie -o ./build/live-installer ./cmd/live-installer

If you use earthly +build, both binaries are built automatically. See the Installation Guide for details.

# go build — binary is in the repo root
sudo -E ./image-composer-tool build image-templates/azl3-x86_64-edge-raw.yml

# earthly +build — binary is in ./build/
sudo -E ./build/image-composer-tool build image-templates/azl3-x86_64-edge-raw.yml

# Debian package — binary is on PATH
sudo image-composer-tool build /usr/share/image-composer-tool/examples/azl3-x86_64-edge-raw.yml

# Override config settings with flags
sudo -E ./image-composer-tool build --workers 16 --cache-dir /tmp/cache image-templates/azl3-x86_64-edge-raw.yml

Common flags: --workers, --cache-dir, --work-dir, --verbose, --dotfile, --config, --log-level. See the full build flag reference for descriptions and additional flags like --system-packages-only.

Build Output

After the image finishes building, the output is placed under the configured work_dir. The full path follows this pattern:

<work_dir>/<os>-<dist>-<arch>/imagebuild/<system-config-name>/

The default work_dir depends on how you installed the tool:

Install method Default work_dir Example output path
Cloned repo ./workspace (relative to repo root) ./workspace/azure-linux-azl3-x86_64/imagebuild/edge/
Debian package /tmp/image-composer-tool /tmp/image-composer-tool/azure-linux-azl3-x86_64/imagebuild/edge/

You can override it with --work-dir or by setting work_dir in your configuration file.

Validating a Template

Check a template for errors before starting a build:

./image-composer-tool validate image-templates/azl3-x86_64-edge-raw.yml

Configuration

The tool uses a layered configuration: config file values are overridden by command-line flags. A config file is auto-discovered from several standard locations (current directory, home directory, /etc/), or you can specify one explicitly with --config.

# Create a default configuration file
./image-composer-tool config init

# Show the active configuration
./image-composer-tool config show

# Use a specific configuration file
./image-composer-tool --config /path/to/config.yaml build template.yml

Key settings:

Setting Default (cloned repo) Default (Debian pkg)
workers 8 8
cache_dir ./cache /var/cache/image-composer-tool
work_dir ./workspace /tmp/image-composer-tool

For the complete search order and all configuration fields, see Configuration Files in the CLI Specification.

Operations Requiring Sudo

The build command requires sudo because it performs system-level operations: creating loop devices, mounting filesystems, setting up chroot environments, installing packages, and configuring bootloaders.

Always run builds with sudo -E to preserve your environment variables (such as $PATH and proxy settings).

Shell Completion

# Auto-detect shell and install completion
./image-composer-tool install-completion

# Or specify a shell: bash, zsh, fish, powershell
./image-composer-tool install-completion --shell bash

After installing, reload your shell configuration (e.g., source ~/.bashrc). For per-shell activation steps and manual completion script generation, see the Install-Completion Command reference.

Template Examples

Templates are YAML files that define the requirements for an image build. For the full template system documentation, see Creating and Reusing Image Templates.

The image-templates/ directory contains ready-to-use examples for all supported distributions and image types.

Minimal Edge Device

image:
  name: minimal-edge
  version: "1.0.0"

target:
  os: azure-linux
  dist: azl3
  arch: x86_64
  imageType: raw

systemConfig:
  name: minimal
  description: Minimal edge device configuration
  packages:
    - openssh-server
    - ca-certificates
  kernel:
    version: "6.12"
    cmdline: "quiet"

Development Environment

image:
  name: dev-environment
  version: "1.0.0"

target:
  os: azure-linux
  dist: azl3
  arch: x86_64
  imageType: raw

systemConfig:
  name: development
  description: Development environment with tools
  packages:
    - openssh-server
    - git
    - docker-ce
    - vim
    - curl
    - wget
    - python3
  kernel:
    version: "6.12"
    cmdline: "quiet splash"

Edge Microvisor Toolkit

image:
  name: emt-edge-device
  version: "1.0.0"

target:
  os: edge-microvisor-toolkit
  dist: emt3
  arch: x86_64
  imageType: raw

systemConfig:
  name: edge
  description: Edge Microvisor Toolkit configuration
  packages:
    - cloud-init
    - rsyslog
  kernel:
    version: "6.12"
    cmdline: "console=ttyS0,115200 console=tty0 loglevel=7"

Related Documentation