OS Image Composer#

OS Image Composer is a command-line tool for building custom, bootable Linux images from pre-built packages. Define your requirements in a YAML template, run one command to get a RAW image ready to deploy (ISO installers require an extra step; see the Installation Guide).

Supported distributions: Azure Linux (azl3), Edge Microvisor Toolkit (emt3), Wind River eLxr (elxr12), Ubuntu (ubuntu24), and Red Hat-compatible distributions (rcd10).

Quick Start#

# 1. Clone and build (requires Go 1.24+)
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

# 2. Install prerequisites
sudo apt install systemd-ukify mmdebstrap
# Or run it directly:
go run ./cmd/os-image-composer --help

# 3. Compose an image
sudo -E ./os-image-composer build image-templates/azl3-x86_64-edge-raw.yml

For build options (Earthly, Debian package) and prerequisite details, see the Installation Guide.

Guides#

Guide	Description
Installation Guide	Build methods, Debian packaging, prerequisites
Usage Guide	CLI commands, configuration, build output, shell completion
CLI Reference	Complete command-line specification
Image Templates	Template structure, variables, best practices
Build Process	Pipeline stages, caching, troubleshooting
Architecture	System design and component overview

Tutorials#

Tutorial	Description
Prerequisites	Manual ukify and mmdebstrap installation
Secure Boot	Configuring secure boot for images
Configure Users	Adding users to images
Custom Build Actions	Pre/post-build scripts
Multiple Repos	Using multiple package repositories

Get Help#

Run os-image-composer --help (using the binary path from your install method)
Start a discussion
Troubleshoot build issues

Contribute#

License#