Skip to content

README.md

Latest commit

 

History

History
134 lines (97 loc) · 5.15 KB

README.md

File metadata and controls

134 lines (97 loc) · 5.15 KB

OS Image Composer

License Go Lint Check Unit and Coverage Security zizmor 🌈 Fuzz test Trivy scan

A command-line tool for building custom Linux images from pre-built packages. Define what you need in a YAML template, run one command, and get a bootable RAW or ISO image.

Supported Distributions

OS Distribution Architecture
Azure Linux azl3 x86_64
Edge Microvisor Toolkit emt3 x86_64
Red Hat Compatible Distro rcd10 x86_64
Wind River eLxr elxr12 x86_64
Ubuntu ubuntu24 x86_64

Quick Start

1. Build the Tool

Requires Go 1.24+. Recommended Ubuntu 24.04

git clone https://github.com/open-edge-platform/os-image-composer.git
cd os-image-composer
go build -buildmode=pie -ldflags "-s -w" ./cmd/os-image-composer

This produces ./os-image-composer in the repo root.

Alternatively, use Earthly for reproducible production builds (output: ./build/os-image-composer):

earthly +build

See the Installation Guide for Debian package installation, prerequisite setup, and other options.

2. Install Prerequisites

# Required for image composition
sudo apt install systemd-ukify mmdebstrap

Specific versions and alternative installation methods are documented in the Installation Guide.

3. Compose an Image

# If built with go build:
sudo -E ./os-image-composer build image-templates/azl3-x86_64-edge-raw.yml

# If built with earthly:
sudo -E ./build/os-image-composer build image-templates/azl3-x86_64-edge-raw.yml

That's it. The output image will be under ./workspace/<os>-<dist>-<arch>/imagebuild/<config-name>/ (or /tmp/os-image-composer/... if installed via the Debian package).

4. Validate a Template (Optional)

Check a template for errors before starting a build:

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

Image Templates

Templates are YAML files that define what goes into your image — OS, packages, kernel, partitioning, and more. Ready-to-use examples are in image-templates/.

A minimal template looks like this:

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

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

systemConfig:
  name: edge
  packages:
    - openssh-server
    - ca-certificates
  kernel:
      version: "6.12"
      cmdline: "quiet"

To learn about template structure, variable substitution, and best practices, see Creating and Reusing Image Templates.

Documentation

Guide Description
Installation Guide Build options, Debian packaging, prerequisites
Usage Guide CLI commands, configuration, shell completion
CLI Reference Complete command-line specification
Image Templates Template system and customization
Build Process How image composition works, troubleshooting
Secure Boot Configuring secure boot for images
Multiple Repos Using multiple package repositories

Get Help

Contribute

License

MIT