Skip to content

usage-guide.md

Latest commit

 

History

History
255 lines (196 loc) · 7.41 KB

usage-guide.md

File metadata and controls

255 lines (196 loc) · 7.41 KB

Usage Guide

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

Table of Contents

Binary Location

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

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

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

Commands Overview

os-image-composer build         # Build an image from a template
os-image-composer validate      # Validate a template without building
os-image-composer inspect       # Inspect a raw image's structure
os-image-composer compare       # Compare two images
os-image-composer cache clean   # Manage cached artifacts
os-image-composer config        # Manage configuration (init, show)
os-image-composer version       # Display version info
os-image-composer --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

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

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

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

# Override config settings with flags
sudo -E ./os-image-composer 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/os-image-composer /tmp/os-image-composer/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:

./os-image-composer 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
./os-image-composer config init

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

# Use a specific configuration file
./os-image-composer --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/os-image-composer
work_dir ./workspace /tmp/os-image-composer

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
./os-image-composer install-completion

# Or specify a shell: bash, zsh, fish, powershell
./os-image-composer 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